CUGL
Cornell University Game Library
Public Member Functions | Static Public Member Functions | List of all members
cugl::Pathname Class Reference

#include <CUPathname.h>

Public Member Functions

 Pathname (const Pathname &copy)
 
 Pathname (Pathname &&copy) noexcept
 
 Pathname (const std::string &path)
 
 Pathname (const char *path)
 
 Pathname (const std::string &parent, const std::string &child)
 
 Pathname (const char *parent, const std::string &child)
 
 Pathname (const std::string &parent, const char *child)
 
 Pathname (const char *parent, const char *child)
 
 Pathname (const Pathname &parent, const std::string &child)
 
 Pathname (const Pathname &parent, const char *child)
 
 ~Pathname ()
 
bool exists () const
 
bool isDirectory () const
 
bool isFile () const
 
bool isHidden () const
 
bool isAbsolute () const
 
std::string getName () const
 
std::string getPathname () const
 
std::string getParentName () const
 
Pathname getParentPath () const
 
std::string getAbsoluteName () const
 
Pathname getAbsolutePath () const
 
std::string getSuffix () const
 
std::string getVolume () const
 
std::vector< std::string > getComponents () const
 
std::vector< std::string > list () const
 
std::vector< std::string > list (const std::function< bool(const std::string &file)> &filter) const
 
std::vector< PathnamelistPaths () const
 
std::vector< PathnamelistPaths (const std::function< bool(const Pathname &path)> &filter) const
 
bool createFile ()
 
bool deleteFile ()
 
bool createDirectory ()
 
bool deleteDirectory ()
 
bool createPath ()
 
bool renameTo (const std::string &path)
 
bool renameTo (const char *path)
 
bool renameTo (const Pathname &dest)
 
bool canRead ()
 
bool canSearch ()
 
bool canWrite ()
 
bool setReadable (bool readable)
 
bool setReadable (bool readable, bool ownerOnly)
 
bool setReadOnly ()
 
bool setSearchable (bool searchable)
 
bool setSearchable (bool searchable, bool ownerOnly)
 
bool setWritable (bool writable)
 
bool setWritable (bool writable, bool ownerOnly)
 
size_t length () const
 
long lastModified () const
 
size_t getFreeSpace () const
 
size_t getAvailableSpace () const
 
size_t getTotalSpace () const
 
bool operator< (const Pathname &other) const
 
bool operator<= (const Pathname &other) const
 
bool operator> (const Pathname &other) const
 
bool operator>= (const Pathname &other) const
 
bool operator== (const Pathname &other) const
 
bool operator!= (const Pathname &other) const
 

Static Public Member Functions

static std::string getSeparator ()
 

Detailed Description

This class is abstract representation of file and directory pathnames.

Pathname strings are system-dependent. Path representation on Unix systems is very different from Window systems. This class provides a system independent way of referring to pathnames. It detects the current platform and converts the pathname to the correct format.

An abstract pathname has two components.

  1. An optional system-dependent prefix string, such as a disk-drive specifier, "/" for the UNIX root directory, or "\\\\" for a Microsoft Windows UNC pathname.
  2. A sequence of zero or more string names separated by a system-dependent path separator, such as "/" for UNIX systems or "\\" for Windows.

A pathname may either be absolute or relative. Absolute pathnames start with the optional prefix, and there is no more information necessary to locate the file that it denotes. A relative pathname, on the other hand, must be interpreted as the suffix of some other pathname. In CUGL, all relative names are resolve against the save directory ({

See also
Application::getSaveDirectory()}), as this is the only directory with both read and write access on all platforms.

When converted back to a string, Pathname objects never end in a path separator, even when they represent a directory.

Instances of Pathname are immutable. Once created, the pathname represented by a Pathname object will never change.

IMPORTANT: Never use a Pathname object to refer to an asset in the asset directory ({

See also
Application::getAssetDirectory()}). This is not guaranteed to be a proper directory, as the assets may be packaged together in a special read-only bundle (e.g. Android). Attempts to navigate this bundle like a directory will fail.

Constructor & Destructor Documentation

cugl::Pathname::Pathname ( const Pathname copy)

Creates a copy of the given pathname

This is the classic copy constructor. The previous pathname object is unaffected.

