GPathBuf: GLib Reference Manual

## GPathBuf GPathBuf — A mutable path builder |

## Functions

GPathBuf * | g_path_buf_new ()
GPathBuf * | g_path_buf_new_from_path ()
GPathBuf * | g_path_buf_init ()
GPathBuf * | g_path_buf_init_from_path ()
void | g_path_buf_clear ()
char * | g_path_buf_clear_to_path ()
void | g_path_buf_free ()
char * | g_path_buf_free_to_path ()
GPathBuf * | g_path_buf_push ()
gboolean | g_path_buf_pop ()
gboolean | g_path_buf_set_filename ()
gboolean | g_path_buf_set_extension ()
char * | g_path_buf_to_path ()
GPathBuf * | g_path_buf_copy ()
gboolean | g_path_buf_equal ()

## Types and Values

struct | GPathBuf
#define | G_PATH_BUF_INIT

## Includes

    #include <glib.h>
    #include <glib/gi18n.h>

## Description

`GPathBuf` is a helper type that allows you to easily build paths from individual elements, using the platform specific conventions for path separators.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    g_auto (GPathBuf) path;

    g_path_buf_init (&path);

    g_path_buf_push (&path, "usr");
    g_path_buf_push (&path, "bin");
    g_path_buf_push (&path, "echo");

    g_autofree char *echo = g_path_buf_to_path (&path);
    g_assert_cmpstr (echo, ==, "/usr/bin/echo");

You can also load a full path and then operate on its components:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    g_auto (GPathBuf) path;

    g_path_buf_init_from_path (&path, "/usr/bin/echo");

    g_path_buf_pop (&path);
    g_path_buf_push (&path, "sh");

    g_autofree char *sh = g_path_buf_to_path (&path);
    g_assert_cmpstr (sh, ==, "/usr/bin/sh");

`GPathBuf` is available since GLib 2.76.

## Functions

### g_path_buf_new ()

    GPathBuf *
    g_path_buf_new (void);

Allocates a new `GPathBuf`.

#### Returns

the newly allocated path buffer.

[transfer full]

Since: 2.76

### g_path_buf_new_from_path ()

    GPathBuf *
    g_path_buf_new_from_path (const char *path);

Allocates a new `GPathBuf` with the given `path` .

#### Parameters

path | the path used to initialize the buffer. | [type filename][nullable]

#### Returns

the newly allocated path buffer.

[transfer full]

Since: 2.76

### g_path_buf_init ()

    GPathBuf *
    g_path_buf_init (GPathBuf *buf);

Initializes a `GPathBuf` instance.

#### Parameters

buf | a path buffer |

#### Returns

the initialized path builder.

[transfer none]

Since: 2.76

### g_path_buf_init_from_path ()

    GPathBuf *
    g_path_buf_init_from_path (GPathBuf *buf,
                               const char *path);

Initializes a `GPathBuf` instance with the given path.

#### Parameters

buf | a path buffer |
path | a file system path. | [type filename][nullable]

#### Returns

the initialized path builder.

[transfer none]

Since: 2.76

### g_path_buf_clear ()

    void
    g_path_buf_clear (GPathBuf *buf);

Clears the contents of the path buffer.

This function should be use to free the resources in a stack-allocated `GPathBuf` initialized using `g_path_buf_init()` or `g_path_buf_init_from_path()`.

#### Parameters

buf | a path buffer |

Since: 2.76

### g_path_buf_clear_to_path ()

    char *
    g_path_buf_clear_to_path (GPathBuf *buf);

Clears the contents of the path buffer and returns the built path.

This function returns `NULL` if the `GPathBuf` is empty.

See also: `g_path_buf_to_path()`

#### Parameters

buf | a path buffer |

#### Returns

the built path.

[transfer full][nullable][type filename]

Since: 2.76

### g_path_buf_free ()

    void
    g_path_buf_free (GPathBuf *buf);

Frees a `GPathBuf` allocated by `g_path_buf_new()`.

#### Parameters

buf | a path buffer. | [transfer full][not nullable]

Since: 2.76

### g_path_buf_free_to_path ()

    char *
    g_path_buf_free_to_path (GPathBuf *buf);

Frees a `GPathBuf` allocated by `g_path_buf_new()`, and returns the path inside the buffer.

This function returns `NULL` if the `GPathBuf` is empty.

See also: `g_path_buf_to_path()`

#### Parameters

buf | a path buffer. | [transfer full][not nullable]

#### Returns

the path.

[transfer full][nullable][type filename]

Since: 2.76

### g_path_buf_push ()

    GPathBuf *
    g_path_buf_push (GPathBuf *buf,
                     const char *path);

Extends the given path buffer with `path` .

If `path` is absolute, it replaces the current path.

If `path` contains a directory separator, the buffer is extended by as many elements the path provides.

On Windows, both forward slashes and backslashes are treated as directory separators. On other platforms, `G_DIR_SEPARATOR_S` is the only directory separator.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    GPathBuf buf, cmp;

    g_path_buf_init_from_path (&buf, "/tmp");
    g_path_buf_push (&buf, ".X11-unix/X0");
    g_path_buf_init_from_path (&cmp, "/tmp/.X11-unix/X0");
    g_assert_true (g_path_buf_equal (&buf, &cmp));
    g_path_buf_clear (&cmp);

    g_path_buf_push (&buf, "/etc/locale.conf");
    g_path_buf_init_from_path (&cmp, "/etc/locale.conf");
    g_assert_true (g_path_buf_equal (&buf, &cmp));
    g_path_buf_clear (&cmp);

    g_path_buf_clear (&buf);

