Panda3D
Public Types | Public Member Functions | Static Public Member Functions | List of all members
Filename Class Reference

The name of a file, such as a texture file or an Egg file. More...

Public Types

enum  Type { T_general = 0, T_dso = 1, T_executable = 2 }
 

Public Member Functions

object __fspath__ ()
 
 __init__ ()
 Creates an empty Filename. More...
 
 __init__ (const Filename dirname, const Filename basename)
 This constructor composes the filename out of a directory part and a basename part. More...
 
 __init__ (object path)
 
bool __nonzero__ ()
 Returns true if the Filename is valid (not empty), or false if it is an empty string. More...
 
object __reduce__ ()
 
object __repr__ ()
 
bool chdir ()
 Changes directory to the specified location. More...
 
int compareTimestamps (const Filename other, bool this_missing_is_old, bool other_missing_is_old)
 Returns a number less than zero if the file named by this object is older than the given file, zero if they have the same timestamp, or greater than zero if this one is newer. More...
 
int compareTo (const Filename other)
 
bool copyTo (const Filename other)
 Copies the file to the indicated new filename, by reading the contents and writing it to the new file. More...
 
str cStr ()
 
bool empty ()
 
bool exists ()
 Returns true if the filename exists on the disk, false otherwise. More...
 
 extractComponents (VectorString components)
 Extracts out the individual directory components of the path into a series of strings. More...
 