Parameters
copyThe pathname to copy
cugl::Pathname::Pathname ( Pathname &&  copy)
noexcept

Creates a copy of the given pathname

This is the classic move constructor. The data from the previous pathname object is merged with this object.

Parameters
copyThe pathname to copy
cugl::Pathname::Pathname ( const std::string &  path)

Creates a pathname for the given path

The specified path may be absolute or relative. Relative paths always refer to the save directory ({

See also
Application::getSaveDirectory()}), as this is the only cross-platform directory for reading and writing. If you wish to refer to any other directory, you must use an absolute path instead.
Parameters
pathThe path to represent
cugl::Pathname::Pathname ( const char *  path)
inline

Creates a pathname for the given path

The specified path may be absolute or relative. Relative paths always refer to the save directory ({

See also
Application::getSaveDirectory()}), as this is the only cross-platform directory for reading and writing. If you wish to refer to any other directory, you must use an absolute path instead.
Parameters
pathThe path to represent
cugl::Pathname::Pathname ( const std::string &  parent,
const std::string &  child 
)

Creates a pathname for the given parent and child

The parent should refer to a directory, while the child may either be a directory or a file. The directory specified by the parent may be absolute or relative. Relative paths always refer to the save directory ({

See also
Application::getSaveDirectory()}), as this is the only cross- platform directory for reading and writing. If you wish to refer to any other directory, you must use an absolute path instead.

The child should have no path separators in it. If it does, this will produce an error.

Parameters
parentThe parent directory
childThe child file or directory
cugl::Pathname::Pathname ( const char *  parent,
const std::string &  child 
)
inline

Creates a pathname for the given parent and child

The parent should refer to a directory, while the child may either be a directory or a file. The directory specified by the parent may be absolute or relative. Relative paths always refer to the save directory ({

See also
Application::getSaveDirectory()}), as this is the only cross- platform directory for reading and writing. If you wish to refer to any other directory, you must use an absolute path instead.

The child should have no path separators in it. If it does, this will produce an error.

Parameters
parentThe parent directory
childThe child file or directory
cugl::Pathname::Pathname ( const std::string &  parent,
const char *  child 
)
inline

Creates a pathname for the given parent and child

The parent should refer to a directory, while the child may either be a directory or a file. The directory specified by the parent may be absolute or relative. Relative paths always refer to the save directory ({

See also
Application::getSaveDirectory()}), as this is the only cross- platform directory for reading and writing. If you wish to refer to any other directory, you must use an absolute path instead.

The child should have no path separators in it. If it does, this will produce an error.

Parameters
parentThe parent directory
childThe child file or directory
cugl::Pathname::Pathname ( const char *  parent,
const char *  child 
)
inline

Creates a pathname for the given parent and child

The parent should refer to a directory, while the child may either be a directory or a file. The directory specified by the parent may be absolute or relative. Relative paths always refer to the save directory ({

See also
Application::getSaveDirectory()}), as this is the only cross- platform directory for reading and writing. If you wish to refer to any other directory, you must use an absolute path instead.

The child should have no path separators in it. If it does, this will produce an error.

Parameters
parentThe parent directory
childThe child file or directory
cugl::Pathname::Pathname ( const Pathname parent,
const std::string &  child 
)

Creates a pathname for the given parent and child

The parent pathname should refer to a directory, while the child may either be a directory or a file. The child should have no path separators in it. If it does, this will produce an error.

Parameters
parentThe parent directory
childThe child file or directory
cugl::Pathname::Pathname ( const Pathname parent,
const char *  child 
)
inline

Creates a pathname for the given parent and child

The parent pathname should refer to a directory, while the child may either be a directory or a file. The child should have no path separators in it. If it does, this will produce an error.

Parameters
parentThe parent directory
childThe child file or directory
cugl::Pathname::~Pathname ( )
inline

Deletes this pathname, releasing all resources

Member Function Documentation

bool cugl::Pathname::canRead ( )

Returns true if the application can read the file for this pathname.

This method uses the access() POSIX method. Therefore, it does not assume that this application is the file owner, and correctly determines the file access.

Returns
true if the application can read the file for this pathname.
bool cugl::Pathname::canSearch ( )

Returns true if the application can execute the file for this pathname.

Note that the only form of file execution supported by CUGL is searching a directory.

