The filename_t is a class to manipulate file names.
A file name is typically manipulated in certain ways, unlike a typical
string. Strings will have characters inserted or removed in arbitrary
position. File names, on the other hand, are treated in a more
structured manner: you will back up to a parent directory, change
the extension, replace ".." and "." parts, and so on.
This class faciliates this by treating a file name as a high-level object.
The file name's string is broken down into parts.
Conceptually, a file name is not a string of characters but is a list of parts. For example, "C:\foo\bar\baz.txt" is made up of four parts:, "C:", "foo", "bar", and "baz.txt". Backing up to the parent directory is simply a matter of removing the last path part.
This class recognises three different kinds of parts. The prefix
part comes first. It can be the drive letter ("D:"), share name ("\\Server"), or
network service ("http:").
The path parts are the various subdirectories.
The name part is the actual name, and follows the path parts
if the filename names a file rather than a subdirectory. "D:\foo\bar.txt" has
a name part of "bar.txt", but "D:\foo\" has no name part.
In addition, the class supports the concept of multiple name parts.
For example, "D:\foo\*.exe;*.dll;*.ocx" has three name parts.
The filename_t class uses a helper class to supply details of the parsing
and some control over the file system (e.g. the exists function).
The concrete class derived from filesystem_t contains the code to
split up a string into the various parts. Since each filename_t
object contains its own filesystem_t, each instance can
handle any kind of “name” independently of the others.
The PC Filesystem parser handles file names where the parts are separated by backslashes, and takes care of drive letters and UNC names.
The URL Filesystem parser, on the other hand, separates parts
with forward slashes, and handles the "http://" prefix which is slightly
different than a drive letter syntax.
In addition, the filesystem_t object is responsible for things
such as checking to see if a file exists and fully-qualifying a file name.
Much of what you want to do with a file name involves getting and setting parts.
text —Gets the whole thing as a string. To set the whole thing, use assignment.
prefix, set_prefix —Gets or sets the prefix part.
path, set_path, path_range, path_count, set_path_range —Gets or sets the path parts.
name, set_name, name_count, remove_name —Gets or sets the name parts.
Beyond the simple getting and setting of parts, there are functions for higher-level manipulation of file names.
common_root
—"D:\foo\bar.txt" and "D:\foo\subdir\baz.html"
have a common root of "D:\foo\".
concat —This is a fancy “change directory” feature. Concat’ing a relative path onto an existing path will apply that subdirectory; see the reference for other cases.
fully_qualify —This takes a relative or otherwise abbreviated path name and produces the fully-qualified name for the file.
exists —This tests for the existance of the file or directory.
assure_path_exists —This creates multiple tiers of a subdirectory, if necessary, to assure that the path part of this filename exists.
Multiple names are not fully implemented.