2.10 Path

The Path class is a string with special OS dependent path related functionalities. Unix/Linux systems use a ’/’ as path separator, and Microsoft systems use a ’\’. Path handles either notation transparently and provides the system with the accurate separator. Thus you can develop code under your preferred platform, and reuse it without having to care about which separator should be used. LYRIC takes care of using the right one in system calls.

Path like String is dynamically reallocated at run time. A creation, concatenation, appending, or expanding automatically handles memory resources by allocating and releasing memory chunks.

Synopsis

Description

˜Path ()

Destroys this path, releasing all memory resources.

Path ()

Constructs this as an empty path.

Path (const char* ascii)

Constructs this path from the given ascii C string. The ascii argument must be a valid null terminated ASCII encoded C string.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the path.

Path (const wchar_t* wascii)

Constructs this path from the given wascii C string. The wascii argument must be a valid null terminated wide ASCII encoded C string.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the path.

Path (const String& path)

Constructs this path from the given path LYRIC string.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the path.

Path (const Path& path)

Constructs this path from the given path. All properties and content of path are cloned into this path.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the path.

Path& operator = (const Path& path)

Assigns this path from path, and return a reference to this for assignment operation chaining. All properties and content of path are cloned into this path.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the path.

Path& operator = (const char* ascii)

Assigns this path from an ascii null terminated C string , and return a reference to this for assignment operation chaining.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the path.

Path& operator += (const Path& path)

Concatenates this path with path, and return a reference to this for assignment operation chaining.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the concatenated path.

Size length () const

Returns the length of this path. The length is given in number of symbols, not bytes.

void create (const char* ascii, Size leng)

Creates this path from an ascii C byte bucket which is not null terminated. The leng argument tells how many bytes are copied from ascii into this.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the path.

void append (const String::Symbol ch)

Appends one symbol given by ch at the end of this path.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the new path.

void append (const Path& path)

Appends path to the end of this path.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the new path.

void insert (Size index, const Path& path)

Inserts the given sub-path into this path, starting at position index.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the new path.

void expand ()

Expands this path. This method uses symbols given in this this and resolves them to form a system usable path. The path expander recognizes 3 types of symbols. Table 2.1 lists the symbol types and their meaning.

---

Symbol Meaning ˜ User’s home directory ${VARIABLE} An environment variable %VARIABLE% An environment variable Table 2.1: Path symbols and their meaning

---

Except for the ˜, all symbols are environment variables with either Unix shell like or Windows like variable notation. Each environment variable is resolved using getenv, without the separators (${...} or %...%). Unresolvable variables expand to the empty string. On Unix/Linux, “˜” expands using getenv("HOME"), and on Windows “˜” expands by concatenating the results of getenv("HOMEDRIVE") and getenv("HOMEPATH").

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the new path.

void abs ()

Renders this path absolute. The current working directory of the running process is taken as reference to make this path absolute.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the new path.

String base (const String& suffix = "") const

Returns the file-name part of this path. The returned result is the file-name stored in this path without the directory part. The optional suffix allows to specify a suffix to be removed at the end of the file-name.

Unix users will recognize the basename command-line tool.

It is assumed that a path has a structure like directory/namesuffix. Note that there is no dot or other separator between name and suffix. This eventual separator must be given as part of the suffix. This function can selectively remove the directory, and optionally also the suffix part of this path, in a resulting path it returns. On windows the drive letter is considered as being part of the directory.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the returned string.

String dir () const

Returns the directory part of this path. The returned result is the directory stored in this path without the file-name part.

Under windows the drive name is considered as being part of the directory part of the path.

Exception::Memory::Alloc

is thrown if there was not enough free memory to store the returned string.

Path::Property prop () const
Path::Property property () const

Returns this path’s property. Currently the property can be absolute or relative, depending if this path is an absolute or a relative path. See section 2.10.1 for further details on the Path::Property class.