The filename_t is a class to manipulate file names.
See the User’s Guide for more discussion.
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
constructor, public
The copy constructor is unsurprising.
destructor, public
The destructor is unsurprising.
public
The copy assignment operator is unsurprising.
public
This assignment operator specifies a new string that will be parsed into parts (see notes for the constructor), completely replacing the existing parts.
[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 |
[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.
[group] public
Equivilent to get_filesystem()->assure_path_exists (*this),
but without making a temporary clone1 of the filesystem_t object.
[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_path, remove_path
Draws behavior from: this->get_filesystem()–>dotname()
[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.
[group] public
Equivilent to get_filesystem()->exists (*this),
but without making a temporary clone1 of the filesystem_t object.
[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.
[group] public
This returns the filesystem_t associated with this object, as specified originally in the constructor.
[group] public
This returns true if the prefix part is not empty.
[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
[group] public
This returns the name proper (no path or prefix) of this object as a string.
[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.
[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.
[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
[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.
[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().
[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
[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+=.
[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)
[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.
[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").
[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+=.
[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+=.
[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.
[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.
[group] public
Equivilent to get_filesystem()->timestamp (*this),
but without making a temporary clone1 of the filesystem_t object.
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.