Filename
from panda3d.core import Filename
- class Filename
Bases:
DTOOL_SUPER_BASEThe 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.
Note that the methods of Filename that interact with the filesystem (such as exists(), open_read(), etc.) directly interface with the operating system and are not aware of Panda’s virtual file system. To interact with the VFS, use the methods on VirtualFileSystem instead.
Inheritance diagram
- Fspath()
C++ Interface: __fspath__(Filename self)
- TDso = 1
- TExecutable = 2
- TGeneral = 0
- T_dso = 1
- T_executable = 2
- T_general = 0
- __init__(*args, **kwargs)
- assign()
C++ Interface: assign(const Filename self, const Filename copy) assign(const Filename self, unicode filename) assign(const Filename self, str filename) assign(const Filename self, str filename)
// Assignment is via the = operator.
- binaryFilename()
C++ Interface: binary_filename(const Filename filename) binary_filename(str filename)
- binary_filename()
C++ Interface: binary_filename(const Filename filename) binary_filename(str filename)
- chdir()
C++ Interface: chdir(Filename self)
- /**
Changes directory to the specified location. Returns true if successful,
false if failure.
*/
- compareTimestamps()
C++ Interface: compare_timestamps(Filename self, 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.
*/
- compare_timestamps()
C++ Interface: compare_timestamps(Filename self, 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.
*/
- copyTo()
C++ Interface: copy_to(Filename self, 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.
*/
- copy_to()
C++ Interface: copy_to(Filename self, 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.
*/
- exists()
C++ Interface: exists(Filename self)
- /**
Returns true if the filename exists on the physical disk, false otherwise.
If the type is indicated to be executable, this also tests that the file has
execute permission.
@see VirtualFileSystem::exists() for checking whether the filename exists in
the virtual file system.
*/
- expandFrom()
C++ Interface: expand_from(str user_string, int type)
- /**
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.
*/
- expand_from()
C++ Interface: expand_from(str user_string, int type)
- /**
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.
*/
- findOnSearchpath()
C++ Interface: find_on_searchpath(const Filename self, 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.
*/
- find_on_searchpath()
C++ Interface: find_on_searchpath(const Filename self, 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()
C++ Interface: from_os_specific(str os_specific, int 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).
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()
C++ Interface: from_os_specific_w(unicode os_specific, int type)
- /**
The wide-string variant of from_os_specific(). Returns a new Filename,
converted from an os-specific wide-character string.
*/
- from_os_specific()
C++ Interface: from_os_specific(str os_specific, int 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).
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.
*/
- from_os_specific_w()
C++ Interface: from_os_specific_w(unicode os_specific, int type)
- /**
The wide-string variant of from_os_specific(). Returns a new Filename,
converted from an os-specific wide-character string.
*/
- getAccessTimestamp()
C++ Interface: get_access_timestamp(Filename self)
- /**
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()
C++ Interface: get_basename(Filename self)
- /**
Returns the basename part of the filename. This is everything in the
filename after the rightmost slash, including any extensions.
*/
- getBasenameWoExtension()
C++ Interface: get_basename_wo_extension(Filename self)
- /**
Returns the basename part of the filename, without the file extension.
*/
- getClassType()
C++ Interface: get_class_type()
- getCommonAppdataDirectory()
C++ Interface: get_common_appdata_directory()
- /**
Returns a path to a system-defined directory appropriate for creating a
subdirectory for storing application-specific data, common to all users.
*/
- getDirname()
C++ Interface: get_dirname(Filename self)
- /**
Returns the directory part of the filename. This is everything in the
filename up to, but not including the rightmost slash.
*/
- getExtension()
C++ Interface: get_extension(Filename self)
- /**
Returns the file extension. This is everything after the rightmost dot, if
there is one, or the empty string if there is not.
*/
- getFileSize()
C++ Interface: get_file_size(Filename self)
- /**
Returns the size of the file in bytes, or 0 if there is an error.
*/
- getFilenameIndex()
C++ Interface: get_filename_index(Filename self, 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.
*/
- getFilesystemEncoding()
C++ Interface: get_filesystem_encoding()
- /**
Specifies the default encoding to be used for all subsequent Filenames
objects. See set_filesystem_encoding().
*/
- getFullpath()
C++ Interface: get_fullpath(Filename self)
// Or, you can use any of these.
- /**
Returns the entire filename: directory, basename, extension. This is the
same thing returned by the string typecast operator.
*/
- getFullpathW()
C++ Interface: get_fullpath_w(Filename self)
- /**
Returns the entire filename as a wide-character string.
*/
- getFullpathWoExtension()
C++ Interface: get_fullpath_wo_extension(Filename self)
- /**
Returns the full filename–directory and basename parts–except for the
extension.
*/
- getHash()
C++ Interface: get_hash(Filename self)
- /**
Returns a hash code that attempts to be mostly unique for different
Filenames.
*/
- getHashToEnd()
C++ Interface: get_hash_to_end(Filename self)
- /**
Returns the part of the filename beginning at the hash sequence (if any),
and continuing to the end of the filename.
*/
- getHomeDirectory()
C++ Interface: get_home_directory()
- /**
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()
C++ Interface: get_pattern(Filename self)
- /**
Returns the flag indicating whether this is a filename pattern. See
set_pattern().
*/
- getTempDirectory()
C++ Interface: get_temp_directory()
- /**
Returns a path to a system-defined temporary directory.
*/
- getTimestamp()
C++ Interface: get_timestamp(Filename self)
- /**
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()
C++ Interface: get_type(Filename self)
- /**
Returns the type of the file represented by the filename, as previously set
by set_type().
*/
- getUserAppdataDirectory()
C++ Interface: get_user_appdata_directory()
- /**
Returns a path to a system-defined directory appropriate for creating a
subdirectory for storing application-specific data, specific to the current
user.
*/
- get_access_timestamp()
C++ Interface: get_access_timestamp(Filename self)
- /**
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.
*/
- get_basename()
C++ Interface: get_basename(Filename self)
- /**
Returns the basename part of the filename. This is everything in the
filename after the rightmost slash, including any extensions.
*/
- get_basename_wo_extension()
C++ Interface: get_basename_wo_extension(Filename self)
- /**
Returns the basename part of the filename, without the file extension.
*/
- get_class_type()
C++ Interface: get_class_type()
- get_common_appdata_directory()
C++ Interface: get_common_appdata_directory()
- /**
Returns a path to a system-defined directory appropriate for creating a
subdirectory for storing application-specific data, common to all users.
*/
- get_dirname()
C++ Interface: get_dirname(Filename self)
- /**
Returns the directory part of the filename. This is everything in the
filename up to, but not including the rightmost slash.
*/
- get_extension()
C++ Interface: get_extension(Filename self)
- /**
Returns the file extension. This is everything after the rightmost dot, if
there is one, or the empty string if there is not.
*/
- get_file_size()
C++ Interface: get_file_size(Filename self)
- /**
Returns the size of the file in bytes, or 0 if there is an error.
*/
- get_filename_index()
C++ Interface: get_filename_index(Filename self, 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.
*/
- get_filesystem_encoding()
C++ Interface: get_filesystem_encoding()
- /**
Specifies the default encoding to be used for all subsequent Filenames
objects. See set_filesystem_encoding().
*/
- get_fullpath()
C++ Interface: get_fullpath(Filename self)
// Or, you can use any of these.
- /**
Returns the entire filename: directory, basename, extension. This is the
same thing returned by the string typecast operator.
*/
- get_fullpath_w()
C++ Interface: get_fullpath_w(Filename self)
- /**
Returns the entire filename as a wide-character string.
*/
- get_fullpath_wo_extension()
C++ Interface: get_fullpath_wo_extension(Filename self)
- /**
Returns the full filename–directory and basename parts–except for the
extension.
*/
- get_hash()
C++ Interface: get_hash(Filename self)
- /**
Returns a hash code that attempts to be mostly unique for different
Filenames.
*/
- get_hash_to_end()
C++ Interface: get_hash_to_end(Filename self)
- /**
Returns the part of the filename beginning at the hash sequence (if any),
and continuing to the end of the filename.
*/
- get_home_directory()
C++ Interface: get_home_directory()
- /**
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.
*/
- get_pattern()
C++ Interface: get_pattern(Filename self)
- /**
Returns the flag indicating whether this is a filename pattern. See
set_pattern().
*/
- get_temp_directory()
C++ Interface: get_temp_directory()
- /**
Returns a path to a system-defined temporary directory.
*/
- get_timestamp()
C++ Interface: get_timestamp(Filename self)
- /**
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.
*/
- get_type()
C++ Interface: get_type(Filename self)
- /**
Returns the type of the file represented by the filename, as previously set
by set_type().
*/
- get_user_appdata_directory()
C++ Interface: get_user_appdata_directory()
- /**
Returns a path to a system-defined directory appropriate for creating a
subdirectory for storing application-specific data, specific to the current
user.
*/
- hasHash()
C++ Interface: has_hash(Filename self)
- /**
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.
*/
- has_hash()
C++ Interface: has_hash(Filename self)
- /**
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()
C++ Interface: is_binary(Filename self)
- /**
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()
C++ Interface: is_binary_or_text(Filename self)
- /**
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()
C++ Interface: is_directory(Filename self)
- /**
Returns true if the filename exists on the physical disk and is a directory
name, false otherwise.
@see VirtualFileSystem::is_directory() for checking whether the filename
exists as a directory in the virtual file system.
*/
- isExecutable()
C++ Interface: is_executable(Filename self)
- /**
Returns true if the filename exists and is executable
*/
- isFullyQualified()
C++ Interface: is_fully_qualified(Filename self)
- /**
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()
C++ Interface: is_local(Filename self)
- /**
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()
C++ Interface: is_regular_file(Filename self)
- /**
Returns true if the filename exists on the physical disk and is the name of
a regular file (i.e. not a directory or device), false otherwise.
@see VirtualFileSystem::is_regular_file() for checking whether the filename
exists and is a regular file in the virtual file system.
*/
- isText()
C++ Interface: is_text(Filename self)
- /**
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()
C++ Interface: is_writable(Filename self)
- /**
Returns true if the filename exists on the physical disk and is either a
directory or a regular file that can be written to, or false otherwise.
*/
- is_binary()
C++ Interface: is_binary(Filename self)
- /**
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.
*/
- is_binary_or_text()
C++ Interface: is_binary_or_text(Filename self)
- /**
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.
*/
- is_directory()
C++ Interface: is_directory(Filename self)
- /**
Returns true if the filename exists on the physical disk and is a directory
name, false otherwise.
@see VirtualFileSystem::is_directory() for checking whether the filename
exists as a directory in the virtual file system.
*/
- is_executable()
C++ Interface: is_executable(Filename self)
- /**
Returns true if the filename exists and is executable
*/
- is_fully_qualified()
C++ Interface: is_fully_qualified(Filename self)
- /**
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).
*/
- is_local()
C++ Interface: is_local(Filename self)
- /**
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.
*/
- is_regular_file()
C++ Interface: is_regular_file(Filename self)
- /**
Returns true if the filename exists on the physical disk and is the name of
a regular file (i.e. not a directory or device), false otherwise.
@see VirtualFileSystem::is_regular_file() for checking whether the filename
exists and is a regular file in the virtual file system.
*/
- is_text()
C++ Interface: is_text(Filename self)
- /**
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.
*/
- is_writable()
C++ Interface: is_writable(Filename self)
- /**
Returns true if the filename exists on the physical disk and is either a
directory or a regular file that can be written to, or false otherwise.
*/
- makeAbsolute()
C++ Interface: make_absolute(const Filename self) make_absolute(const Filename self, const Filename start_directory)
- /**
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.
*/
- /**
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()
C++ Interface: make_canonical(const Filename self)
- /**
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()
C++ Interface: make_dir(Filename self)
- /**
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()
C++ Interface: make_relative_to(const Filename self, 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()
C++ Interface: make_true_case(const Filename self)
- /**
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.
*/
- make_absolute()
C++ Interface: make_absolute(const Filename self) make_absolute(const Filename self, const Filename start_directory)
- /**
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.
*/
- /**
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.
*/
- make_canonical()
C++ Interface: make_canonical(const Filename self)
- /**
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).
*/
- make_dir()
C++ Interface: make_dir(Filename self)
- /**
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.
*/
- make_relative_to()
C++ Interface: make_relative_to(const Filename self, 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.
*/
- make_true_case()
C++ Interface: make_true_case(const Filename self)
- /**
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()
C++ Interface: mkdir(Filename self)
- /**
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()
C++ Interface: open_append(Filename self, OFileStream stream) open_append(Filename self, 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().
*/
- /**
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().
*/
- openRead()
C++ Interface: open_read(Filename self, IFileStream stream) open_read(Filename self, 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().
*/
- /**
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().
*/
- openReadAppend()
C++ Interface: open_read_append(Filename self, FileStream stream) open_read_append(Filename self, 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().
*/
- /**
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().
*/
- openReadWrite()
C++ Interface: open_read_write(Filename self, FileStream stream, bool truncate) open_read_write(Filename self, 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().
*/
- /**
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()
C++ Interface: open_write(Filename self, OFileStream stream, bool truncate) open_write(Filename self, 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.
*/
- /**
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.
*/
- open_append()
C++ Interface: open_append(Filename self, OFileStream stream) open_append(Filename self, 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().
*/
- /**
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().
*/
- open_read()
C++ Interface: open_read(Filename self, IFileStream stream) open_read(Filename self, 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().
*/
- /**
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().
*/
- open_read_append()
C++ Interface: open_read_append(Filename self, FileStream stream) open_read_append(Filename self, 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().
*/
- /**
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().
*/
- open_read_write()
C++ Interface: open_read_write(Filename self, FileStream stream, bool truncate) open_read_write(Filename self, 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().
*/
- /**
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().
*/
- open_write()
C++ Interface: open_write(Filename self, OFileStream stream, bool truncate) open_write(Filename self, 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.
*/
- /**
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.
*/
- patternFilename()
C++ Interface: pattern_filename(str filename)
- /**
Constructs a filename that represents a sequence of numbered files. See
set_pattern().
*/
- pattern_filename()
C++ Interface: pattern_filename(str filename)
- /**
Constructs a filename that represents a sequence of numbered files. See
set_pattern().
*/
- renameTo()
C++ Interface: rename_to(Filename self, 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.
*/
- rename_to()
C++ Interface: rename_to(Filename self, 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()
C++ Interface: resolve_filename(const Filename self, 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.
*/
- resolve_filename()
C++ Interface: resolve_filename(const Filename self, 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()
C++ Interface: rmdir(Filename self)
- /**
The inverse of mkdir(): this removes the directory named by this Filename,
if it is in fact a directory.
*/
- scanDirectory()
C++ Interface: scan_directory(Filename self)
- /**
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.
*/
- scan_directory()
C++ Interface: scan_directory(Filename self)
- /**
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()
C++ Interface: set_basename(const Filename self, str s)
- /**
Replaces the basename part of the filename. This is everything in the
filename after the rightmost slash, including any extensions.
*/
- setBasenameWoExtension()
C++ Interface: set_basename_wo_extension(const Filename self, str s)
- /**
Replaces the basename part of the filename, without the file extension.
*/
- setBinary()
C++ Interface: set_binary(const Filename self)
// Setting these flags appropriately is helpful when opening or searching // for a file; it helps the Filename resolve OS-specific conventions (for // instance, that dynamic library names should perhaps be changed from .so // to .dll).
- /**
Indicates that the filename represents a binary file. This is primarily
relevant to the read_file() and write_file() methods, so they can set the
appropriate flags to the OS.
*/
- setDirname()
C++ Interface: set_dirname(const Filename self, str s)
- /**
Replaces the directory part of the filename. This is everything in the
filename up to, but not including the rightmost slash.
*/
- setExtension()
C++ Interface: set_extension(const Filename self, 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()
C++ Interface: set_filesystem_encoding(int encoding)
- /**
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()
C++ Interface: set_fullpath(const Filename self, str s)
// You can also use any of these to reassign pieces of the filename.
- /**
Replaces the entire filename: directory, basename, extension. This can
also be achieved with the assignment operator.
*/
- setFullpathWoExtension()
C++ Interface: set_fullpath_wo_extension(const Filename self, str s)
- /**
Replaces the full filename–directory and basename parts–except for the
extension.
*/
- setHashToEnd()
C++ Interface: set_hash_to_end(const Filename self, str s)
- /**
Replaces the part of the filename from the beginning of the hash sequence
to the end of the filename.
*/
- setPattern()
C++ Interface: set_pattern(const Filename self, 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()
C++ Interface: set_text(const Filename self)
- /**
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()
C++ Interface: set_type(const Filename self, int 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).
*/
- set_basename()
C++ Interface: set_basename(const Filename self, str s)
- /**
Replaces the basename part of the filename. This is everything in the
filename after the rightmost slash, including any extensions.
*/
- set_basename_wo_extension()
C++ Interface: set_basename_wo_extension(const Filename self, str s)
- /**
Replaces the basename part of the filename, without the file extension.
*/
- set_binary()
C++ Interface: set_binary(const Filename self)
// Setting these flags appropriately is helpful when opening or searching // for a file; it helps the Filename resolve OS-specific conventions (for // instance, that dynamic library names should perhaps be changed from .so // to .dll).
- /**
Indicates that the filename represents a binary file. This is primarily
relevant to the read_file() and write_file() methods, so they can set the
appropriate flags to the OS.
*/
- set_dirname()
C++ Interface: set_dirname(const Filename self, str s)
- /**
Replaces the directory part of the filename. This is everything in the
filename up to, but not including the rightmost slash.
*/
- set_extension()
C++ Interface: set_extension(const Filename self, 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.
*/
- set_filesystem_encoding()
C++ Interface: set_filesystem_encoding(int encoding)
- /**
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.
*/
- set_fullpath()
C++ Interface: set_fullpath(const Filename self, str s)
// You can also use any of these to reassign pieces of the filename.
- /**
Replaces the entire filename: directory, basename, extension. This can
also be achieved with the assignment operator.
*/
- set_fullpath_wo_extension()
C++ Interface: set_fullpath_wo_extension(const Filename self, str s)
- /**
Replaces the full filename–directory and basename parts–except for the
extension.
*/
- set_hash_to_end()
C++ Interface: set_hash_to_end(const Filename self, str s)
- /**
Replaces the part of the filename from the beginning of the hash sequence
to the end of the filename.
*/
- set_pattern()
C++ Interface: set_pattern(const Filename self, 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.
*/
- set_text()
C++ Interface: set_text(const Filename self)
- /**
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.
*/
- set_type()
C++ Interface: set_type(const Filename self, int 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()
C++ Interface: standardize(const Filename self)
- /**
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()
C++ Interface: substr(Filename self, int begin) substr(Filename self, int begin, int end)
- temporary()
C++ Interface: temporary(str dirname, str prefix, str suffix, int type)
- /**
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()
C++ Interface: text_filename(const Filename filename) text_filename(str filename)
// Static constructors to explicitly create a filename that refers to a text // or binary file. This is in lieu of calling set_text() or set_binary() or // set_type().
- text_filename()
C++ Interface: text_filename(const Filename filename) text_filename(str filename)
// Static constructors to explicitly create a filename that refers to a text // or binary file. This is in lieu of calling set_text() or set_binary() or // set_type().
- toOsGeneric()
C++ Interface: to_os_generic(Filename self)
- /**
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()
C++ Interface: to_os_long_name(Filename self)
- /**
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()
C++ Interface: to_os_short_name(Filename self)
- /**
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()
C++ Interface: to_os_specific(Filename self)
- /**
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()
C++ Interface: to_os_specific_w(Filename self)
- /**
The wide-string variant on to_os_specific().
*/
- to_os_generic()
C++ Interface: to_os_generic(Filename self)
- /**
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.
*/
- to_os_long_name()
C++ Interface: to_os_long_name(Filename self)
- /**
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().
*/
- to_os_short_name()
C++ Interface: to_os_short_name(Filename self)
- /**
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().
*/
- to_os_specific()
C++ Interface: to_os_specific(Filename self)
- /**
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().
*/
- to_os_specific_w()
C++ Interface: to_os_specific_w(Filename self)
- /**
The wide-string variant on to_os_specific().
*/