# Path structures

These functions are declared in the main Allegro header file:

~~~~c
 #include <allegro5/allegro.h>
~~~~

We define a path as an optional *drive*, followed by zero or more *directory
components*, followed by an optional *filename*.  The filename may be broken
up into a *basename* and an *extension*, where the basename includes the start
of the filename up to, but not including, the last dot (.) character.
If no dot character exists the basename is the whole filename.
The extension is everything from the last dot character to the end of the
filename.

## API: al_create_path

Create a path structure from a string.  The last component, if it is followed
by a directory separator and is neither "." nor "..", is treated as the last
directory name in the path.  Otherwise the last component is treated as the
filename.
The string may be NULL for an empty path.

See also: [al_create_path], [al_destroy_path]

## API: al_create_path_for_directory

This is the same as [al_create_path], but interprets the passed string
as a directory path. The filename component of the returned path will
always be empty.

See also: [al_create_path], [al_destroy_path]

## API: al_destroy_path

Free a path structure.
Does nothing if passed NULL.

See also: [al_create_path], [al_create_path_for_directory]

## API: al_clone_path

Clones an ALLEGRO_PATH structure.
Returns NULL on failure.

See also: [al_destroy_path]

## API: al_join_paths

Concatenate two path structures. The first path structure is
modified.  If 'tail' is an absolute path, this function does nothing.

If 'tail' is a relative path, all of its directory components will be
appended to 'path'.  tail's filename will also overwrite path's filename,
even if it is just the empty string.

Tail's drive is ignored.

Returns true if 'tail' was a relative path and so concatenated to 'path',
otherwise returns false.

See also: [al_rebase_path]

## API: al_rebase_path

Concatenate two path structures, modifying the second path structure.
If *tail* is an absolute path, this function does nothing.
Otherwise, the drive and path components in *head* are inserted
at the start of *tail*.

For example, if *head* is "/anchor/" and *tail* is "data/file.ext", then
after the call *tail* becomes "/anchor/data/file.ext".

See also: [al_join_paths]

## API: al_get_path_drive

Return the drive letter on a path, or the empty string if there is none.

The "drive letter" is only used on Windows, and is usually a string like
"c:", but may be something like "\\\\Computer Name" in the case of UNC
(Uniform Naming Convention) syntax.

## API: al_get_path_num_components

Return the number of directory components in a path.

The directory components do not include the final part of a path
(the filename).

See also: [al_get_path_component]

## API: al_get_path_component

Return the i'th directory component of a path, counting from zero.
If the index is negative then count from the right, i.e. -1 refers to
the last path component.
It is an error to pass an index which is out of bounds.

See also: [al_get_path_num_components], [al_get_path_tail]

## API: al_get_path_tail

Returns the last directory component, or NULL if there are no directory
components.

## API: al_get_path_filename

Return the filename part of the path, or the empty string if there is none.

The returned pointer is valid only until the filename part of the path
is modified in any way, or until the path is destroyed.

See also: [al_get_path_basename], [al_get_path_extension],
[al_get_path_component]

## API: al_get_path_basename

Return the basename, i.e. filename with the extension removed.
If the filename doesn't have an extension, the whole filename is the basename.
If there is no filename part then the empty string is returned.

The returned pointer is valid only until the filename part of the path
is modified in any way, or until the path is destroyed.

See also: [al_get_path_filename], [al_get_path_extension]

## API: al_get_path_extension

Return a pointer to the start of the extension of the filename,
i.e. everything from the final dot ('.') character onwards.
If no dot exists, returns an empty string.

The returned pointer is valid only until the filename part of the path
is modified in any way, or until the path is destroyed.

See also: [al_get_path_filename], [al_get_path_basename]

## API: al_set_path_drive

Set the drive string on a path.
The drive may be NULL, which is equivalent to setting the drive
string to the empty string.

See also: [al_get_path_drive]

## API: al_append_path_component

Append a directory component.

See also: [al_insert_path_component]

## API: al_insert_path_component

Insert a directory component at index i.
If the index is negative then count from the right, i.e. -1 refers to
the last path component.

It is an error to pass an index i which is not within these bounds:
0 <= i <= al_get_path_num_components(path).

See also: [al_append_path_component], [al_replace_path_component],
[al_remove_path_component]

## API: al_replace_path_component

Replace the i'th directory component by another string.
If the index is negative then count from the right, i.e. -1 refers to
the last path component.
It is an error to pass an index which is out of bounds.

See also: [al_insert_path_component], [al_remove_path_component]

## API: al_remove_path_component

Delete the i'th directory component.
If the index is negative then count from the right, i.e. -1 refers to
the last path component.
It is an error to pass an index which is out of bounds.

See also: [al_insert_path_component], [al_replace_path_component],
[al_drop_path_tail]

## API: al_drop_path_tail

Remove the last directory component, if any.

See also: [al_remove_path_component]

## API: al_set_path_filename

Set the optional filename part of the path.
The filename may be NULL, which is equivalent to setting the
filename to the empty string.

See also: [al_set_path_extension], [al_get_path_filename]

## API: al_set_path_extension

Replaces the extension of the path with the given one, i.e. replaces
everything from the final dot ('.') character onwards, including the dot.
If the filename of the path has no extension, the given one is appended.
Usually the new extension you supply should include a leading dot.

Returns false if the path contains no filename part,
i.e. the filename part is the empty string.

See also: [al_set_path_filename], [al_get_path_extension]

## API: al_path_cstr

Convert a path to its string representation, i.e. optional drive,
followed by directory components separated by 'delim',
followed by an optional filename.

To use the current native path separator, use ALLEGRO_NATIVE_PATH_SEP
for 'delim'.

The returned pointer is valid only until the path is modified in any way,
or until the path is destroyed.

## API: al_make_path_canonical

Removes any leading '..' directory components in absolute paths.
Removes all '.' directory components.

Note that this does *not* collapse "x/../y" sections into "y".
This is by design. If "/foo" on your system is a symlink to "/bar/baz",
then "/foo/../quux" is actually "/bar/quux",
not "/quux" as a naive removal of ".." components would give you.

