filename_t Users Guide

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.

Related Documents


Parts of a File Name

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 filesystem_t class

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.

Members By Category

Getting and Setting Parts

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.

Higher Level Manipulation

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.

File System Aware Operations

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 Name Parts

Multiple names are not fully implemented.