CXFilePath

The CXFilePath class provides an platform-neutral file path representation. The file paths are encoded in UTF8 with forward slash ("/") separators. A leading slash indicates an absolute path, otherwise the path is considered relative. The "/./" and "/../" constructs are supported for referring to the current directory and parent directory respectively. No other characters are reserved or prevented. CXFilePath objects are considered case sensitive, regardless of whether the underlying file system is or is not case sensitive.

 

The underlying CXFilePathBase templated class allows selection of a string container. CXFilePath is implemented as CXFilePathBase<CXString>. As an alternative, the application can use CXFilePathBase<CXStringEdit> instead of CXFilePath if high-performance editing is required.

 

Native Encodings

Where the host platform differs from these details, transformation between CXFilePath encoding and the native encoding occurs at the lowest possible level. The application should never need to deal with native encoding except where it is directly accessing native functions (bypassing the cxsource framework).

 

Windows

TBD.

C:\foo\bah.txt

C:\foo/bah.txt

\\machine\share\foo\bah.txt

\\?..

 

Posix

CXFilePath directly adopts posix filepath format and no significant transformations are required to convert between a posix file path and a CXFilePath. If the underlying APIs do not accept UTF-8 input, then a string codepage transformation may be required.

 

Construction

Various constructors are available to allow a CXFilePath to be build from a C String, string classes, etc.

//
CXFilePath(void);

//
CXFilePath(const char* __nullable path);
CXFilePath(const CXString& path);
CXFilePath(const CXStringEdit& path);
template <class OP> inline CXFilePath(const CXFilePathBase<OP>& other);

 

Nullness

CXFilePath does not distinguish between null and empty states. An empty filepath cannot be used to reference a file (although it can be appended as a relative filepath, to no effect) and so it is typically treated as a sentinel for a null / invalid / unset value.

// Returns true if this CXFilePath object has a non-zero length.
operator bool(void) const;

// Returns true if this CXFilePath is empty.
bool operator !(void) const;

 

Various methods are available for working with path components.

// Returns the filename portion of this path.
CXString GetFilename(void) const;
  
// Removes and returns the leftmost path element (root).
CXString StripLeftElement(bool bShouldStripFilenameElement = true);

// Remove and return the rightmost path element (filename).
CXString StripRightElement(void);

// Returns the path minus its rightmost path element.
CXString GetParentPath(void) const;

// Returns true if this object represents an absolute path.
// TBD.
bool IsAbsolutePath(void) const;

// Returns true if this object represents the filesystem root.
// TBD.
bool IsRoot(void) const;

// Returns true if this object contains a file name but no path separators.
bool IsFilenameOnly(void) const;

// Attempt to resolve any './' and '../' references, symlinks, etc.
// TBD.
bool Resolve(void);

 

String Manipulation

//
operator const char* __nonnull (void) const;

//
operator CXStringArgument(void) const;

//
const char& operator[](int pos) const;

//
size_t Length(void) const;

//
operator NSString* __nonnull (void) const;

//
const CXString& AsString(void) const;

//
const char* __nonnull c_str(void) const;

//
char GetFirstChar(void) const;

 

Comparison

//
bool operator==(const QUAL &p_path) const;

//
bool operator==(const CXString &p_str) const;

//
bool operator==(const char* __nonnull p_str) const;

//
bool operator!=(const QUAL &p_path) const;

//
bool operator!=(const CXString &p_str) const;

//
bool operator!=(const char* __nonnull p_str) const;

// sort operator
bool operator<(const QUAL &other) const;

 

Helper Methods

// convert to lowercase; useful for filename matching on case-insensitive systems
void ToLower(void);

//
static String GetSafeFilename(const char* __nonnull filename);

//
static CXFilePath ResolvePathRelativeTo(const CXFilePath& relativeOrAbsolutePath, const CXFilePath& basePathForRelative);

//
static CXFilePath GetPathRelativeTo(const CXFilePath& absolutePath, CXFilePath basePathForRelative);

//
static bool IsPathRelativeTo(const CXFilePath& absolutePath, const CXFilePath& basePathForRelative);

//
CXString AsFileURIString(void) const;

 

Streamers

//
template <CX_STREAMER_TMPL_DECL> CX_STREAMER_QUAL& operator << (CX_STREAMER_QUAL& stream, const CXFilePath& src);

//
template <CX_STREAMER_TMPL_DECL> CX_STREAMER_QUAL& operator >> (CX_STREAMER_QUAL& stream, CXFilePath& dst);

 

Stringification

//
void CXStringify(CXString& o_result, const CXFilePath& value);