#### Parameters

buf | a path buffer |
path | a path. | [type filename]

#### Returns

the same pointer to `buf` , for convenience.

[transfer none]

Since: 2.76

### g_path_buf_pop ()

    gboolean
    g_path_buf_pop (GPathBuf *buf);

Removes the last element of the path buffer.

If there is only one element in the path buffer (for example, `/` on Unix-like operating systems or the drive on Windows systems), it will not be removed and `FALSE` will be returned instead.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    GPathBuf buf, cmp;

    g_path_buf_init_from_path (&buf, "/bin/sh");

    g_path_buf_pop (&buf);
    g_path_buf_init_from_path (&cmp, "/bin");
    g_assert_true (g_path_buf_equal (&buf, &cmp));
    g_path_buf_clear (&cmp);

    g_path_buf_pop (&buf);
    g_path_buf_init_from_path (&cmp, "/");
    g_assert_true (g_path_buf_equal (&buf, &cmp));
    g_path_buf_clear (&cmp);

    g_path_buf_clear (&buf);

#### Parameters

buf | a path buffer |

#### Returns

`TRUE` if the buffer was modified and `FALSE` otherwise

Since: 2.76

### g_path_buf_set_filename ()

    gboolean
    g_path_buf_set_filename (GPathBuf *buf,
                             const char *file_name);

Sets the file name of the path.

If the path buffer is empty, the filename is left unset and this function returns `FALSE`.

If the path buffer only contains the root element (on Unix-like operating systems) or the drive (on Windows), this is the equivalent of pushing the new `file_name` .

If the path buffer contains a path, this is the equivalent of popping the path buffer and pushing `file_name` , creating a sibling of the original path.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    GPathBuf buf, cmp;

    g_path_buf_init_from_path (&buf, "/");

    g_path_buf_set_filename (&buf, "bar");
    g_path_buf_init_from_path (&cmp, "/bar");
    g_assert_true (g_path_buf_equal (&buf, &cmp));
    g_path_buf_clear (&cmp);

    g_path_buf_set_filename (&buf, "baz.txt");
    g_path_buf_init_from_path (&cmp, "/baz.txt");
    g_assert_true (g_path_buf_equal (&buf, &cmp);
    g_path_buf_clear (&cmp);

    g_path_buf_clear (&buf);

#### Parameters

buf | a path buffer |
file_name | the file name in the path. | [type filename][not nullable]

#### Returns

`TRUE` if the file name was replaced, and `FALSE` otherwise

Since: 2.76

### g_path_buf_set_extension ()

    gboolean
    g_path_buf_set_extension (GPathBuf *buf,
                              const char *extension);

Adds an extension to the file name in the path buffer.

If `extension` is `NULL`, the extension will be unset.

If the path buffer does not have a file name set, this function returns `FALSE` and leaves the path buffer unmodified.

#### Parameters

buf | a path buffer |
extension | the file extension. | [type filename][nullable]

#### Returns

`TRUE` if the extension was replaced, and `FALSE` otherwise

Since: 2.76

### g_path_buf_to_path ()

    char *
    g_path_buf_to_path (GPathBuf *buf);

Retrieves the built path from the path buffer.

On Windows, the result contains backslashes as directory separators, even if forward slashes were used in input.

If the path buffer is empty, this function returns `NULL`.

#### Parameters

buf | a path buffer |

#### Returns

the path.

[transfer full][type filename][nullable]

Since: 2.76

### g_path_buf_copy ()

    GPathBuf *
    g_path_buf_copy (GPathBuf *buf);

Copies the contents of a path buffer into a new `GPathBuf`.

#### Parameters

buf | a path buffer. | [not nullable]

#### Returns

the newly allocated path buffer.

[transfer full]

Since: 2.76

### g_path_buf_equal ()

    gboolean
    g_path_buf_equal (gconstpointer v1,
                      gconstpointer v2);

Compares two path buffers for equality and returns `TRUE` if they are equal.

The path inside the paths buffers are not going to be normalized, so `X/Y/Z/A/..`, `X/./Y/Z` and `X/Y/Z` are not going to be considered equal.

This function can be passed to `g_hash_table_new()` as the `key_equal_func` parameter.

#### Parameters

v1 | a path buffer to compare. | [not nullable]
v2 | a path buffer to compare. | [not nullable]

#### Returns

`TRUE` if the two path buffers are equal, and `FALSE` otherwise

Since: 2.76

## Types and Values

### struct GPathBuf

    struct GPathBuf {
    };

A mutable path builder.

Since: 2.76

### G_PATH_BUF_INIT

    #define             G_PATH_BUF_INIT

Initializes a GPathBuf on the stack.

A stack-allocated `GPathBuf` must be initialized if it is used together with `g_auto()` to avoid warnings and crashes if the function returns before calling `g_path_buf_init()`.

    1
    g_auto (GPathBuf) buf = G_PATH_BUF_INIT;

Since: 2.76