filename_t class reference

The filename_t is a class to manipulate file names. See the User’s Guide for more discussion.


filename_t (const ustring& s)

filename_t (cow<filesystem_t>)

filename_t (const ustring& s, cow<filesystem_t>)

filename_t

constructor, public

A filename_t object is created given a string, a filesystem_t, or both.

The string is the file name, which is parsed into its parts. If omitted, the filename is empty. Note that the string is taken as a file name unless it ends in a path separator character, in which case it’s taken as a directory without a file name. Use directory to produce a directory (not a file name) regardless of the presence of a trailing separator.

For example, "F:\foo\bar" is a file named "bar" in a directory "foo", while "F:\foo\bar\" is the subdirectory "bar".

The filesystem_t specifies which file system is associated with this object. If omitted, the value of default_filesystem is used.

See also: operator=, directory


filename_t (const filename_t& other)

filename_t

constructor, public

The copy constructor is unsurprising.


~filename_t()

filename_t

destructor, public

The destructor is unsurprising.


filename_t& operator= (const filename_t&)

filename_t

public

The copy assignment operator is unsurprising.


filename_t& operator= (const ustring& text)

filename_t

public

This assignment operator specifies a new string that will be parsed into parts (see notes for the constructor), completely replacing the existing parts.


bool absolute() const

filename_t

[group] public

This function returns true if there is at least one path part and the first path part is empty. It's more efficient then doing the above checking using other public functions.

An absolute path is represented with a blank part as the first part, which is a natural thing to do if you consider each part to be followed by a separator character (which is not included in the part).

Here we see the structure of the relative "D:foo\subdir\x\bar.txt"
vs. the absolute "D:\foo\subdir\x\bar.txt".
Note that backslashes are separators, not part of the part, but are shown in the table to clearly illustrate the correspondence between the internal structure and how the string was parsed. Basically, each backslash indicates the end of a path part.

prefix path name
0 1 2 3
D: foo \ subdir \ x \ bar.txt
D: \ foo \ subdir \ x \ bar.txt

filename_t add_path (const ustring&) const

void add_path_this (const ustring&)

filename_t

[group] public

This appends a single part to the path of this filename. The string should not contain part delimiter characters (e.g. backslash for PC file system)—if it does, the results are unspecified.

add_path will return the result as a new object and does not affect the original, while add_path_this will modify the object in-place. In general, foo is to foo_this as operator+ is to operator+=.

filename_t x= ustring("F:\\foo\\bar\\notes.txt");
filename_t y= x.add_path ("baz");
// produces  F:\foo\bar\baz\notes.txt
x.add_path_this ("baz");
// same as  x=x.add_path("baz")
The contents of the string to be appended are taken literally. That is, no special processing is done for ".." directories.

See also: cdd.


void assure_path_exists() const

filename_t

[group] public

Equivilent to get_filesystem()->assure_path_exists (*this), but without making a temporary clone1 of the filesystem_t object.


filename_t cdd (const filename_t& other) const

void cdd_this (const filename_t& other)

filename_t

[group] public

This function is like a generalized "change directory" function. This filename_t is the starting point, and the other is the “change directory” command argument.

cdd will return the result as a new object and does not affect the original, while cdd_this will modify the object in-place. In general, foo is to foo_this as operator+ is to operator+=.

The behavior is similar to the CDD (change drive and directory) command in the “4NT” command shell, or CD /D in the version of the “CMD” shell that ships with NT4.0.

If the argument contains a prefix part, then the prefix and path of other replace the prefix and part in this object.

Otherwise the argument has no prefix. If the argument has an absolute path (it begins with the empty part indicating a leading slash) then the argument’s path replaces this path. Otherwise (the argument has a relative path) the argument’s path parts are appended to this path, with special logic for dotname parts.

