GLib.PathBuf¶

Fields¶

Name	Type	Access	Description
dummy	[`object`]	r

Methods¶

class	`equal` (v1, v2)
	`clear` ()
	`clear_to_path` ()
	`free` ()
	`free_to_path` ()
	`init` ()
	`init_from_path` (path)
	`pop` ()
	`push` (path)
	`set_extension` (extension)
	`set_filename` (file_name)
	`to_path` ()

Details¶

class GLib.PathBuf¶

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

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:

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.

New in version 2.76.

classmethod equal(v1, v2)[source]¶

Parameters:

v1 (object) – a path buffer to compare
v2 (object) – a path buffer to compare

Returns:

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

Return type:

bool

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.

New in version 2.76.

clear()[source]¶

Clears the contents of the path buffer.

This function should be use to free the resources in a stack-allocated GPathBuf initialized using GLib.PathBuf.init() or GLib.PathBuf.init_from_path().

New in version 2.76.

clear_to_path()[source]¶

Returns:: the built path
Return type:: str or None

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

This function returns NULL if the GPathBuf is empty.

See also: GLib.PathBuf.to_path()

New in version 2.76.

init()[source]¶

Returns:: the initialized path builder
Return type:: GLib.PathBuf

Initializes a GPathBuf instance.

New in version 2.76.

init_from_path(path)[source]¶

Parameters:: path (str or None) – a file system path
Returns:: the initialized path builder
Return type:: GLib.PathBuf

Initializes a GPathBuf instance with the given path.

New in version 2.76.

pop()[source]¶

Returns:: TRUE if the buffer was modified and FALSE otherwise
Return type:: bool

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.

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);

New in version 2.76.

push(path)[source]¶

Parameters:: path (str) – a path
Returns:: the same pointer to self, for convenience
Return type:: GLib.PathBuf

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, GLib.DIR_SEPARATOR_S is the only directory separator.

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);

New in version 2.76.

set_extension(extension)[source]¶

Parameters:: extension (str or None) – the file extension
Returns:: TRUE if the extension was replaced, and FALSE otherwise
Return type:: bool

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.

New in version 2.76.

set_filename(file_name)[source]¶

Parameters:: file_name (str) – the file name in the path
Returns:: TRUE if the file name was replaced, and FALSE otherwise
Return type:: bool

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.

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);

New in version 2.76.

to_path()[source]¶

Returns:: the path
Return type:: str or None

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.

New in version 2.76.