Edit

CPathT Class

  • Article

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 ellipsis.
CPathT::CompactPathEx Call this method to truncate a file path to fit within a given number of characters by replacing path components with ellipsis.
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 ellipsis.

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 ellipsis.

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.

operator const 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.

operator PCXSTR() 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.

operator StringType&() 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.

See also

Classes
CStringT Class