When appending “dot” path parts, the path part "." (or however these special names are spelled if you override dotname) is ignored; ".." removes a part instead; "..." removes two parts; etc. If there are not enough parts remaining to remove, or if a part to be removed is itself a “dot” part, then the “dot” part is not treated specially but gets appended to this path like any normal part name (see explaination in remove_path).

Note that in no case is the name part of this object affected.

See also: add_pathremove_path

Draws behavior from: this->get_filesystem()–>dotname()


int common_root (const filename_t& other) const

filename_t

[group] public

This tells you how many nodes two paths have in common, starting from the top. The prefix part and the filename part are not relevant.

Starting at the beginning of each path, this function counts how many corresponding parts match exactly.

For example, "D:\foo\y\bar.txt" and "C:\foo\subdir\x\baz.html" have a common root of "\foo\". This function returns 2, indicating that the first two parts from either filename_t matches the other. Here is how it is counted:

prefix path name
0 1 2 3
D: \ foo\ y\ bar.txt
C: \ foo\ subdir\ x\ baz.html

Path part 0 and path part 1 are the same, so the function returns 2, meaning two matching parts. The difference in the prefix is not a consideration.


bool exists() const

filename_t

[group] public

Equivilent to get_filesystem()->exists (*this), but without making a temporary clone1 of the filesystem_t object.


filename_t fully_qualify() const

void fully_qualify_this()

filename_t

[group] public

Equivilent to get_filesystem()->fully_qualify (*this)
and *this= get_filesystem()->fully_qualify (*this), respectivly, but without making a temporary clone1 of the filesystem_t object.


cow<filesystem_t> get_filesystem() const

filename_t

[group] public

This returns the filesystem_t associated with this object, as specified originally in the constructor.


bool has_prefix() const

filename_t

[group] public

This returns true if the prefix part is not empty.


filename_t make_relative_to (
const filename_t& root, bool usedots=false) const

void make_relative_to_this (
const filename_t& root, bool usedots=false)

filename_t

[group] public

This makes a relative path so that the result applied to the root parameter is equal to the input value of *this.

make_relative_to will return the result as a new object and does not affect the original, while make_relative_to_this will modify the object in-place. In general, foo is to foo_this as operator+ is to operator+=.

Need more discussion, and docs for usedots


ustring name() const

filename_t

[group] public

This returns the name proper (no path or prefix) of this object as a string.


int name_count() const

filename_t

[group] public

This returns the number of name parts in this filename_t. Normally this will be 1 to indicate that a name is present, or 0 to indicate that this is a directory only without a specific file name.

This class supports multiple names, so the value may be greater than 1.


ustring path() const

filename_t

[group] public

This returns the entire path, not including the prefix or the name. The separator character used is taken from the attached filesystem, and no separator appears after the last part. A separator appears before the first part to indicate an absolute path (see further explaination in the absolute documentation). For example, the path() of "D:\foo\bar\baz.html" is "\foo\bar".

See the examples in the test2() function in filename_t_test.cxx.


ustring path (int index) const

filename_t

[group] public

This returns a single path part, with no delimiters around it.

For an absolute path, as "D:\foo\bar\baz.html", the index of 0 will be a blank entry. For relative names, the first path part (index==0) will be the first named part.

See also: path_range


int path_count() const

filename_t

[group] public

This returns the number of path parts. Note that absolute paths are denoted by having an empty first element. So path_count ("D:\foo\bar\baz.html") is 3, while path_count ("D:foo\bar\baz.html") is 2. In other words, the empty node indicates “start from the top” and does take up a slot in the array. See the examples in the test2() function in filename_t_test.cxx.


ustring path_range (int n, int m) const

filename_t

[group] public

While path(int) gets a single part, and path() gets all parts, this function is more general and can get any contiguous range of parts. The parameter n is the first part returned, and m is the last part returned, inclusive. The legal range is ≥0 and <path_count().


ustring prefix() const

filename_t

[group] public

This returns the prefix part of the file name. For PC file system names this will be the drive letter or UNC server name. For URL names it is the service.