This method uses the access() POSIX method. Therefore, it does not assume that this application is the file owner, and correctly determines the file access.

Returns
true if the application can execute the file for this pathname.
bool cugl::Pathname::canWrite ( )

Returns true if the application can modify the file for this pathname.

This method uses the access() POSIX method. Therefore, it does not assume that this application is the file owner, and correctly determines the file access.

Returns
true if the application can modify the file for this pathname.
bool cugl::Pathname::createDirectory ( )

Creates the directory named by this pathname.

This method succeeds if and only if a file or directory with this name does not yet exist.

Returns
true if the directory was successfully created.
bool cugl::Pathname::createFile ( )

Creates a new, empty file named by this pathname

This method succeeds if and only if a file with this name does not yet exist. The file will be an empty, regular file.

Returns
true if the file was successfully created.
bool cugl::Pathname::createPath ( )

Creates the directory for this pathname, including any necessary parent directories.

This method is similar to createDirectory except that it also creates any missing parent directories. It may fail if it does not have the appropriate permissions to create a parent. Even if it fails, it may still successfully create some of the parents.

Returns
true if the path was successfully created.
bool cugl::Pathname::deleteDirectory ( )

Deletes the directory denoted by this pathname.

This method will fail if the file is not a directory or if it does not yet exist.

Returns
true if the directory was successfully deleted.
bool cugl::Pathname::deleteFile ( )

Deletes the file denoted by this pathname.

This method will fail if the file is not a regular file or if it does not yet exist.

Returns
true if the file was successfully deleted.
bool cugl::Pathname::exists ( ) const

Returns true if the file or directory denoted by this pathname exists.

