Path Class Reference
This reference page is linked to from the following overview topics: Relative Paths.
Detailed Description
Path type - adds path-operation richness over symbol strings.
The Path interface provides operations for path composition (Append and Prepend) and decomposition (StripToParent, StripToChild, RemoveParent, RemoveChild), query methods for determining information about a Path, such as whether it's absolute, relative, a root or a UNC, and finally, quick conversions from relative to absolute or absolute to relative.
Note paths are automatically kept in a standard form, where:
- all slashes '/' are converted to backslashes '\'.
- multiple backslashes in a row are collapsed down to one - '\\\' becomes '\'
Normalization is a separate, explicit method that must be called by the client. Normalization removes null directories '\.\' and adds in any missing backslash after the drive letter. Wherever possible, normalization will resolve out any ".." path components so: "r:\\dirA\\dirB\\..\\dirC" becomes "r:\\dirA\\dirC." If these hit the root, they just get stripped off, so "r:\\.." normalizes to "r:\\" If the path is relative, and there are more ".."s than preceding directories, * the extra sets are kept at the start of the path: "b\\..\\..\\c" becomes "..\\c" Any trailing backslash is kept on the path for compatibility with many win32 API functions. If a uniform trailing-backslash format is desired, for example, for display in the UI, it is up to client-level code to implement this policy. Unresolved symbols are left intact during normalization. Resolving the symbols in a string normalizes automatically.
To reiterate, normalization as performed by the Normalize() method is different from the basic standard form maintained by all members of Path. The client must call Normalize() explicitly (or ResolveSymbols() which is the only method that calls Normalize() automatically). The reason that these are kept separate is to keep from radically modifying a path in a way that may be surprising to a user. If the user wishes to construt a path with many '..\'s in it, the user will expect to see this result. Normalize() may then be called subsequently when it is deemed appropriate.
To illustrate the difference:
- "/a/b/c/./../" is neither in standard form nor normalized.
- "\\a\b\\c\\.." and "\\a\b\\c\\." are in standard form but not normalized.
- "\\a\b" and "\\a\b\\c" are both in standard form and normalized.
#include <Path.h>
Public Member Functions |
|
| UtilExport | Path () |
| Default constructor - creates an empty path.
|
|
| UtilExport | Path (const MSTR &pathString) |
| Construct a path from a path-filename
string. |
|
| UtilExport | Path (const MCHAR *pathString) |
| Construct from a null-terminated
path-filename MCHAR array. |
|
| UtilExport | Path (const Path &other) |
| Copy construct a Path
from another. |
|
| UtilExport | ~Path () |
| Destructor. |
|
| UtilExport Path & | SetPath (const Path &other) |
| Set this Path
from another. |
|
| UtilExport Path & | SetPath (const MCHAR *pathString) |
| Set this Path's internal string from a null
terminated character string. |
|
| UtilExport Path & | SetPath (const MSTR &pathString) |
| Set this Path
from a MSTR. |
|
| UtilExport Path & | operator= (const Path &other) |
| Assignment operator. |
|
| UtilExport Path & | operator= (const MCHAR *pathString) |
| Assignment operator taking a null terminated
character string. |
|
| UtilExport Path & | operator= (const MSTR &pathString) |
| Assignment operator. |
|
| UtilExport bool | IsAbsolute () const |
| Get whether this is an absolutely specified
path. |
|
| UtilExport bool | IsEmpty () const |
| Get whether this is an empty path. |
|
| UtilExport bool | IsLegal () const |
| Query whether this path doesn't have any
illegal characters according to the Windows platform rules.
|
|
| UtilExport bool | IsRoot () const |
| Check if this path is just a root. |
|
| UtilExport bool | IsUnc () const |
| Query whether this path is a UNC path.
|
|
| UtilExport bool | IsUncShare () const |
| Query whether this path fits the pattern for
a UNC share. |
|
| UtilExport bool | IsRootedAtBackslash () const |
| Query whether this path is rooted at
backslash, that is at the current drive with no drive letter.
|
|
| UtilExport bool | IsRootedAtDriveLetter () const |
| Query whether this path is rooted at a drive
letter. |
|
| UtilExport bool | HasUnresolvedSymbols () const |
| Query whether unresolved symbols remain in
this string. |
|
| UtilExport bool | StartsWithUpDirectory () const |
| Query with this path, when normalized,
starts with "..". |
|
| UtilExport bool | IsEqual (const Path &other) const |
| Query whether this and the passed-in path
are exactly the same. |
|
| UtilExport bool | operator== (const Path &other) const |
| Query whether this and the passed-in path
are exactly the same. |
|
| UtilExport bool | ResolvesEquivalent (const Path &other) const |
| Query whether this and the passed-in path
currently point to the same location. |
|
| UtilExport bool | HasTrailingBackslash () const |
| Query whether this path has a trailing
backslash. |
|
| UtilExport Path & | AddTrailingBackslash () |
| Add a backslash to the end of this path if
there isn't one already. |
|
| UtilExport Path & | RemoveTrailingBackslash () |
| Remove any trailing backslash from this
path. |
|
| UtilExport Path & | Prepend (const Path &newParent) |
| Add a new parent path to the start of this
path. |
|
| UtilExport Path & | Append (const Path &relativeChild) |
| Add a new child path at the end of this
path. |
|
| UtilExport Path & | StripToTopParent () |
| Strip all but the topmost parent from
this path. |
|
| UtilExport Path & | RemoveTopParent () |
| Remove the topmost parent from this path.
|
|
| UtilExport Path & | StripToLeaf () |
| Strip all but the very last child from
this path. |
|
| UtilExport Path & | RemoveLeaf () |
| Remove the very last child from this path.
|
|
| UtilExport Path & | ResolveSymbols () |
| Resolve out any symbols in the path string.
|
|
| UtilExport Path & | Normalize () |
| Transform this path into its normal form.
|
|
| UtilExport Path & | ConvertToLowerCase () |
| Convert all the characters in this path to
lower case. |
|
| UtilExport Path & | ConvertToRelativeTo (const Path &newBase) |
| Convert this absolute Path
so that it points to the same location, but relative to the new
base path. |
|
| UtilExport Path & | ConvertToUNC () |
| Convert this mapped drive Path
to a UNC path with a host and share name. |
|
| UtilExport Path & | ConvertToAbsolute () |
| Convert this relative path to absolute
rooted at the current 3ds Max Project Folder. |
|
| UtilExport const Path & | GetResolvedAbsolutePath () const |
| Get the fully-resolved, lower case, path
converted to absolute rooted at the current 3ds Max Project Folder.
|
|
| UtilExport Path & | ConvertToRelativeToProjectFolder () |
| Converts an absolute path into a path that
is relative to the current Project Folder. |
|
| UtilExport MSTR | GetString () const |
| Get the current string representation of
this path. |
|
| UtilExport const MCHAR * | GetCStr () const |
| Get the internal c-string formatted data
representation for this path. |
|
| PathImpl & | GetImpl () |
| Not exported outside the DLL - for use by
PathImpl only. |
|
| const PathImpl & | GetImpl () const |
| Not exported outside the DLL - for use by
PathImpl only. |
|
Constructor & Destructor Documentation
| UtilExport Path | ( | ) |
Default constructor - creates an empty path.
- Postcondition:
- IsEmpty() returns true.
Construct a path from a path-filename string.
- Parameters:
-
pathString path & filename as a string from which to construct a path object.
| UtilExport Path | ( | const MCHAR * | pathString | ) |
Construct from a null-terminated path-filename MCHAR array.
- Parameters:
-
pathString path & filename (must be null-terminated).
- Precondition:
- pathString is null terminated.
Copy construct a Path from another.
This performs a deep copy. Subsequent operations on this path will not affect the copied path and vice versa.
- Parameters:
-
other The path to copy.
| UtilExport ~Path | ( | ) |
Destructor.
Member Function Documentation
Set this Path from another.
Equivalent to the assignment operator, but more verbose.
- Parameters:
-
other - path to copy.
| UtilExport Path& SetPath | ( | const MCHAR * | pathString | ) |
Set this Path's internal string from a null terminated character string.
Equivalent to the assignment operator, but more verbose.
- Parameters:
-
pathString null-terminated character string to copy into this path.
Set this Path from a MSTR.
Equivalent to the assignment operator, but more verbose.
- Parameters:
-
pathString MSTR to copy into this path.
Assignment operator.
- Parameters:
-
other - path to copy
| UtilExport Path& operator= | ( | const MCHAR * | pathString | ) |
Assignment operator taking a null terminated character string.
- Parameters:
-
pathString null-terminated character string to copy into this path.
Assignment operator.
- Parameters:
-
pathString MSTR to copy into this path.
| UtilExport bool IsAbsolute | ( | ) | const |
Get whether this is an absolutely specified path.
An absolute path is rooted from a starting backslash (\), drive letter or UNC hostname.
- Returns:
- Returns true if this is an absolute path.
| UtilExport bool IsEmpty | ( | ) | const |
Get whether this is an empty path.
An empty path has a backing string representation of "".
- Returns:
- true if this is an empty path. Returns false otherwise.
| UtilExport bool IsLegal | ( | ) | const |
Query whether this path doesn't have any illegal characters according to the Windows platform rules.
Illegal characters are ':' for any character but the second and any occurrence of * ? " < > or |.
- Returns:
- true if the path appears to be legal, false if an illegal character was found.
| UtilExport bool IsRoot | ( | ) | const |
Check if this path is just a root.
Possible roots are:
- just backslash "\\"
- drive letter "c:\\"
- unc host "\\\\host"
- unc share "\\\\host\\share"
Note that all roots are absolute paths, but not all absolute paths are roots.
The host or drive letter does not have to exist. This path just has to fit the pattern.
- Returns:
- true if this path fits one of the patterns for a root outlined above, false other wise.
| UtilExport bool IsUnc | ( | ) | const |
Query whether this path is a UNC path.
A UNC path fits \\host or \\host\share or \\host\share\subdirectory\... The host doesn't necessarily have to exist.
- Returns:
- true if this path is a UNC, false otherwise.
| UtilExport bool IsUncShare | ( | ) | const |
Query whether this path fits the pattern for a UNC share.
The UNC share pattern is \\host\share.
- Returns:
- true if this path is a UNC share. False, otherwise.
| UtilExport bool IsRootedAtBackslash | ( | ) | const |
Query whether this path is rooted at backslash, that is at the current drive with no drive letter.
e.g. "\\abc\\def" is rooted at backslash.
- Returns:
- true if the first character is '\' and this is not a UNC.
| UtilExport bool IsRootedAtDriveLetter | ( | ) | const |
Query whether this path is rooted at a drive letter.
- Returns:
- true if this path is rooted at a drive letter like "c:\\dir\\dir"
| UtilExport bool HasUnresolvedSymbols | ( | ) | const |
Query whether unresolved symbols remain in this string.
- Returns:
- true if there are symbols yet to be resolved, false if all symbols have been resolved.
| UtilExport bool StartsWithUpDirectory | ( | ) | const |
Query with this path, when normalized, starts with "..".
- Returns:
- true if normalizing the path causes it to be relative to an ancestor path - ie, it starts with ".." False, otherwise.
| UtilExport bool IsEqual | ( | const Path & | other | ) | const |
Query whether this and the passed-in path are exactly the same.
This does not perform any path resolution to try to determine if the paths point to the same file. To be equal, the two paths must have exactly the same current representation.
- Parameters:
-
other a path to check for equality with this one.
- Returns:
- true if both paths are exactly the same.
| UtilExport bool operator== | ( | const Path & | other | ) | const |
Query whether this and the passed-in path are exactly the same.
This is a convenience operator overload. It calls IsEqual() under the hood.
- Parameters:
-
other a path to check for equality with this one.
- Returns:
- true if both paths are exactly the same.
| UtilExport bool ResolvesEquivalent | ( | const Path & | other | ) | const |
Query whether this and the passed-in path currently point to the same location.
This may not remain true (or false) if the paths contain symbols that may resolve differently later on.
- Parameters:
-
other a path to check for equivalence with this one
- Returns:
- true if both paths resolve out to pointing to the same location, false otherwise.
| UtilExport bool HasTrailingBackslash | ( | ) | const |
Query whether this path has a trailing backslash.
- Returns:
- true if this path has a trailing backslash.
| UtilExport Path& AddTrailingBackslash | ( | ) |
Add a backslash to the end of this path if there isn't one already.
- Returns:
- A reference to this Path. (This allows for operation chaining.)
| UtilExport Path& RemoveTrailingBackslash | ( | ) |
Remove any trailing backslash from this path.
Does nothing if there is no trailing backslash.
- Returns:
- A reference to this Path. (This allows for operation chaining.)
Add a new parent path to the start of this path.
While the usual cleaning up is done, Normalization is not performed. No checking is performed to verify that the resulting path will be legal. Generally, this Path should be relative while the new parent path may be absolute or relative.
Examples:
Path("a\\b\\c").Prepend(Path("e\\f\\g")) producesPath("e\\f\\g\\a\\b\\c")Path("c:\\").Prepend(Path("e\\f\\g")) producesPath("e\\f\\g\\c:")Path("a\\b\\c").Prepend(Path("c:\\")) producesPath("c:\\a\\b\\c")Path("").Prepend(Path("e\\f\\g")) producesPath("e\\f\\g")Path("..\\d").Prepend(Path("e\\f\\g")) producesPath("e\\f\\g\\..\\d") and normalizes toPath("e\\f\\d") after a call toNormalize()
To convert a relative path to an absolute path with an arbitrary base, simply Prepend that base to this relative path.
- Parameters:
-
newParent The new parent path to place at the start of this path.
- Returns:
- A reference to this Path. (This allows for operation chaining.)
Add a new child path at the end of this path.
While the usual cleaning up is done, Normalization is not performed. No checking is performed to verify that the resulting path will be legal. Generally, the new child should be relative should be relative, while this base path may be absolute or relative.
Examples:
Path("a\\b\\c").Append(Path("e\\f\\g")) producesPath("a\\b\\c\\e\\f\\g")Path("c:\\").Append(Path("e\\f\\g")) producesPath("c:\\e\\f\\g")Path("a\\b\\c").Append(Path("c:\\")) producesPath("a\\b\\c\\c:")Path("").Append(Path("e\\f\\g")) producesPath("e\\f\\g")Path("a\\b\\c").Append(Path("..\\d")) producesPath("a\\b\\c\\..\\d") and normalizes toPath("a\\b\\d") after a call toNormalize()
- Parameters:
-
relativeChild the new relative child component for this path.
- Returns:
- A reference to this Path. (This allows for operation chaining.)
| UtilExport Path& StripToTopParent | ( | ) |
Strip all but the topmost parent from this path.
Examples:
Path("a\\b\\c").StripToTopParent() producesPath("a")Path("c:\\dir").StripToTopParent() producesPath("c:\\")Path("a").StripToTopParent() producesPath("a")
- Returns:
- A reference to this Path. (This allows for operation chaining.)
| UtilExport Path& RemoveTopParent | ( | ) |
Remove the topmost parent from this path.
Examples:
Path("a\\b\\c").RemoveTopParent() producesPath("b\\c")Path("c:\\dir").RemoveTopParent() producesPath("dir")Path("a").RemoveTopParent() producesPath("")
- Returns:
- A reference to this Path. (This allows for operation chaining.)
| UtilExport Path& StripToLeaf | ( | ) |
Strip all but the very last child from this path.
Examples:
Path("a\\b\\c").StripToLeaf() producesPath("c")Path("c:\\dir").StripToLeaf() producesPath("dir")Path("a").StripToLeaf() producesPath("a")
- Returns:
- A reference to this Path. (This allows for operation chaining.)
| UtilExport Path& RemoveLeaf | ( | ) |
Remove the very last child from this path.
Examples:
Path("a\\b\\c").RemoveLeaf() producesPath("a\\b")Path("c:\\dir").RemoveLeaf() producesPath("c:\\")Path("a").RemoveLeaf() producesPath("")
- Returns:
- A reference to this Path. (This allows for operation chaining.)
| UtilExport Path& ResolveSymbols | ( | ) |
Resolve out any symbols in the path string.
After resolving the symbols, normalization is performed automatically. At the moment, this is an internal feature to 3ds Max, but is exposed to the SDK to support future functionality.
- Returns:
- A reference to this Path. (This allows for operation chaining.)
| UtilExport Path& Normalize | ( | ) |
Transform this path into its normal form.
This will clean up pieces not following the backslash rules outlined in the class documentation, and will convert ".."s as much as possible. "r:\\dirA\\dirB\\..\\dirC" becomes "r:\\dirA\\dirC." If these hit the root, they just get stripped off, so "r:\\.." normalizes to "r:\\" If the path is relative, and there are more ".."s than preceding directories, the extra sets are kept at the start of the path: "b\\..\\..\\c" becomes "..\\c"
Any symbols in the path will be maintained since a symbol may resolve out to more than one directory.
- Returns:
- A reference to this Path. (This allows for operation chaining.)
| UtilExport Path& ConvertToLowerCase | ( | ) |
Convert all the characters in this path to lower case.
- Returns:
- A reference to this Path. (This allows for operation chaining.)
Convert this absolute Path so that it points to the same location, but relative to the new base path.
The following attempted conversions are invalid and will leave the path unchanged:
- this path is already relative
- newBase is a relative path
- this path and newBase are both absolute but on different drives or hosts.
Example: Path("c:\\a\\b\\c").ConvertToRelativeTo(Path("c:\\a\\b\\d")
produces Path("..\\c")
- Parameters:
-
newBase absolute base path from which this Path must later be rooted to point to its current location again.
- Returns:
- A reference to this Path. (This allows for operation chaining.)
| UtilExport Path& ConvertToUNC | ( | ) |
| UtilExport Path& ConvertToAbsolute | ( | ) |
Convert this relative path to absolute rooted at the current 3ds Max Project Folder.
This will automatically resolve any symbols and normalize this path. If this Path already resolves to an absolute Path, it will ignore the current working directory. This does not resolve the path using the 3ds Max file search mechanism.
If conversion to an arbitrarily-rooted absolute path is desired,
Prepend should be used instead.
- Returns:
- A reference to this Path. (This allows for operation chaining.)
| UtilExport const Path& GetResolvedAbsolutePath | ( | ) | const |
Get the fully-resolved, lower case, path converted to absolute rooted at the current 3ds Max Project Folder.
This is a performance-oriented convenience method for clients that wish to hold on to the original, unresolved, relative path yet often need to access the absolute path.
- Returns:
- This path after it's been fully resolved, converted to absolute (rooted at the Project Folder), and converted to lower case.
| UtilExport Path& ConvertToRelativeToProjectFolder | ( | ) |
Converts an absolute path into a path that is relative to the current Project Folder.
Converts an absolute path into a path that is relative to the current Project Folder. If the path cannot be made relative (if it is rooted on a different drive, for instance), then it is left untouched. If the path is already relative, it is also left untouched.
- Returns:
- A reference to this Path. (This allows for operation chaining.)
| UtilExport MSTR GetString | ( | ) | const |
Get the current string representation of this path.
Note that this does not perform any symbol resolution or normalization.
- Returns:
- A copy of this Path's current string representation.
| UtilExport const MCHAR* GetCStr | ( | ) | const |
Get the internal c-string formatted data representation for this path.
Note that this c-string is not guaranteed to be consistent after any modifications are made to the Path object. If the data is needed persistently, consider either copying the contents of this pointer, or calling GetString() instead.
- Returns:
- A null-terminated c-string representation of the internals of this object.
| PathImpl& GetImpl | ( | ) |
Not exported outside the DLL - for use by PathImpl only.
- Returns:
- The internal implementation of this Path.
| const PathImpl& GetImpl | ( | ) | const |
Not exported outside the DLL - for use by PathImpl only.
Same as the other version, but this one's for const-context.
- Returns:
- The internal implementation of this Path.
