The CXFilePath class provides an platform-neutral file path representation. The file paths are encoded in UTF8 with forward slash ("/") separators. 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.

CXFilePath is intended to refer to paths in the local file system, and as such its behaviour may differ in subtle ways depending on the host platform. Specifically, the concept of a "file system root" differs between OSes, and the platforms may differ with respect to which characters or names are permissible. It is uncommon that the application would need to be aware of these differences.

The standard "/./" and "/../" constructs are supported for referring to the current directory and parent directory respectively.

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

Win32

Windows filepaths are UTF-16 encoded, use backslash ("\") separators, have virtually unlimited length and support a wide range of characters. Unfortunately, the Windows shell imposes a lot of legacy restrictions on paths, such that a typical path is limited to 230 characters, allows a forward slash ("/") separator in most but not all cases, doesn't allow certain characters to appear at all, doesn't allow certain characters to appear at certain locations in the path, and treats certain filenames as special devices. Further complicating this scenario, many Win32 API functions accept shell paths.

The CXFilePath abstract-to-native mappings resolve this as follows:

If the filepath is longer than 230 characters, and represents a windows network path (ie. is prefixed with "//"), it is converted to a UNC path by stripping the two leading slashes and then prefixing "\\?\UNC\".
If the filepath is longer than 230 characters, and is an absolute path, it is converted to a UNC path by prefixing "\\?\UNC\"
Otherwise, the filepath is used as-is.

All forward slash character ("/") are converted to backslash characters ("\").

TBD: Absolute vs relative paths.

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.

A leading slash indicates an absolute path, otherwise the path is considered relative. The slash character ("/") is the root element of any absolute filepath; other volumes are mounted as folders within the root filesystem.

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;

Path Operations

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

// Byte-for-byte string equality test.
bool operator==(const CXFilePath& path) const;
bool operator==(const CXString& str) const;
bool operator==(const char* __nonnull str) const;

// Byte-for-byte string inequality test.
bool operator!=(const CXFilePath& path) const;
bool operator!=(const CXString& str) const;
bool operator!=(const char* __nonnull str) const;

// Sort operator.
bool operator<(const QUAL& other) const;

Helper Methods

// Convert the entire filepath to lowercase; useful for filename 
// matching on case-insensitive filesystems.
void ToLower(void);

// Given a proposed filename (NOT a filepath), this function 
// returns a filename which is considered valid and safe on the
// local platform. The returned filename is not guaranteed unique.
static CXString GetSafeFilename(const char* __nonnull filename);

// Given an absolute filepath as the first parameter, this returns
// the filepath verbatim. Given a relative filepath as the first
// parameter, the return value is a path concatenation of the
// second parameter and the first parameter.
static CXFilePath ResolvePathRelativeTo(const CXFilePath& relativeOrAbsolutePath, const CXFilePath& basePathForRelative);

// If the second parameter is a path prefix of the first parameter,
// the prefix is stripped and the remaining relative path is 
// returned. Otherwise, an empty filepath is returned.
static CXFilePath GetPathRelativeTo(const CXFilePath& absolutePath, CXFilePath basePathForRelative);

// This function returns whether the second parameter is a path
// prefix of the first parameter.
static bool IsPathRelativeTo(const CXFilePath& absolutePath, const CXFilePath& basePathForRelative);

// Returns a "file://" URI representing the same file as this object.
CXString AsFileURIString(void) const;

Streamers

// Writes this object's filepath to the specified binary stream.
template <CX_STREAMER_TMPL_DECL> CX_STREAMER_QUAL& operator << (CX_STREAMER_QUAL& stream, const CXFilePath& src);

// Reads a filepath from the specified binary stream and assigns
// it to this object.
template <CX_STREAMER_TMPL_DECL> CX_STREAMER_QUAL& operator >> (CX_STREAMER_QUAL& stream, CXFilePath& dst);

Stringification

// Converts the specified filepath to a string.
void CXStringify(CXString& o_result, const CXFilePath& value);

CXFilePath

Contents