This function may return an empty string to indicate “no prefix”. The prefix count is always one, and the lack of a prefix on a file specification is indicated with an empty string here.

See also: has_prefix


filename_t remove_name() const

void remove_name_this()

filename_t

[group] public

This removes the name (or multiple names) from this object. After calling it, name_count() on the result will return 0 and name() will return an empty string.

remove_name will return the result as a new object and does not affect the original, while remove_name_this will modify the object in-place. In general, foo is to foo_this as operator+ is to operator+=.


filename_t remove_path (int count) const

bool remove_path_this (int count, bool detect_dots)

filename_t

[group] public

This function attempts to remove count parts from the end of the path. If there are not enough parts available, it returns false and no change is made. On success, it returns true.

remove_path will return the result as a new object and does not affect the original, while remove_path_this will modify the object in-place. In general, foo is to foo_this as operator+ is to operator+=. In this case, the non-this form cannot return a status value, so is not really exactly the same. Both forms are provided anyway for consistancy.

In the remove_path_this function, if the detect_dots flag is specified, then special “dot” name parts cannot be removed and the function indicates this by returning false. Otherwise (detect_dots is false or not available) the dot names are not significant and any path is removed without looking at content.

Draws behavior from: this->get_filesystem()–>dotname(int)


bool same_prefix (const filename_t& other) const

filename_t

[group] public

Returns true if the prefix of the objects are the same, using the string matching rules (e.g. case sensitivity) of the filesystem_t attached to this object.


filename_t set_name (const ustring&) const

void set_name_this (const ustring& s)

filename_t

[group] public

This sets the name part to the specified string. If the string contains part delimiter characters (e.g. backslash for PC file system), the results are unspecified.

set_name will return the result as a new object and does not affect the original, while set_name_this will modify the object in-place. In general, foo is to foo_this as operator+ is to operator+=.

If the parameter string is empty, the name is removed (name_count() will become 0). The string may contain name separator characters as defined in the filesystem helper object to set multiple names (e.g. "*.exe;*.dll").


filename_t set_path (const ustring& s) const

void set_path_this (const ustring& s)

filename_t

[group] public

This sets the path part to the specified string. If the string contains part delimiter characters (e.g. backslash for PC file system), the new path will have multiple parts.

set_path will return the result as a new object and does not affect the original, while set_path_this will modify the object in-place. In general, foo is to foo_this as operator+ is to operator+=.


filename_t set_path_range (int n, int m, const ustring& s) const

void set_path_range_this (int n, int m, const ustring& s)

filename_t

[group] public

This replaces the path parts specified. The parameters n and m are as used in path_range(n,m), and the string is as used with set_path.

set_path_range will return the result as a new object and does not affect the original, while set_path_range_this will modify the object in-place. In general, foo is to foo_this as operator+ is to operator+=.


filename_t set_prefix (const ustring& s) const

void set_prefix_this (const ustring& s)

filename_t

[group] public

This sets the prefix of the file name.

set_prefix will return the result as a new object and does not affect the original, while set_prefix_this will modify the object in-place. In general, foo is to foo_this as operator+ is to operator+=.

Currently, setting an invalid prefix doesn’t cause any error, and the results are unspecified. This needs to be improved to detect errors at the point the change is made.


ustring text() const

filename_t

[group] public

This returns the entire contents of the file name as a string. The proper delimiters are inserted between the parts as described by the filesystem_t helper object.


__int64 timestamp() const

filename_t

[group] public

Equivilent to get_filesystem()->timestamp (*this), but without making a temporary clone1 of the filesystem_t object.


Footnotes

temporary copy of filesystem_t object:

The cow (copy on write) smart pointer returned from get_filesystem has an operator-> function, which is what makes it a smart pointer. Unfortunatly, the operator-> cannot distinguish whether the function that will be called on its return value will be a const or a non-const member. So any use of cow<filesystem_t>::operator-> will trigger the copy.