CPathT Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CPathT Class.
This class represents a path.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
template <typename StringType>
class CPathT
Parameters
StringType
The ATL/MFC string class to use for the path (see CStringT).
Members
Public Typedefs
| Name | Description |
|---|---|
| CPathT::PCXSTR | A constant string type. |
| CPathT::PXSTR | A string type. |
| CPathT::XCHAR | A character type. |
Public Constructors
| Name | Description |
|---|---|
| CPathT::CPathT | The constructor for the path. |
Public Methods
| Name | Description |
|---|---|
| CPathT::AddBackslash | Call this method to add a backslash to the end of a string to create the correct syntax for a path. |
| CPathT::AddExtension | Call this method to add a file extension to a path. |
| CPathT::Append | Call this method to append a string to the current path. |
| CPathT::BuildRoot | Call this method to create a root path from a given drive number. |
| CPathT::Canonicalize | Call this method to convert the path to canonical form. |
| CPathT::Combine | Call this method to concatenate a string representing a directory name and a string representing a file path name into one path. |
| CPathT::CommonPrefix | Call this method to determine whether the specified path shares a common prefix with the current path. |
| CPathT::CompactPath | Call this method to truncate a file path to fit within a given pixel width by replacing path components with ellipses. |
| CPathT::CompactPathEx | Call this method to truncate a file path to fit within a given number of characters by replacing path components with ellipses. |
| CPathT::FileExists | Call this method to check whether the file at this path name exists. |
| CPathT::FindExtension | Call this method to find the position of the file extension within the path. |
| CPathT::FindFileName | Call this method to find the position of the file name within the path. |
| CPathT::GetDriveNumber | Call this method to search the path for a drive letter within the range of 'A' to 'Z' and return the corresponding drive number. |
| CPathT::GetExtension | Call this method to get the file extension from the path. |
| CPathT::IsDirectory | Call this method to check whether the path is a valid directory. |
| CPathT::IsFileSpec | Call this method to search a path for any path-delimiting characters (for example, ':' or '\' ). If there are no path-delimiting characters present, the path is considered to be a File Spec path. |
| CPathT::IsPrefix | Call this method to determine whether a path contains a valid prefix of the type passed by pszPrefix. |
| CPathT::IsRelative | Call this method to determine if the path is relative. |
| CPathT::IsRoot | Call this method to determine if the path is a directory root. |
| CPathT::IsSameRoot | Call this method to determine whether another path has a common root component with the current path. |
| CPathT::IsUNC | Call this method to determine whether the path is a valid UNC (universal naming convention) path for a server and share. |
| CPathT::IsUNCServer | Call this method to determine whether the path is a valid UNC (universal naming convention) path for a server only. |
| CPathT::IsUNCServerShare | Call this method to determine whether the path is a valid UNC (universal naming convention) share path, \\ server\ share. |
| CPathT::MakePretty | Call this method to convert a path to all lowercase characters to give the path a consistent appearance. |
| CPathT::MatchSpec | Call this method to search the path for a string containing a wildcard match type. |
| CPathT::QuoteSpaces | Call this method to enclose the path in quotation marks if it contains any spaces. |
| CPathT::RelativePathTo | Call this method to create a relative path from one file or folder to another. |
| CPathT::RemoveArgs | Call this method to remove any command-line arguments from the path. |
| CPathT::RemoveBackslash | Call this method to remove the trailing backslash from the path. |
| CPathT::RemoveBlanks | Call this method to remove all leading and trailing spaces from the path. |
| CPathT::RemoveExtension | Call this method to remove the file extension from the path, if there is one. |
| CPathT::RemoveFileSpec | Call this method to remove the trailing file name and backslash from the path, if it has them. |
| CPathT::RenameExtension | Call this method to replace the file name extension in the path with a new extension. If the file name does not contain an extension, the extension will be attached to the end of the string. |
| CPathT::SkipRoot | Call this method to parse a path, ignoring the drive letter or UNC server/share path parts. |
| CPathT::StripPath | Call this method to remove the path portion of a fully qualified path and file name. |
| CPathT::StripToRoot | Call this method to remove all parts of the path except for the root information. |
| CPathT::UnquoteSpaces | Call this method to remove quotation marks from the beginning and end of a path. |
Public Operators
| Name | Description |
|---|---|
| CPathT::operator const StringType & | This operator allows the object to be treated like a string. |
| CPathT::operator CPathT::PCXSTR | This operator allows the object to be treated like a string. |
| CPathT::operator StringType & | This operator allows the object to be treated like a string. |
| CPathT::operator += | This operator appends a string to the path. |
Public Data Members
| Name | Description |
|---|---|
| CPathT::m_strPath | The path. |
Remarks
CPath, CPathA, and CPathW are instantiations of CPathT defined as follows:
typedef CPathT< CString > CPath;
typedef CPathT< CStringA > CPathA;
typedef CPathT< CStringW > CPathW;
Requirements
Header: atlpath.h
CPathT::AddBackslash
Call this method to add a backslash to the end of a string to create the correct syntax for a path. If the path already has a trailing backslash, no backslash will be added.
void AddBackslash();
Remarks
For more information, see PathAddBackSlash.
CPathT::AddExtension
Call this method to add a file extension to a path.
BOOL AddExtension(PCXSTR pszExtension);
Parameters
pszExtension
The file extension to add.
Return Value
Returns TRUE on success, FALSE on failure.
Remarks
For more information, see PathAddExtension.
CPathT::Append
Call this method to append a string to the current path.
BOOL Append(PCXSTR pszMore);
Parameters
pszMore
The string to append.
Return Value
Returns TRUE on success, FALSE on failure.
Remarks
For more information, see PathAppend.
CPathT::BuildRoot
Call this method to create a root path from a given drive number.
void BuildRoot(int iDrive);
Parameters
iDrive
The drive number (0 is A:, 1 is B:, and so on).
Remarks
For more information, see PathBuildRoot.
CPathT::Canonicalize
Call this method to convert the path to canonical form.
void Canonicalize();
Remarks
For more information, see PathCanonicalize.
CPathT::Combine
Call this method to concatenate a string representing a directory name and a string representing a file path name into one path.
void Combine(PCXSTR pszDir, PCXSTR pszFile);
Parameters
pszDir
The directory path.
pszFile
The file path.
Remarks
For more information, see PathCombine.
CPathT::CommonPrefix
Call this method to determine whether the specified path shares a common prefix with the current path.
CPathT<StringType> CommonPrefix(PCXSTR pszOther);
Parameters
pszOther
The path to compare to the current one.
Return Value
Returns the common prefix.
Remarks
A prefix is one of these types: "C:\\", ".", "..", "..\\". For more information, see PathCommonPrefix.
CPathT::CompactPath
Call this method to truncate a file path to fit within a given pixel width by replacing path components with ellipses.
BOOL CompactPath(HDC hDC, UINT nWidth);
Parameters
hDC
The device context used for font metrics.
nWidth
The width, in pixels, that the string will be forced to fit in.
Return Value
Returns TRUE on success, FALSE on failure.
Remarks
For more information, see PathCompactPath.
CPathT::CompactPathEx
Call this method to truncate a file path to fit within a given number of characters by replacing path components with ellipses.
BOOL CompactPathEx(UINT nMaxChars, DWORD dwFlags = 0);
Parameters
nMaxChars
The maximum number of characters to be contained in the new string, including the terminating NULL character.
dwFlags
Reserved.
Return Value
Returns TRUE on success, FALSE on failure.
Remarks
For more information, see PathCompactPathEx.
CPathT::CPathT
The constructor.
CPathT(PCXSTR pszPath);
CPathT(const CPathT<StringType>& path);
CPathT() throw();
Parameters
pszPath
The pointer to a path string.
path
The path string.
CPathT::FileExists
Call this method to check whether the file at this path name exists.
BOOL FileExists() const;
Return Value
Returns TRUE if the file exists, FALSE otherwise.
Remarks
For more information, see PathFileExists.
CPathT::FindExtension
Call this method to find the position of the file extension within the path.
int FindExtension() const;
Return Value
Returns the position of the "." preceding the extension. If no extension is found, returns –1.
Remarks
For more information, see PathFindExtension.
CPathT::FindFileName
Call this method to find the position of the file name within the path.
int FindFileName() const;
Return Value
Returns the position of the file name. If no file name is found, returns –1.
Remarks
For more information, see PathFindFileName.
CPathT::GetDriveNumber
Call this method to search the path for a drive letter within the range of 'A' to 'Z' and return the corresponding drive number.
int GetDriveNumber() const;
Return Value
Returns the drive number as an integer from 0 through 25 (corresponding to 'A' through 'Z') if the path has a drive letter, or -1 otherwise.
Remarks
For more information, see PathGetDriveNumber.
CPathT::GetExtension
Call this method to get the file extension from the path.
StringType GetExtension() const;
Return Value
Returns the file extension.
CPathT::IsDirectory
Call this method to check whether the path is a valid directory.
BOOL IsDirectory() const;
Return Value
Returns a non-zero value (16) if the path is a directory, FALSE otherwise.
Remarks
For more information, see PathIsDirectory.
CPathT::IsFileSpec
Call this method to search a path for any path-delimiting characters (for example, ':' or '\' ). If there are no path-delimiting characters present, the path is considered to be a File Spec path.
BOOL IsFileSpec() const;
Return Value
Returns TRUE if there are no path-delimiting characters within the path, or FALSE if there are path-delimiting characters.
Remarks
For more information, see PathIsFileSpec.
CPathT::IsPrefix
Call this method to determine whether a path contains a valid prefix of the type passed by pszPrefix.
BOOL IsPrefix(PCXSTR pszPrefix) const;
Parameters
pszPrefix
The prefix for which to search. A prefix is one of these types: "C:\\", ".", "..", "..\\".
Return Value
Returns TRUE if the path contains the prefix, or FALSE otherwise.
Remarks
For more information, see PathIsPrefix.
CPathT::IsRelative
Call this method to determine if the path is relative.
BOOL IsRelative() const;
Return Value
Returns TRUE if the path is relative, or FALSE if it is absolute.
Remarks
For more information, see PathIsRelative.
CPathT::IsRoot
Call this method to determine if the path is a directory root.
BOOL IsRoot() const;
Return Value
Returns TRUE if the path is a root, or FALSE otherwise.
Remarks
For more information, see PathIsRoot.
CPathT::IsSameRoot
Call this method to determine whether another path has a common root component with the current path.
BOOL IsSameRoot(PCXSTR pszOther) const;
Parameters
pszOther
The other path.
Return Value
Returns TRUE if both strings have the same root component, or FALSE otherwise.
Remarks
For more information, see PathIsSameRoot.
CPathT::IsUNC
Call this method to determine whether the path is a valid UNC (universal naming convention) path for a server and share.
BOOL IsUNC() const;
Return Value
Returns TRUE if the path is a valid UNC path, or FALSE otherwise.
Remarks
For more information, see PathIsUNC.
CPathT::IsUNCServer
Call this method to determine whether the path is a valid UNC (universal naming convention) path for a server only.
BOOL IsUNCServer() const;
Return Value
Returns TRUE if the string is a valid UNC path for a server only (no share name), or FALSE otherwise.
Remarks
For more information, see PathIsUNCServer.
CPathT::IsUNCServerShare
Call this method to determine whether the path is a valid UNC (universal naming convention) share path, \\ server\ share.
BOOL IsUNCServerShare() const;
Return Value
Returns TRUE if the path is in the form \\ server\ share, or FALSE otherwise.
Remarks
For more information, see PathIsUNCServerShare.
CPathT::m_strPath
The path.
StringType m_strPath;
Remarks
StringType is the template parameter to CPathT.
CPathT::MakePretty
Call this method to convert a path to all lowercase characters to give the path a consistent appearance.
BOOL MakePretty();
Return Value
Returns TRUE if the path has been converted, or FALSE otherwise.
Remarks
For more information, see PathMakePretty.
CPathT::MatchSpec
Call this method to search the path for a string containing a wildcard match type.
BOOL MatchSpec(PCXSTR pszSpec) const;
Parameters
pszSpec
Pointer to a null-terminated string with the file type for which to search. For example, to test whether the file at the current path is a DOC file, pszSpec should be set to "*.doc".
Return Value
Returns TRUE if the string matches, or FALSE otherwise.
Remarks
For more information, see PathMatchSpec.
CPathT::operator +=
This operator appends a string to the path.
CPathT<StringType>& operator+=(PCXSTR pszMore);
Parameters
pszMore
The string to append.
Return Value
Returns the updated path.
CPathT::operator const StringType &
This operator allows the object to be treated like a string.
operatorconst StringType&() const throw();
Return Value
Returns a string representing the current path managed by this object.
CPathT::operator CPathT::PCXSTR
This operator allows the object to be treated like a string.
operatorPCXSTR() const throw();
Return Value
Returns a string representing the current path managed by this object.
CPathT::operator StringType &
This operator allows the object to be treated like a string.
operatorStringType&() throw();
Return Value
Returns a string representing the current path managed by this object.
CPathT::PCXSTR
A constant string type.
typedef StringType::PCXSTR PCXSTR;
Remarks
StringType is the template parameter to CPathT.
CPathT::PXSTR
A string type.
typedef StringType::PXSTR PXSTR;
Remarks
StringType is the template parameter to CPathT.
CPathT::QuoteSpaces
Call this method to enclose the path in quotation marks if it contains any spaces.
void QuoteSpaces();
Remarks
For more information, see PathQuoteSpaces.
CPathT::RelativePathTo
Call this method to create a relative path from one file or folder to another.
BOOL RelativePathTo(
PCXSTR pszFrom,
DWORD dwAttrFrom,
PCXSTR pszTo,
DWORD dwAttrTo);
Parameters
pszFrom
The start of the relative path.
dwAttrFrom
The File attributes of pszFrom. If this value contains FILE_ATTRIBUTE_DIRECTORY, pszFrom is assumed to be a directory; otherwise, pszFrom is assumed to be a file.
pszTo
The end point of the relative path.
dwAttrTo
The File attributes of pszTo. If this value contains FILE_ATTRIBUTE_DIRECTORY, pszTo is assumed to be a directory; otherwise, pszTo is assumed to be a file.
Return Value
Returns TRUE on success, FALSE on failure.
Remarks
For more information, see PathRelativePathTo.
CPathT::RemoveArgs
Call this method to remove any command-line arguments from the path.
void RemoveArgs();
Remarks
For more information, see PathRemoveArgs.
CPathT::RemoveBackslash
Call this method to remove the trailing backslash from the path.
void RemoveBackslash();
Remarks
For more information, see PathRemoveBackslash.
CPathT::RemoveBlanks
Call this method to remove all leading and trailing spaces from the path.
void RemoveBlanks();
Remarks
For more information, see PathRemoveBlanks.
CPathT::RemoveExtension
Call this method to remove the file extension from the path, if there is one.
void RemoveExtension();
Remarks
For more information, see PathRemoveExtension.
CPathT::RemoveFileSpec
Call this method to remove the trailing file name and backslash from the path, if it has them.
BOOL RemoveFileSpec();
Return Value
Returns TRUE on success, FALSE on failure.
Remarks
For more information, see PathRemoveFileSpec.
CPathT::RenameExtension
Call this method to replace the file name extension in the path with a new extension. If the file name does not contain an extension, the extension will be attached to the end of the path.
BOOL RenameExtension(PCXSTR pszExtension);
Parameters
pszExtension
The new file name extension, preceded by a "." character.
Return Value
Returns TRUE on success, FALSE on failure.
Remarks
For more information, see PathRenameExtension.
CPathT::SkipRoot
Call this method to parse a path, ignoring the drive letter or UNC (universal naming convention) server/share path parts.
int SkipRoot() const;
Return Value
Returns the position of the beginning of the subpath that follows the root (drive letter or UNC server/share).
Remarks
For more information, see PathSkipRoot.
CPathT::StripPath
Call this method to remove the path portion of a fully qualified path and file name.
void StripPath();
Remarks
For more information, see PathStripPath.
CPathT::StripToRoot
Call this method to remove all parts of the path except for the root information.
BOOL StripToRoot();
Return Value
Returns TRUE if a valid drive letter was found in the path, or FALSE otherwise.
Remarks
For more information, see PathStripToRoot.
CPathT::UnquoteSpaces
Call this method to remove quotation marks from the beginning and end of a path.
void UnquoteSpaces();
Remarks
For more information, see PathUnquoteSpaces.
CPathT::XCHAR
A character type.
typedef StringType::XCHAR XCHAR;
Remarks
StringType is the template parameter to CPathT.