int findOnSearchpath (const DSearchPath searchpath)
 Performs the reverse of the resolve_filename() operation: assuming that the current filename is fully-specified pathname (i.e. More...
 
time_t getAccessTimestamp ()
 Returns a time_t value that represents the time the file was last accessed, if this information is available. More...
 
str getBasename ()
 Returns the basename part of the filename. More...
 
str getBasenameWoExtension ()
 Returns the basename part of the filename, without the file extension. More...
 
str getDirname ()
 Returns the directory part of the filename. More...
 
str getExtension ()
 Returns the file extension. More...
 
Filename getFilenameIndex (int index)
 If the pattern flag is set for this Filename and the filename string actually includes a sequence of hash marks, then this returns a new Filename with the sequence of hash marks replaced by the indicated index number. More...
 
Streamsize getFileSize ()
 Returns the size of the file in bytes, or 0 if there is an error. More...
 
str getFullpath ()
 Returns the entire filename: directory, basename, extension. More...
 
str getFullpathW ()
 Returns the entire filename as a wide-character string. More...
 
str getFullpathWoExtension ()
 Returns the full filename–directory and basename parts–except for the extension. More...
 
int getHash ()
 Returns a hash code that attempts to be mostly unique for different Filenames. More...
 
str getHashToEnd ()
 Returns the part of the filename beginning at the hash sequence (if any), and continuing to the end of the filename. More...
 
bool getPattern ()
 Returns the flag indicating whether this is a filename pattern. More...
 
time_t getTimestamp ()
 Returns a time_t value that represents the time the file was last modified, to within whatever precision the operating system records this information (on a Windows95 system, for instance, this may only be accurate to within 2 seconds). More...
 
Filename::Type getType ()
 Returns the type of the file represented by the filename, as previously set by set_type(). More...
 
bool hasHash ()
 Returns true if the filename is indicated to be a filename pattern (that is, set_pattern(true) was called), and the filename pattern did include a sequence of hash marks, or false if it was not a filename pattern or did not include hash marks. More...
 
bool isBinary ()
 Returns true if the Filename has been indicated to represent a binary file via a previous call to set_binary(). More...
 
bool isBinaryOrText ()
 Returns true either is_binary() or is_text() is true; that is, that the filename has been specified as either binary or text. More...
 
bool isDirectory ()
 Returns true if the filename exists and is a directory name, false otherwise. More...
 
bool isExecutable ()
 Returns true if the filename exists and is executable. More...
 
bool isFullyQualified ()
 Returns true if the filename is fully qualified, e.g. More...
 
bool isLocal ()
 Returns true if the filename is local, e.g. More...
 
bool isRegularFile ()
 Returns true if the filename exists and is the name of a regular file (i.e. More...
 
bool isText ()
 Returns true if the Filename has been indicated to represent a text file via a previous call to set_text(). More...
 
bool isWritable ()
 Returns true if the filename exists and is either a directory or a regular file that can be written to, or false otherwise. More...
 
int length ()
 
 makeAbsolute ()
 Converts the filename to a fully-qualified pathname from the root (if it is a relative pathname), and then standardizes it (see standardize()). More...
 
 makeAbsolute (const Filename start_directory)
 Converts the filename to a fully-qualified filename from the root (if it is a relative filename), and then standardizes it (see standardize()). More...
 
bool makeCanonical ()
 Converts this filename to a canonical name by replacing the directory part with the fully-qualified directory part. More...
 
bool makeDir ()
 Creates all the directories in the path to the file specified in the filename, except for the basename itself. More...
 
bool makeRelativeTo (Filename directory, bool allow_backups)
 Adjusts this filename, which must be a fully-specified pathname beginning with a slash, to make it a relative filename, relative to the fully- specified directory indicated (which must also begin with, and may or may not end with, a slash–a terminating slash is ignored). More...
 
bool makeTrueCase ()
 On a case-insensitive operating system (e.g. More...
 
bool mkdir ()
 Creates the directory named by this filename. More...
 
bool openAppend (Pofstream stream)
 Opens the indicated pifstream for writing the file, if possible. More...
 
bool openAppend (Ofstream stream)
 Opens the indicated ofstream for writing the file, if possible. More...
 
bool openRead (Pifstream stream)
 Opens the indicated pifstream for reading the file, if possible. More...
 
bool openRead (Ifstream stream)
 Opens the indicated ifstream for reading the file, if possible. More...
 
bool openReadAppend (Pfstream stream)
 Opens the indicated pfstream for reading and writing the file, if possible; writes are appended to the end of the file. More...
 
bool openReadAppend (Fstream stream)
 Opens the indicated ifstream for reading and writing the file, if possible; writes are appended to the end of the file. More...
 
bool openReadWrite (Pfstream stream, bool truncate)
 Opens the indicated fstream for read/write access to the file, if possible. More...
 
bool openReadWrite (Fstream stream, bool truncate)
 Opens the indicated fstream for read/write access to the file, if possible. More...
 
bool openWrite (Pofstream stream, bool truncate)
 Opens the indicated pifstream for writing the file, if possible. More...
 
bool openWrite (Ofstream stream, bool truncate)
 Opens the indicated ifstream for writing the file, if possible. More...
 
bool operator != (str other)
 
char operator [] (int n)
 
Filename operator+ (str other)
 
Filename operator+= (str other)
 
Filename operator/ (const Filename other)
 
bool operator< (str other)
 
Filename operator= (Filename from)
 
Filename operator= (const Filename copy)
 
Filename operator= (str filename)
 
Filename operator= (str filename)
 
Filename operator= (str filename)
 
bool operator== (str other)
 
 output (Ostream out)
 
bool renameTo (const Filename other)
 Renames the file to the indicated new filename. More...
 
bool resolveFilename (const DSearchPath searchpath, str default_extension)
 Searches the given search path for the filename. More...
 
bool rmdir ()
 The inverse of mkdir(): this removes the directory named by this Filename, if it is in fact a directory. More...
 
object scanDirectory ()
 
bool scanDirectory (VectorString contents)
 Attempts to open the named filename as if it were a directory and looks for the non-hidden files within the directory. More...
 
 setBasename (str s)
 Replaces the basename part of the filename. More...
 
 setBasenameWoExtension (str s)
 Replaces the basename part of the filename, without the file extension. More...
 
 setBinary ()
 
 setDirname (str s)
 Replaces the directory part of the filename. More...
 
 setExtension (str s)
 Replaces the file extension. More...
 
 setFullpath (str s)
 Replaces the entire filename: directory, basename, extension. More...
 
 setFullpathWoExtension (str s)
 Replaces the full filename–directory and basename parts–except for the extension. More...
 
 setHashToEnd (str s)
 Replaces the part of the filename from the beginning of the hash sequence to the end of the filename. More...
 
 setPattern (bool pattern)
 Sets the flag indicating whether this is a filename pattern. More...
 
 setText ()
 Indicates that the filename represents a text file. More...
 
 setType (Filename::Type type)
 Sets the type of the file represented by the filename. More...
 
 standardize ()
 Converts the filename to standard form by replacing consecutive slashes with a single slash, removing a trailing slash if present, and backing up over . More...
 
str substr (int begin)
 
str substr (int begin, int end)
 
str toOsGeneric ()
 This is similar to to_os_specific(), but it is designed to generate a filename that can be understood on as many platforms as possible. More...
 
str toOsLongName ()
 This is the opposite of to_os_short_name(): it returns the "long name" of the filename, if the filename exists. More...
 
str toOsShortName ()
 This works like to_os_generic(), but it returns the "short name" version of the filename, if it exists, or the original filename otherwise. More...
 
str toOsSpecific ()
 Converts the filename from our generic Unix-like convention (forward slashes starting with the root at '/') to the corresponding filename in the local operating system (slashes in the appropriate direction, starting with the root at C:\, for instance). More...
 
str toOsSpecificW ()
 The wide-string variant on to_os_specific(). More...
 
bool touch ()
 Updates the modification time of the file to the current time. More...
 
bool unlink ()
 Permanently deletes the file associated with the filename, if possible. More...
 

Static Public Member Functions

static Filename binaryFilename (const Filename filename)
 
static Filename binaryFilename (str filename)
 
static Filename dsoFilename (str filename)
 
static Filename executableFilename (str filename)
 
static Filename expandFrom (str user_string, Filename::Type type)
 Returns the same thing as from_os_specific(), but embedded environment variable references (e.g. More...
 
static Filename fromOsSpecific (str os_specific, Filename::Type type)
 This named constructor returns a Panda-style filename (that is, using forward slashes, and no drive letter) based on the supplied filename string that describes a filename in the local system conventions (for instance, on Windows, it may use backslashes or begin with a drive letter and a colon). More...
 
static Filename fromOsSpecificW (str os_specific, Filename::Type type)
 The wide-string variant of from_os_specific(). More...
 
static TypeHandle getClassType ()
 
static const Filename getCommonAppdataDirectory ()
 Returns a path to a system-defined directory appropriate for creating a subdirectory for storing application-specific data, common to all users. More...
 
static TextEncoder::Encoding getFilesystemEncoding ()
 Specifies the default encoding to be used for all subsequent Filenames objects. More...
 
static const Filename getHomeDirectory ()
 Returns a path to the user's home directory, if such a thing makes sense in the current OS, or to the nearest equivalent. More...
 
static const Filename getTempDirectory ()
 Returns a path to a system-defined temporary directory. More...
 
static const Filename getUserAppdataDirectory ()
 Returns a path to a system-defined directory appropriate for creating a subdirectory for storing application-specific data, specific to the current user. More...
 
static Filename patternFilename (str filename)
 Constructs a filename that represents a sequence of numbered files. More...
 
static setFilesystemEncoding (TextEncoder::Encoding encoding)
 Specifies the default encoding to be used for all subsequent Filenames. More...
 
static Filename temporary (str dirname, str prefix, str suffix, Filename::Type type)
 Generates a temporary filename within the indicated directory, using the indicated prefix. More...
 
static Filename textFilename (const Filename filename)
 
static Filename textFilename (str filename)
 

Detailed Description

The name of a file, such as a texture file or an Egg file.

Stores the full pathname, and includes functions for extracting out the directory prefix part and the file extension and stuff.

A Filename is also aware of the mapping between the Unix-like filename convention we use internally, and the local OS's specific filename convention, and it knows how to perform basic OS-specific I/O, like testing for file existence and searching a searchpath, as well as the best way to open an fstream for reading or writing.

Member Enumeration Documentation

◆ Type

enum Type
Enumerator
T_general 

These type values must fit within the bits allocated for F_type, below.

T_dso 
T_executable 

Member Function Documentation

◆ __fspath__()

object __fspath__ ( )

◆ __init__() [1/3]

__init__ ( )

Creates an empty Filename.

◆ __init__() [2/3]

__init__ ( const Filename  dirname,
const Filename  basename 
)

This constructor composes the filename out of a directory part and a basename part.

It will insert an intervening '/' if necessary.

◆ __init__() [3/3]

__init__ ( object  path)

◆ __nonzero__()

bool __nonzero__ ( )

Returns true if the Filename is valid (not empty), or false if it is an empty string.

This implements the Python equivalent to operator bool. Defining an actual operator bool method for C++ use would work too, but it seems to cause too many ambiguities for the C++ compiler, so we use this Python-only approach instead.

◆ __reduce__()

object __reduce__ ( )

◆ __repr__()

object __repr__ ( )

◆ binaryFilename() [1/2]

static Filename binaryFilename ( const Filename  filename)
static

◆ binaryFilename() [2/2]

static Filename binaryFilename ( str  filename)
static

◆ chdir()

bool chdir ( )

Changes directory to the specified location.

Returns true if successful, false if failure.

◆ compareTimestamps()

int compareTimestamps ( const Filename  other,
bool  this_missing_is_old,
bool  other_missing_is_old 
)

Returns a number less than zero if the file named by this object is older than the given file, zero if they have the same timestamp, or greater than zero if this one is newer.

If this_missing_is_old is true, it indicates that a missing file will be treated as if it were older than any other file; otherwise, a missing file will be treated as if it were newer than any other file. Similarly for other_missing_is_old.

◆ compareTo()

int compareTo ( const Filename  other)

◆ copyTo()

bool copyTo ( const Filename  other)

Copies the file to the indicated new filename, by reading the contents and writing it to the new file.

Returns true if successful, false on failure. The copy is always binary, regardless of the filename settings.

◆ cStr()

str cStr ( )

◆ dsoFilename()

static Filename dsoFilename ( str  filename)
static

◆ empty()

bool empty ( )

◆ executableFilename()

static Filename executableFilename ( str  filename)
static

◆ exists()

bool exists ( )

Returns true if the filename exists on the disk, false otherwise.

If the type is indicated to be executable, this also tests that the file has execute permission.

◆ expandFrom()

static Filename expandFrom ( str  user_string,
Filename::Type  type 
)
static

Returns the same thing as from_os_specific(), but embedded environment variable references (e.g.

"$DMODELS/foo.txt") are expanded out. It also automatically elevates the file to its true case if needed.

◆ extractComponents()

extractComponents ( VectorString  components)

Extracts out the individual directory components of the path into a series of strings.

get_basename() will be the last component stored in the vector. Note that no distinction is made by this method between a leading slash and no leading slash, but you can call is_local() to differentiate the two cases.

◆ findOnSearchpath()

int findOnSearchpath ( const DSearchPath  searchpath)

Performs the reverse of the resolve_filename() operation: assuming that the current filename is fully-specified pathname (i.e.

beginning with '/'), look on the indicated search path for a directory under which the file can be found. When found, adjust the Filename to be relative to the indicated directory name.

Returns the index of the directory on the searchpath at which the file was found, or -1 if it was not found.

◆ fromOsSpecific()

static Filename fromOsSpecific ( str  os_specific,
Filename::Type  type 
)
static

This named constructor returns a Panda-style filename (that is, using forward slashes, and no drive letter) based on the supplied filename string that describes a filename in the local system conventions (for instance, on Windows, it may use backslashes or begin with a drive letter and a colon).

Use this function to create a Filename from an externally-given filename string. Use to_os_specific() again later to reconvert it back to the local operating system's conventions.

This function will do the right thing even if the filename is partially local conventions and partially Panda conventions; e.g. some backslashes and some forward slashes.

◆ fromOsSpecificW()

static Filename fromOsSpecificW ( str  os_specific,
Filename::Type  type 
)
static

The wide-string variant of from_os_specific().

Returns a new Filename, converted from an os-specific wide-character string.

◆ getAccessTimestamp()

time_t getAccessTimestamp ( )

Returns a time_t value that represents the time the file was last accessed, if this information is available.

See also get_timestamp(), which returns the last modification time.

◆ getBasename()

str getBasename ( )

Returns the basename part of the filename.

This is everything in the filename after the rightmost slash, including any extensions.

◆ getBasenameWoExtension()

str getBasenameWoExtension ( )

Returns the basename part of the filename, without the file extension.

◆ getClassType()

static TypeHandle getClassType ( )
static

◆ getCommonAppdataDirectory()

static const Filename getCommonAppdataDirectory ( )
static

Returns a path to a system-defined directory appropriate for creating a subdirectory for storing application-specific data, common to all users.

◆ getDirname()

str getDirname ( )

Returns the directory part of the filename.

This is everything in the filename up to, but not including the rightmost slash.

◆ getExtension()

str getExtension ( )

Returns the file extension.

This is everything after the rightmost dot, if there is one, or the empty string if there is not.

◆ getFilenameIndex()

Filename getFilenameIndex ( int  index)

If the pattern flag is set for this Filename and the filename string actually includes a sequence of hash marks, then this returns a new Filename with the sequence of hash marks replaced by the indicated index number.

If the pattern flag is not set for this Filename or it does not contain a sequence of hash marks, this quietly returns the original filename.

◆ getFileSize()

Streamsize getFileSize ( )

Returns the size of the file in bytes, or 0 if there is an error.

◆ getFilesystemEncoding()

static TextEncoder::Encoding getFilesystemEncoding ( )
static

Specifies the default encoding to be used for all subsequent Filenames objects.

See set_filesystem_encoding().

◆ getFullpath()

str getFullpath ( )

Returns the entire filename: directory, basename, extension.

This is the same thing returned by the string typecast operator.

◆ getFullpathW()

str getFullpathW ( )

Returns the entire filename as a wide-character string.

◆ getFullpathWoExtension()

str getFullpathWoExtension ( )

Returns the full filename–directory and basename parts–except for the extension.

◆ getHash()

int getHash ( )

Returns a hash code that attempts to be mostly unique for different Filenames.

◆ getHashToEnd()

str getHashToEnd ( )

Returns the part of the filename beginning at the hash sequence (if any), and continuing to the end of the filename.

◆ getHomeDirectory()

static const Filename getHomeDirectory ( )
static

Returns a path to the user's home directory, if such a thing makes sense in the current OS, or to the nearest equivalent.

This may or may not be directly writable by the application.

◆ getPattern()

bool getPattern ( )

Returns the flag indicating whether this is a filename pattern.

See set_pattern().

◆ getTempDirectory()

static const Filename getTempDirectory ( )
static

Returns a path to a system-defined temporary directory.

◆ getTimestamp()

time_t getTimestamp ( )

Returns a time_t value that represents the time the file was last modified, to within whatever precision the operating system records this information (on a Windows95 system, for instance, this may only be accurate to within 2 seconds).

If the timestamp cannot be determined, either because it is not supported by the operating system or because there is some error (such as file not found), returns 0.

◆ getType()

Filename::Type getType ( )

Returns the type of the file represented by the filename, as previously set by set_type().

◆ getUserAppdataDirectory()

static const Filename getUserAppdataDirectory ( )
static

Returns a path to a system-defined directory appropriate for creating a subdirectory for storing application-specific data, specific to the current user.

◆ hasHash()

bool hasHash ( )

Returns true if the filename is indicated to be a filename pattern (that is, set_pattern(true) was called), and the filename pattern did include a sequence of hash marks, or false if it was not a filename pattern or did not include hash marks.

If this is true, then get_filename_index() will return a different filename each time.

◆ isBinary()

bool isBinary ( )

Returns true if the Filename has been indicated to represent a binary file via a previous call to set_binary().

It is possible that neither is_binary() nor is_text() will be true, if neither set_binary() nor set_text() was ever called.

◆ isBinaryOrText()

bool isBinaryOrText ( )

Returns true either is_binary() or is_text() is true; that is, that the filename has been specified as either binary or text.

If this is false, the filename has not been specified.

◆ isDirectory()

bool isDirectory ( )

Returns true if the filename exists and is a directory name, false otherwise.

◆ isExecutable()

bool isExecutable ( )

Returns true if the filename exists and is executable.

◆ isFullyQualified()

bool isFullyQualified ( )

Returns true if the filename is fully qualified, e.g.

begins with a slash. This is almost, but not quite, the same thing as !is_local(). It's not exactly the same because a special case is made for filenames that begin with a single dot followed by a slash–these are considered to be fully qualified (they are explicitly relative to the current directory, and do not refer to a filename on a search path somewhere).

◆ isLocal()

bool isLocal ( )

Returns true if the filename is local, e.g.

does not begin with a slash, or false if the filename is fully specified from the root.

◆ isRegularFile()

bool isRegularFile ( )

Returns true if the filename exists and is the name of a regular file (i.e.

not a directory or device), false otherwise.

◆ isText()

bool isText ( )

Returns true if the Filename has been indicated to represent a text file via a previous call to set_text().

It is possible that neither is_binary() nor is_text() will be true, if neither set_binary() nor set_text() was ever called.

◆ isWritable()

bool isWritable ( )

Returns true if the filename exists and is either a directory or a regular file that can be written to, or false otherwise.

◆ length()

int length ( )

◆ makeAbsolute() [1/2]

makeAbsolute ( )

Converts the filename to a fully-qualified pathname from the root (if it is a relative pathname), and then standardizes it (see standardize()).

This is sometimes a little problematic, since it may convert the file to its 'true' absolute pathname, which could be an ugly NFS-named file, irrespective of symbolic links (e.g. /.automount/dimbo/root/usr2/fit/people/drose instead of /fit/people/drose); besides being ugly, filenames like this may not be consistent across multiple different platforms.

◆ makeAbsolute() [2/2]

makeAbsolute ( const Filename  start_directory)

Converts the filename to a fully-qualified filename from the root (if it is a relative filename), and then standardizes it (see standardize()).

This flavor accepts a specific starting directory that the filename is known to be relative to.

◆ makeCanonical()

bool makeCanonical ( )

Converts this filename to a canonical name by replacing the directory part with the fully-qualified directory part.

This is done by changing to that directory and calling getcwd().

This has the effect of (a) converting relative paths to absolute paths (but see make_absolute() if this is the only effect you want), and (b) always resolving a given directory name to the same string, even if different symbolic links are traversed, and (c) changing nice symbolic-link paths like fit/people/drose to ugly NFS automounter names like hosts/dimbo/usr2/fit/people/drose. This can be troubling, but sometimes this is exactly what you want, particularly if you're about to call make_relative_to() between two filenames.

The return value is true if successful, or false on failure (usually because the directory name does not exist or cannot be chdir'ed into).

◆ makeDir()

bool makeDir ( )

Creates all the directories in the path to the file specified in the filename, except for the basename itself.

This assumes that the Filename contains the name of a file, not a directory name; it ensures that the directory containing the file exists.

However, if the filename ends in a slash, it assumes the Filename represents the name of a directory, and creates all the paths.

◆ makeRelativeTo()

bool makeRelativeTo ( Filename  directory,
bool  allow_backups 
)

Adjusts this filename, which must be a fully-specified pathname beginning with a slash, to make it a relative filename, relative to the fully- specified directory indicated (which must also begin with, and may or may not end with, a slash–a terminating slash is ignored).

This only performs a string comparsion, so it may be wise to call make_canonical() on both filenames before calling make_relative_to().

If allow_backups is false, the filename will only be adjusted to be made relative if it is already somewhere within or below the indicated directory. If allow_backups is true, it will be adjusted in all cases, even if this requires putting a series of .. characters before the filename –unless it would have to back all the way up to the root.

Returns true if the file was adjusted, false if it was not.

◆ makeTrueCase()

bool makeTrueCase ( )

On a case-insensitive operating system (e.g.

Windows), this method looks up the file in the file system and resets the Filename to represent the actual case of the file as it exists on the disk. The return value is true if the file exists and the conversion can be made, or false if there is some error.

On a case-sensitive operating system, this method does nothing and always returns true.

An empty filename is considered to exist in this case.

◆ mkdir()

bool mkdir ( )

Creates the directory named by this filename.

Unlike make_dir(), this assumes that the Filename contains the directory name itself. Also, parent directories are not automatically created; this function fails if any parent directory is missing.

◆ openAppend() [1/2]

bool openAppend ( Pofstream  stream)

Opens the indicated pifstream for writing the file, if possible.

Returns true if successful, false otherwise. This requires the setting of the set_text()/set_binary() flags to open the file appropriately as indicated; it is an error to call open_read() without first calling one of set_text() or set_binary().

◆ openAppend() [2/2]

bool openAppend ( Ofstream  stream)

Opens the indicated ofstream for writing the file, if possible.

Returns true if successful, false otherwise. This requires the setting of the set_text()/set_binary() flags to open the file appropriately as indicated; it is an error to call open_read() without first calling one of set_text() or set_binary().

◆ openRead() [1/2]

bool openRead ( Pifstream  stream)

Opens the indicated pifstream for reading the file, if possible.

Returns true if successful, false otherwise. This requires the setting of the set_text()/set_binary() flags to open the file appropriately as indicated; it is an error to call open_read() without first calling one of set_text() or set_binary().

◆ openRead() [2/2]

bool openRead ( Ifstream  stream)

Opens the indicated ifstream for reading the file, if possible.

Returns true if successful, false otherwise. This requires the setting of the set_text()/set_binary() flags to open the file appropriately as indicated; it is an error to call open_read() without first calling one of set_text() or set_binary().

◆ openReadAppend() [1/2]

bool openReadAppend ( Pfstream  stream)

Opens the indicated pfstream for reading and writing the file, if possible; writes are appended to the end of the file.

Returns true if successful, false otherwise. This requires the setting of the set_text()/set_binary() flags to open the file appropriately as indicated; it is an error to call open_read() without first calling one of set_text() or set_binary().

◆ openReadAppend() [2/2]

bool openReadAppend ( Fstream  stream)

Opens the indicated ifstream for reading and writing the file, if possible; writes are appended to the end of the file.

Returns true if successful, false otherwise. This requires the setting of the set_text()/set_binary() flags to open the file appropriately as indicated; it is an error to call open_read() without first calling one of set_text() or set_binary().

◆ openReadWrite() [1/2]

bool openReadWrite ( Pfstream  stream,
bool  truncate 
)

Opens the indicated fstream for read/write access to the file, if possible.

Returns true if successful, false otherwise. This requires the setting of the set_text()/set_binary() flags to open the file appropriately as indicated; it is an error to call open_read_write() without first calling one of set_text() or set_binary().

◆ openReadWrite() [2/2]

bool openReadWrite ( Fstream  stream,
bool  truncate 
)

Opens the indicated fstream for read/write access to the file, if possible.

Returns true if successful, false otherwise. This requires the setting of the set_text()/set_binary() flags to open the file appropriately as indicated; it is an error to call open_read_write() without first calling one of set_text() or set_binary().

◆ openWrite() [1/2]

bool openWrite ( Pofstream  stream,
bool  truncate 
)

Opens the indicated pifstream for writing the file, if possible.

Returns true if successful, false otherwise. This requires the setting of the set_text()/set_binary() flags to open the file appropriately as indicated; it is an error to call open_read() without first calling one of set_text() or set_binary().

If truncate is true, the file is truncated to zero length upon opening it, if it already exists. Otherwise, the file is kept at its original length.

◆ openWrite() [2/2]

bool openWrite ( Ofstream  stream,
bool  truncate 
)

Opens the indicated ifstream for writing the file, if possible.

Returns true if successful, false otherwise. This requires the setting of the set_text()/set_binary() flags to open the file appropriately as indicated; it is an error to call open_read() without first calling one of set_text() or set_binary().

If truncate is true, the file is truncated to zero length upon opening it, if it already exists. Otherwise, the file is kept at its original length.

◆ operator !=()

bool operator != ( str  other)

◆ operator []()

char operator [] ( int  n)

◆ operator+()

Filename operator+ ( str  other)

◆ operator+=()

Filename operator+= ( str  other)

◆ operator/()

Filename operator/ ( const Filename  other)

◆ operator<()

bool operator< ( str  other)

◆ operator=() [1/5]

Filename operator= ( Filename  from)

◆ operator=() [2/5]

Filename operator= ( const Filename  copy)

◆ operator=() [3/5]

Filename operator= ( str  filename)

◆ operator=() [4/5]

Filename operator= ( str  filename)

◆ operator=() [5/5]

Filename operator= ( str  filename)

◆ operator==()

bool operator== ( str  other)

◆ output()

output ( Ostream  out)

◆ patternFilename()

static Filename patternFilename ( str  filename)
static

Constructs a filename that represents a sequence of numbered files.

See set_pattern().

◆ renameTo()

bool renameTo ( const Filename  other)

Renames the file to the indicated new filename.

If the new filename is in a different directory, this will perform a move. Returns true if successful, false on failure.

◆ resolveFilename()

bool resolveFilename ( const DSearchPath  searchpath,
str  default_extension 
)

Searches the given search path for the filename.

If it is found, updates the filename to the full pathname found and returns true; otherwise, returns false.

◆ rmdir()

bool rmdir ( )

The inverse of mkdir(): this removes the directory named by this Filename, if it is in fact a directory.

◆ scanDirectory() [1/2]

object scanDirectory ( )

◆ scanDirectory() [2/2]

bool scanDirectory ( VectorString  contents)

Attempts to open the named filename as if it were a directory and looks for the non-hidden files within the directory.

Fills the given vector up with the sorted list of filenames that are local to this directory.

It is the user's responsibility to ensure that the contents vector is empty before making this call; otherwise, the new files will be appended to it.

Returns true on success, false if the directory could not be read for some reason.

◆ setBasename()

setBasename ( str  s)

Replaces the basename part of the filename.

This is everything in the filename after the rightmost slash, including any extensions.

◆ setBasenameWoExtension()

setBasenameWoExtension ( str  s)

Replaces the basename part of the filename, without the file extension.

◆ setBinary()

setBinary ( )

◆ setDirname()

setDirname ( str  s)

Replaces the directory part of the filename.

This is everything in the filename up to, but not including the rightmost slash.

◆ setExtension()

setExtension ( str  s)

Replaces the file extension.

This is everything after the rightmost dot, if there is one, or the empty string if there is not.

◆ setFilesystemEncoding()

static setFilesystemEncoding ( TextEncoder::Encoding  encoding)
static

Specifies the default encoding to be used for all subsequent Filenames.

This is used to represent wide-character (Unicode) filenames internally. On non-Windows-based systems, the encoded filename is also passed to the underlying operating system.

◆ setFullpath()

setFullpath ( str  s)

Replaces the entire filename: directory, basename, extension.

This can also be achieved with the assignment operator.

◆ setFullpathWoExtension()

setFullpathWoExtension ( str  s)

Replaces the full filename–directory and basename parts–except for the extension.

◆ setHashToEnd()

setHashToEnd ( str  s)

Replaces the part of the filename from the beginning of the hash sequence to the end of the filename.

◆ setPattern()

setPattern ( bool  pattern)

Sets the flag indicating whether this is a filename pattern.

When this is true, the filename is understood to be a placeholder for a numbered sequence of filename, such as an image sequence. In this case, a sequence of one or more hash characters ("#") should appear in the filename string; these characters will be filled in with the corresponding number (or more) of digits representing the sequence number. Sequence numbers always begin counting at 0.

When this is true, methods like has_hash() and get_hash_to_end() and get_filename_index() may be called. Methods like is_exists() will implicitly test for existance of filename sequence 0.

◆ setText()

setText ( )

Indicates that the filename represents a text file.

This is primarily relevant to the read_file() and write_file() methods, so they can set the appropriate flags to the OS.

◆ setType()

setType ( Filename::Type  type)

Sets the type of the file represented by the filename.

This is useful for to_os_specific(), resolve_filename(), test_existence(), and all such real- world access functions. It helps the Filename know how to map the internal filename to the OS-specific filename (for instance, maybe executables should have an .exe extension).

◆ standardize()

standardize ( )

Converts the filename to standard form by replacing consecutive slashes with a single slash, removing a trailing slash if present, and backing up over .

. sequences within the filename where possible.

◆ substr() [1/2]

str substr ( int  begin)

◆ substr() [2/2]

str substr ( int  begin,
int  end 
)

◆ temporary()

static Filename temporary ( str  dirname,
str  prefix,
str  suffix,
Filename::Type  type 
)
static

Generates a temporary filename within the indicated directory, using the indicated prefix.

If the directory is empty, a system-defined directory is chosen instead.

The generated filename did not exist when the Filename checked, but since it does not specifically create the file, it is possible that another process could simultaneously create a file by the same name.

◆ textFilename() [1/2]

static Filename textFilename ( const Filename  filename)
static

◆ textFilename() [2/2]

static Filename textFilename ( str  filename)
static

◆ toOsGeneric()

str toOsGeneric ( )

This is similar to to_os_specific(), but it is designed to generate a filename that can be understood on as many platforms as possible.

Since Windows can usually understand a forward-slash-delimited filename, this means it does the same thing as to_os_specific(), but it uses forward slashes instead of backslashes.

This method has a pretty limited use; it should generally be used for writing file references to a file that might be read on any operating system.

◆ toOsLongName()

str toOsLongName ( )

This is the opposite of to_os_short_name(): it returns the "long name" of the filename, if the filename exists.

On non-Windows platforms, this returns the same thing as to_os_specific().

◆ toOsShortName()

str toOsShortName ( )

This works like to_os_generic(), but it returns the "short name" version of the filename, if it exists, or the original filename otherwise.

On Windows platforms, this returns the 8.3 filename version of the given filename, if the file exists, and the same thing as to_os_specific() otherwise. On non-Windows platforms, this always returns the same thing as to_os_specific().

◆ toOsSpecific()

str toOsSpecific ( )

Converts the filename from our generic Unix-like convention (forward slashes starting with the root at '/') to the corresponding filename in the local operating system (slashes in the appropriate direction, starting with the root at C:\, for instance).

Returns the string representing the converted filename, but does not change the Filename itself.

See also from_os_specific().

◆ toOsSpecificW()

str toOsSpecificW ( )

The wide-string variant on to_os_specific().

◆ touch()

bool touch ( )

Updates the modification time of the file to the current time.

If the file does not already exist, it will be created. Returns true if successful, false if there is an error.

◆ unlink()

bool unlink ( )

Permanently deletes the file associated with the filename, if possible.

Returns true if successful, false if failure (for instance, because the file did not exist, or because permissions were inadequate).