gi_path.h File Reference

Platform-independent path construction and formatting. More...

Go to the source code of this file.

Classes
struct	gi_path
Defines
#define	GI_PATH_SEPARATOR_WIN32   '\\'
#define	GI_PATH_SEPARATOR_UNIX   '/'
#define	GI_PATH_SEPARATOR   GI_PATH_SEPARATOR_UNIX
#define	gi_path_native(gipath)   gi_path_fmt (gipath, GI_PATH_NATIVE)
#define	gi_path_std(gipath)   gi_path_fmt (gipath, GI_PATH_STD)
Typedefs
typedef gi_path	GiPath
Enumerations
enum	gi_path_style { GI_PATH_UNIX, GI_PATH_WIN32, GI_PATH_NATIVE = GI_PATH_UNIX, GI_PATH_STD = GI_PATH_UNIX }
Functions
EXTERN_C_BEGIN LIBGIFT_EXPORT GiPath *	gi_path_new (enum gi_path_style style, const char *path)
LIBGIFT_EXPORT GiPath *	gi_path_newn (enum gi_path_style style, const char *path, size_t len)
LIBGIFT_EXPORT void	gi_path_free (GiPath *gipath)
LIBGIFT_EXPORT GiPath *	gi_path_dup (GiPath *source)
LIBGIFT_EXPORT char *	gi_path_set (GiPath *gipath, enum gi_path_style style, const char *path)
LIBGIFT_EXPORT char *	gi_path_setn (GiPath *gipath, enum gi_path_style style, const char *path, size_t len)
LIBGIFT_EXPORT char *	gi_path_expand (GiPath *gipath)
LIBGIFT_EXPORT GiPath *	gi_path_dirname (GiPath *gipath)
LIBGIFT_EXPORT char *	gi_path_basename (GiPath *gipath)
LIBGIFT_EXPORT char *	gi_path_extname (GiPath *gipath)
LIBGIFT_EXPORT int	gi_path_append (GiPath *gipath, const char *delem)
LIBGIFT_EXPORT int	gi_path_appendn (GiPath *gipath, const char *delem, size_t len)
LIBGIFT_EXPORT char *	gi_path_fmt (GiPath *gipath, enum gi_path_style style)
LIBGIFT_EXPORT char *	gi_path_native_s (GiPath *gipath)
LIBGIFT_EXPORT size_t	gi_path_fmtlen (GiPath *gipath, enum gi_path_style style)
LIBGIFT_EXPORT size_t	gi_path_len (GiPath *gipath)
LIBGIFT_EXPORT bool	gi_path_eq (GiPath *a, GiPath *b)
LIBGIFT_EXPORT int	gi_path_cmp (GiPath *a, GiPath *b)
LIBGIFT_EXPORT int	gi_path_cmpn (GiPath *a, GiPath *b, size_t n)
LIBGIFT_EXPORT bool	gi_path_leads_with (GiPath *path, GiPath *lead)
LIBGIFT_EXPORT bool	gi_path_absolute (GiPath *gipath)

---

Detailed Description

Platform-independent path construction and formatting.

These routines provide an abstraction for platform-specific path specifiers and allows for transport of those paths in a single libgift-wide standard.

---

Typedef Documentation

typedef struct gi_path GiPath

Simple path object which acts as a platform-independent path specifier. This object always manages it's own internal string buffer.

---

Enumeration Type Documentation

enum gi_path_style

Describes what style the internally managed buffer refers to. Enumeration values: GI_PATH_UNIX  UNIX paths are a bit of a misnomer as what we really mean is POSIX semantics. The following rules apply: * The only invalid character in a single named element is '/'. * Empty elements will be automatically removed. For exaple, "/foo//bar" would appear as "/foo/bar". * Trailing slashes will be stripped. GI_PATH_WIN32  We support the following two otherwise independent types of Windows path specifiers: [drive]:\[path] Drive-letter \[machine]\[path] URN We currently make the assumption that drive letter specifiers may only be 1 character wide, and must be in the set [a-zA-Z]. This is probably untrue, but I don't feel like looking it up right now. GI_PATH_NATIVE  Special value which describes which of the aforementioned path forms will be used for the current host's native path. GI_PATH_STD  Standard path style used by libgift.

---

Function Documentation

LIBGIFT_EXPORT bool gi_path_absolute (  GiPath *  gipath  )

Tests if a path is absolute or relative. If the path is initialized to NULL, the path will be claimed to be relative. Returns: If the path is found to be absolute, true is returned; otherwise, the path is relative, and false is returned.

LIBGIFT_EXPORT int gi_path_append (  GiPath *  gipath, const char *  delem )

Add a new directory element to the end of the path. The directory element will be appended according to the rules of the current path style. Note: If the underlying path is currently zero-width, the directory element will be added such that the path string becomes relative; the only way to produce an absolute path string with this API is to first initialize the path as "/". Parameters: gipath  delem  Directory element to be added. May not contain any path separators, as determined by the underlying path style. Returns: On success, the number of bytes copied from `delem' is returned. Otherwise, -1 is returned, and no characters were copied.

LIBGIFT_EXPORT int gi_path_appendn (  GiPath *  gipath, const char *  delem, size_t  len )

Extended interface to gi_path_append wihch allows you to explicitly set the length of `delem'. No more than `len' bytes will be copied from the source.

