CPathT Class

Artículo
06/05/2017

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.

Compartir a través de

CPathT Class

Syntax

Parameters

Members

Public Typedefs

Public Constructors

Public Methods

Public Operators

Public Data Members

Remarks

Requirements

CPathT::AddBackslash

Remarks

CPathT::AddExtension

Parameters

Return Value

Remarks

CPathT::Append

Parameters

Return Value

Remarks

CPathT::BuildRoot

Parameters

Remarks

CPathT::Canonicalize

Remarks

CPathT::Combine

Parameters

Remarks

CPathT::CommonPrefix

Parameters

Return Value

Remarks

CPathT::CompactPath

Parameters

Return Value

Remarks

CPathT::CompactPathEx

Parameters

Return Value

Remarks

CPathT::CPathT

Parameters

CPathT::FileExists

Return Value

Remarks

CPathT::FindExtension

Return Value

Remarks

CPathT::FindFileName

Return Value

Remarks

CPathT::GetDriveNumber

Return Value

Remarks

CPathT::GetExtension

Return Value

CPathT::IsDirectory

Return Value

Remarks

CPathT::IsFileSpec

Return Value

Remarks

CPathT::IsPrefix

Parameters

Return Value

Remarks

CPathT::IsRelative

Return Value

Remarks

CPathT::IsRoot

Return Value

Remarks

CPathT::IsSameRoot

Parameters

Return Value

Remarks

CPathT::IsUNC

Return Value