tsc_Path

The tsc_Path class provides a number of static functions for dealing with file paths.  Unless noted otherwise, methods behave identically to the .NET Path class members of the same name.  

Path works correctly for both Windows and Linux/Android filesystems and will transparently translate between the two formats. That does not mean it will adjust the path itself - "C:\Program Files" will always fail miserably on Android.

There are some terms that have quite precise meanings that are used in this explanation:

• Directory (or folder) - The name of a directory or directories without any file name at the end.

• Filename - the name of a file, including the extension, and excluding any directory information.

• Path - the full path to a file, including directories and the file name.

• Separator - the character used between directory names and preceding the file name.

• Extension - a short name following the filename and separated from it by a period (dot, or '.').  Often used to indicate the type of data in the file.

• Absolute path - a file path that begins with a separator, and fully defines the location of a file.

• Relative path - a file path that does not begin with a separator, and must be appended to an absolute directory before use.

Public constants

static const char DirectorySeparatorChar;      // Windows: Left slash (\), Android: Right slash (/)
static const char AltDirectorySeparatorChar;   // Right slash (/)
static const char VolumeSeparatorChar;         // Windows: Colon (:), Android: n/a

Public methods

static bool Equals (const tsc_String& path1, const tsc_String& path2);
This function compares two paths. It is separator insensitive, and case insensitive for Windows.  This is a string compare with no reference to the filesystem, therefore do not mix absolute and relative paths.

static bool ExtensionsEqual (const tsc_String& path1, const tsc_String& path2);
Compares the extensions on two paths. The compare is case insensitive on Windows.

static tsc_String Combine (const tsc_String& path1, const tsc_String& path2);
Combines two paths, adding a directory separator if necessary. If path2 is absolute, path1 is ignored.

static tsc_String ChangeExtension (const tsc_String& path, const tsc_String& newExt);
Replaces the extension in the path. newExt may optionally start with a period (.).
If newExt is an empty string, the file extension is removed (which varies from .NET behaviour).

static tsc_String GetDirectoryName (const tsc_String& path);
Removes the last element (typically the file name and extension) and the directory separator from the path and returns the remainder.

static tsc_String GetExtension (const tsc_String& path);
Returns the extension, including the period character.  Returns an empty string if path has no period following the last directory separator character.

static tsc_String GetFileName (const tsc_String& path);
Removes all directory information and returns the filename and extension.  The last element is assumed to be the filename even if it is in fact a directory.

static bool IsPathRooted (const tsc_String& path);
Returns true if the path is absolute (ie, starts with a directory separator). On Windows, any initial drive letter (eg c:) is skipped.

static tsc_String MakeRelativeTo (const tsc_String& path, const tsc_String& root);
Removes the root part from the path if and only if path starts with the same directory string.

static tsc_String  GetFileNameWithoutExtension (const tsc_String& path);
Returns the file name with the directory path and the extension removed.

Path macros for Standard folder names

In addition to the above, the Path class supports macro expansion to help with the construction of Survey Core standard paths.

Path macros take the form $(name).  The Path::Compose() methods will replace all such names with their current values.  Macros do not contain leading or trailing directory separators, except that a leading slash denotes the start of an absolute directory name possibly preceded by a drive letter.

For clarity, the names of macros that refer to absolute paths such as $(ProjectRootDir) end in "Dir", whereas the names of macros that refer to portions of paths, such as $(Language) or $(Project) do not end with "Dir".

The Compose functions are safe to call multiple times on any path whether it contains macros or not.  A path containing no macros will remain unchanged.  The multiple-parameter overloads of Compose() concatenate the parts in a manner similar to Combine().

If specifying multiple directory parts in a single parameter, then those parts must be separated by a directory separator character.  Empty subpaths (ie, two slashes together) will be reduced to a single slash.  For example:

Path::Compose ("$(ProjectRootDir)\\$(Project)\\$(Export)\\myreport.txt");

or (better):

Path::Compose ("$(ProjectRootDir)\\$(Project)\\$(Export)", "myreport", "txt");

static tsc_String  Compose  (const tsc_String& path);
static tsc_String  Compose  (const tsc_String& directory, const tsc_String& filename);
static tsc_String  Compose  (const tsc_String& directory, const tsc_String& filename, const tsc_String& extension);

The extension parameter may be provided either with a leading period (.) or without.

Path macros available

The following macros are supported :