LIBGIFT_EXPORT char* gi_path_basename (  GiPath *  gipath  )

Access the "base" name of the path object. That is, the very last directory element, which usually represents a filename. Returns: On success, a pointer directly into the path object is returned. This memory is guaranteed to point to the basename portion only so long as no other library call operates on the GiPath object. Otherwise, NULL is returned.

LIBGIFT_EXPORT int gi_path_cmp (  GiPath *  a, GiPath *  b )

Compare two paths borrowing from the current platform's semantics where applicable.

LIBGIFT_EXPORT int gi_path_cmpn (  GiPath *  a, GiPath *  b, size_t  n )

Compare two paths borrowing from the current platform's semantics where applicable. No more than `n' characters will be compared from either `a' or `b'.

LIBGIFT_EXPORT GiPath* gi_path_dirname (  GiPath *  gipath  )

Access the directory portion of a path object. For example, given a path object that describes "/foo/bar/baz", a new path object would be returned describing "/foo/bar". No trailing '/' will be found in the result unless that is the only directory component that exists. Returns: On success, a newly allocated path object describing the directory name is produced. If there was no directory portion of the input path object, or the object could not be allocated, NULL is returned.

LIBGIFT_EXPORT GiPath* gi_path_dup (  GiPath *  source  )

Produce a deep copy of `source'. This call is similar to gi_path_new (source->style, gi_path_fmt (source, source->style)).

LIBGIFT_EXPORT bool gi_path_eq (  GiPath *  a, GiPath *  b )

Functionally equivalent to gi_path_cmp, but with the possibility to micro-optimize by first evaluating the length of the underlying path.

LIBGIFT_EXPORT char* gi_path_expand (  GiPath *  gipath  )

Expand the underlying path string using shell-like expansion rules. Currently this only understands what to do with "~", which it expands to $HOME when it appears at the beginning of the path. It does not support the extended usage "~user".

LIBGIFT_EXPORT char* gi_path_extname (  GiPath *  gipath  )

Access the extension of the base filename. The extension is defined as any characters following the last '.' character which occurs in the basename. Returns: On success, a pointer to the extension. See gi_path_basename for usage warnings.

LIBGIFT_EXPORT char* gi_path_fmt (  GiPath *  gipath, enum gi_path_style  style )

Format the internal buffer to the specified style and return the conversion as a pointer to internally managed memory.

LIBGIFT_EXPORT size_t gi_path_fmtlen (  GiPath *  gipath, enum gi_path_style  style )

Simple convenience for calling gi_path_fmt, and then returning the result of gi_path_len.

LIBGIFT_EXPORT void gi_path_free (  GiPath *  gipath  )

Destroy the gipath object as well as the internally managed copy of the path element.

LIBGIFT_EXPORT bool gi_path_leads_with (  GiPath *  path, GiPath *  lead )

Tests if the supplied path has leading components of the path supplied by `lead'. This is essentially a sugary wrapper for gi_path_cmpn.

LIBGIFT_EXPORT size_t gi_path_len (  GiPath *  gipath  )

Access the length of the current path string.

LIBGIFT_EXPORT char* gi_path_native_s (  GiPath *  gipath  )

Similar to the ::gi_path_native macro except that this function will never allow NULL to be returned. This may be useful for lazily printing the underlying path without first checking or asserting that it is non-NULL. Returns: If `gipath' is NULL, or the underlying path is unspecified, the string literal "(nil)" will be returned. Otherwise, the path formatted according to GI_PATH_NATIVE will be returned.

EXTERN_C_BEGIN LIBGIFT_EXPORT GiPath* gi_path_new (  enum gi_path_style  style, const char *  path )

Construct a new path object from the specified string path. No conversion will be immediately applied, however an allocated copy of `path' will be made for internal management. Parameters: style  Format of `path'. Please use either GI_PATH_HOST or GI_PATH_STD. If specified as GI_PATH_HOST, we will use compile-time information to determine what style that really is. path  Path to copy into the newly created object. You may further operate on this path once encapsulated within the object without disturbing the storage provided by this argument. May be NULL.

LIBGIFT_EXPORT GiPath* gi_path_newn (  enum gi_path_style  style, const char *  path, size_t  len )

Extended interface to gi_path_new which allows you to explicitly set the length of `path'. No more than `len' bytes will be copied from the source.

LIBGIFT_EXPORT char* gi_path_set (  GiPath *  gipath, enum gi_path_style  style, const char *  path )

Assign or re-assign a path object with an initial path. If a path was previously set, the original memory segment will be reused for efficiency. Note: This function is called from gi_path_new to initialize the path object. Returns: Pointer to the internal path buffer. This is the same result as a subsequent call to gi_path_fmt with the same `style' parameter.

LIBGIFT_EXPORT char* gi_path_setn (  GiPath *  gipath, enum gi_path_style  style, const char *  path, size_t  len )

Extended interface to gi_path_set wihch allows you to explicitly set the length of `path'. No more than `len' bytes will be copied from the source.

---