This value is recomputed each time the method is called. If the file is created later (such as with createFile, it will return true.

Returns
true if the file or directory denoted by this pathname exists.
std::string cugl::Pathname::getAbsoluteName ( ) const
inline

Returns the absolute pathname string of this pathname.

The absolute path is fixed, as the only relative pathnames that we allow are in the save directory ({

See also
Application::getSaveDirectory()}).
Returns
the absolute pathname string of this pathname.
Pathname cugl::Pathname::getAbsolutePath ( ) const

Returns the absolute form of this pathname.

The absolute path is fixed, as the only relative pathnames that we allow are in the save directory ({

See also
Application::getSaveDirectory()}).
Returns
the absolute form of this pathname.
size_t cugl::Pathname::getAvailableSpace ( ) const

Returns the number of available bytes in the partition for this pathname.

The value is for the partition containing the given file or directory. This method is similar to getFreeSpace except that it measures the number of bytes available for unpriviledged users.

Returns
the number of available bytes in the partition for this pathname.
std::vector<std::string> cugl::Pathname::getComponents ( ) const

Returns the hierarchical components of this pathname.

The result vector will not contain the volume. However it will contain every intermediate directory and the leaf child (file or directory). Together with the volume and path separator, this can be use to reconstruct the absolute pathname.

Returns
the hierarchical components of this pathname.
size_t cugl::Pathname::getFreeSpace ( ) const

Returns the number of unallocated bytes in the partition for this pathname.

The value is for the partition containing the given file or directory. Just because space is free does not mean that it is available. The space may be restricted to priviledged users.

Returns
the number of unallocated bytes in the partition for this pathname.
std::string cugl::Pathname::getName ( ) const
inline

Returns the name of the file or directory denoted by this pathname.

The value returned is the short name, without any parent directories.

Returns
the name of the file or directory denoted by this pathname.
std::string cugl::Pathname::getParentName ( ) const

Returns the pathname string of this pathname's parent

The parent is extracted from the absolute path, which allows us to specify a specific parent even in the case of a relative path. This method returns the empty string if this pathname does not have a parent directory.

Returns
the pathname string of this pathname's parent
Pathname cugl::Pathname::getParentPath ( ) const

Returns the pathname of this pathname's parent

The parent pathname is computed from the absolute path, which allows us to specify a specific parent even in the case of a relative path. This method returns the volume root if this pathname does not have a parent directory.

Returns
the pathname of this pathname's parent
std::string cugl::Pathname::getPathname ( ) const
inline

Returns the pathname string for this pathname.

This value is the normalized version of the pathname provided to the constructor. Path separators have been replaced with the correct version for the platform. However, the path is relative is the original value was relative.

Returns
the pathname string for this pathname.
static std::string cugl::Pathname::getSeparator ( )
static

Returns the system-dependent path separator for this pathname.

Path separators are the same across all files. Hence this method can be called staticly.

Returns
the system-dependent path separator for this pathname.
std::string cugl::Pathname::getSuffix ( ) const

Returns the suffix for the leaf file of this path.

A suffix is any part of the file name after a final period. If there is no suffix, this method returns the empty string.

Returns
the suffix for the leaf file of this path.
size_t cugl::Pathname::getTotalSpace ( ) const

Returns the size of the partition named by this pathname.

The value is for the partition containing the given file or directory.

Returns
the size of the partition named by this pathname.
std::string cugl::Pathname::getVolume ( ) const

Returns the volume prefix for this path.

This method will return a value even if the path is a relative one.

Returns
the volume prefix for this path.
bool cugl::Pathname::isAbsolute ( ) const
inline

Returns true if this pathname is absolute.

Returns
true if this pathname is absolute.
bool cugl::Pathname::isDirectory ( ) const

Returns true if the file denoted by this pathname is a directory.

This value will return false is the file does not exist. This value is recomputed each time the method is called. If the file is created later (such as with createDirectory, it will return true.

Returns
true if the file denoted by this pathname is a directory.
bool cugl::Pathname::isFile ( ) const

Returns true if the file denoted by this pathname is a normal file.

This value will return false is the file does not exist. This value is recomputed each time the method is called. If the file is created later (such as with createFile, it will return true.

Returns
true if the file denoted by this pathname is a normal file.
bool cugl::Pathname::isHidden ( ) const
inline

Returns true if the file named by this pathname is a hidden file.

This value will return false is the file does not exist. This value is recomputed each time the method is called. If the file is created later (such as with createFile, it will return true.

Returns
true if the file named by this pathname is a hidden file.
long cugl::Pathname::lastModified ( ) const

Returns the time that the file for this pathname was last modified.

The value is in seconds since the last epoch (e.g. January 1, 1970 on Unix systems)

Returns
the time that the file for this pathname was last modified.
size_t cugl::Pathname::length ( ) const

Returns the length of the file denoted by this pathname.

The value is measured in bytes.

Returns
the length of the file denoted by this pathname.
std::vector<std::string> cugl::Pathname::list ( ) const

Returns a list of strings naming the files and directories in the pathname

This method assumes that this pathname denotes a directory. If it does not, the list will be empty.

Returns
a list of strings naming the files and directories in the pathname
std::vector<std::string> cugl::Pathname::list ( const std::function< bool(const std::string &file)> &  filter) const

Returns a filtered list of strings naming the files and directories in the pathname

This method assumes that this pathname denotes a directory. If it does not, the list will be empty.

The filter will only be given the shortname of each file. It will not have access to the full path.

Returns
a filtered list of strings naming the files and directories in the pathname
std::vector<Pathname> cugl::Pathname::listPaths ( ) const

Returns a list of pathnames for the files and directories in the pathname

This method assumes that this pathname denotes a directory. If it does not, the list will be empty.

Returns
a list of pathnames for the files and directories in the pathname
std::vector<Pathname> cugl::Pathname::listPaths ( const std::function< bool(const Pathname &path)> &  filter) const

Returns a filtered list of pathnames for the files and directories in the pathname

This method assumes that this pathname denotes a directory. If it does not, the list will be empty.

Returns
a filtered list of pathnames for the files and directories in the pathname
bool cugl::Pathname::operator!= ( const Pathname other) const
inline

Returns true if this path is not equal to the given path.

This comparison uses lexicographical of the absolute path names.

Parameters
otherThe pathname to compare against.
Returns
True if this path is not equal to the given path.
bool cugl::Pathname::operator< ( const Pathname other) const
inline

Returns true if this path is less than the given path.

This comparison uses lexicographical of the absolute path names.

Parameters
otherThe pathname to compare against.
Returns
True if this path is less than the given path.
bool cugl::Pathname::operator<= ( const Pathname other) const
inline

Returns true if this path is less than or equal to the given path.

This comparison uses lexicographical of the absolute path names.

Parameters
otherThe pathname to compare against.
Returns
True if this path is less than or equal to the given path.
bool cugl::Pathname::operator== ( const Pathname other) const
inline

Returns true if this path is equal to the given path.

This comparison uses lexicographical of the absolute path names.

Parameters
otherThe pathname to compare against.
Returns
True if this path is equal to the given path.
bool cugl::Pathname::operator> ( const Pathname other) const
inline

Returns true if this path is greater than the given path.

This comparison uses lexicographical of the absolute path names.

Parameters
otherThe pathname to compare against.
Returns
True if this path is greater than the given path.
bool cugl::Pathname::operator>= ( const Pathname other) const
inline

Returns true if this path is greater than or equal to the given path.

This comparison uses lexicographical of the absolute path names.

Parameters
otherThe pathname to compare against.
Returns
True if this path is greater than or equal to the given path.
bool cugl::Pathname::renameTo ( const std::string &  path)
inline

Renames the file denoted by this pathname.

This contents of this pathname will not be changed. Instead, the file for this pathname will no longer exist. The file will now be referred to via the provided pathname.

This method will fail if there is no file for this pathname.

Parameters
pathThe new pathname for this file.
Returns
true if the file was successfully renamed.
bool cugl::Pathname::renameTo ( const char *  path)
inline

Renames the file denoted by this pathname.

This contents of this pathname will not be changed. Instead, the file for this pathname will no longer exist. The file will now be referred to via the provided pathname.

This method will fail if there is no file for this pathname.

Parameters
pathThe new pathname for this file.
Returns
true if the file was successfully renamed.
bool cugl::Pathname::renameTo ( const Pathname dest)

Renames the file denoted by this pathname.

This contents of this pathname will not be changed. Instead, the file for this pathname will no longer exist. The file will now be referred to via the provided pathname.

This method will fail if there is no file for this pathname.

Parameters
destThe new pathname for this file.
Returns
true if the file was successfully renamed.
bool cugl::Pathname::setReadable ( bool  readable)

Sets the owner's read permission for this pathname.

The owner may or may not be this application. The method will return false if the application does not have permission for this change.

Parameters
readableWhether the owner may read this file
Returns
true if the file permissions where successfully changed.
bool cugl::Pathname::setReadable ( bool  readable,
bool  ownerOnly 
)

Sets the owner's or everybody's read permission for this pathname.

The owner may or may not be this application. The method will return false if the application does not have permission for this change.

Parameters
readableWhether this file may be read
ownerOnlyWhether to apply this change only to the owner
Returns
true if the file permissions where successfully changed.
bool cugl::Pathname::setReadOnly ( )

Marks this file or directory so that only read operations are allowed.

The owner may or may not be this application. The method will return false if the application does not have permission for this change.

Returns
true if the file permissions where successfully changed.
bool cugl::Pathname::setSearchable ( bool  searchable)

Sets the owner's execution permission for this pathname.

Note that the only form of file execution supported by CUGL is searching a directory.

The owner may or may not be this application. The method will return false if the application does not have permission for this change.

Parameters
searchableWhether the owner may execute (search) this file
Returns
true if the file permissions where successfully changed.
bool cugl::Pathname::setSearchable ( bool  searchable,
bool  ownerOnly 
)

Sets the owner's or everybody's execution permission for this pathname.

Note that the only form of file execution supported by CUGL is searching a directory.

The owner may or may not be this application. The method will return false if the application does not have permission for this change.

Parameters
searchableWhether this file may be excuted
ownerOnlyWhether to apply this change only to the owner
Returns
true if the file permissions where successfully changed.
bool cugl::Pathname::setWritable ( bool  writable)

Sets the owner's write permission for this pathname.

The owner may or may not be this application. The method will return false if the application does not have permission for this change.

Parameters
writableWhether the owner may write to this file
Returns
true if the file permissions where successfully changed.
bool cugl::Pathname::setWritable ( bool  writable,
bool  ownerOnly 
)

Sets the owner's or everybody's write permission for this pathname.

The owner may or may not be this application. The method will return false if the application does not have permission for this change.

Parameters
writableWhether this file may be written to
ownerOnlyWhether to apply this change only to the owner
Returns
true if the file permissions where successfully changed.

The documentation for this class was generated from the following file: