CPathT Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

For the latest documentation on Visual Studio 2017, see CPathT Class on docs.microsoft.com. This class represents a path.

System_CAPS_ICON_important.jpg Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

template <typename StringType>
class CPathT

Parameters

StringType
The ATL/MFC string class to use for the path (see CStringT).

Public Typedefs

NameDescription
CPathT::PCXSTRA constant string type.
CPathT::PXSTRA string type.
CPathT::XCHARA character type.

Public Constructors

NameDescription
CPathT::CPathTThe constructor for the path.

Public Methods

NameDescription
CPathT::AddBackslashCall this method to add a backslash to the end of a string to create the correct syntax for a path.
CPathT::AddExtensionCall this method to add a file extension to a path.
CPathT::AppendCall this method to append a string to the current path.
CPathT::BuildRootCall this method to create a root path from a given drive number.
CPathT::CanonicalizeCall this method to convert the path to canonical form.
CPathT::CombineCall this method to concatenate a string representing a directory name and a string representing a file path name into one path.
CPathT::CommonPrefixCall this method to determine whether the specified path shares a common prefix with the current path.
CPathT::CompactPathCall this method to truncate a file path to fit within a given pixel width by replacing path components with ellipses.
CPathT::CompactPathExCall this method to truncate a file path to fit within a given number of characters by replacing path components with ellipses.
CPathT::FileExistsCall this method to check whether the file at this path name exists.
CPathT::FindExtensionCall this method to find the position of the file extension within the path.
CPathT::FindFileNameCall this method to find the position of the file name within the path.
CPathT::GetDriveNumberCall this method to search the path for a drive letter within the range of 'A' to 'Z' and return the corresponding drive number.
CPathT::GetExtensionCall this method to get the file extension from the path.
CPathT::IsDirectoryCall this method to check whether the path is a valid directory.
CPathT::IsFileSpecCall 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::IsPrefixCall this method to determine whether a path contains a valid prefix of the type passed by pszPrefix.
CPathT::IsRelativeCall this method to determine if the path is relative.
CPathT::IsRootCall this method to determine if the path is a directory root.
CPathT::IsSameRootCall this method to determine whether another path has a common root component with the current path.
CPathT::IsUNCCall this method to determine whether the path is a valid UNC (universal naming convention) path for a server and share.
CPathT::IsUNCServerCall this method to determine whether the path is a valid UNC (universal naming convention) path for a server only.
CPathT::IsUNCServerShareCall this method to determine whether the path is a valid UNC (universal naming convention) share path, \\ server\ share.
CPathT::MakePrettyCall this method to convert a path to all lowercase characters to give the path a consistent appearance.
CPathT::MatchSpecCall this method to search the path for a string containing a wildcard match type.
CPathT::QuoteSpacesCall this method to enclose the path in quotation marks if it contains any spaces.
CPathT::RelativePathToCall this method to create a relative path from one file or folder to another.
CPathT::RemoveArgsCall this method to remove any command-line arguments from the path.
CPathT::RemoveBackslashCall this method to remove the trailing backslash from the path.
CPathT::RemoveBlanksCall this method to remove all leading and trailing spaces from the path.
CPathT::RemoveExtensionCall this method to remove the file extension from the path, if there is one.
CPathT::RemoveFileSpecCall this method to remove the trailing file name and backslash from the path, if it has them.
CPathT::RenameExtensionCall 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::SkipRootCall this method to parse a path, ignoring the drive letter or UNC server/share path parts.
CPathT::StripPathCall this method to remove the path portion of a fully qualified path and file name.
CPathT::StripToRootCall this method to remove all parts of the path except for the root information.
CPathT::UnquoteSpacesCall this method to remove quotation marks from the beginning and end of a path.

Public Operators

NameDescription
CPathT::operator const StringType &This operator allows the object to be treated like a string.
CPathT::operator CPathT::PCXSTRThis 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

NameDescription
CPathT::m_strPathThe path.

CPath, CPathA, and CPathW are instantiations of CPathT defined as follows:

typedef CPathT< CString > CPath;

typedef CPathT< CStringA > CPathA;

typedef CPathT< CStringW > CPathW;

Header: atlpath.h

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.

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.

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.

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.

Call this method to convert the path to canonical form.

void Canonicalize();

Remarks

For more information, see PathCanonicalize.

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.

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.

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.

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.

The constructor.

CPathT(PCXSTR pszPath);
CPathT(const CPathT<StringType>& path);
CPathT() throw();

Parameters

pszPath
The pointer to a path string.

path
The path string.

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.

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.

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.

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.

Call this method to get the file extension from the path.

StringType GetExtension() const;

Return Value

Returns the file extension.

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.

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.

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.

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.

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.

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.

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.

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.

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.

The path.

StringType m_strPath;

Remarks

StringType is the template parameter to CPathT.

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.

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.

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.

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.

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.

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.

A constant string type.

typedef StringType::PCXSTR PCXSTR;

Remarks

StringType is the template parameter to CPathT.

A string type.

typedef StringType::PXSTR PXSTR;

Remarks

StringType is the template parameter to CPathT.

Call this method to enclose the path in quotation marks if it contains any spaces.

void QuoteSpaces();

Remarks

For more information, see PathQuoteSpaces.

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.

Call this method to remove any command-line arguments from the path.

void RemoveArgs();

Remarks

For more information, see PathRemoveArgs.

Call this method to remove the trailing backslash from the path.

void RemoveBackslash();

Remarks

For more information, see PathRemoveBackslash.

Call this method to remove all leading and trailing spaces from the path.

void RemoveBlanks();

Remarks

For more information, see PathRemoveBlanks.

Call this method to remove the file extension from the path, if there is one.

void RemoveExtension();

Remarks

For more information, see PathRemoveExtension.

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.

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.

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.

Call this method to remove the path portion of a fully qualified path and file name.

void StripPath();

Remarks

For more information, see PathStripPath.

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.

Call this method to remove quotation marks from the beginning and end of a path.

void UnquoteSpaces();

Remarks

For more information, see PathUnquoteSpaces.

A character type.

typedef StringType::XCHAR XCHAR;

Remarks

StringType is the template parameter to CPathT.

Classes
CStringT Class

Show: