gi-glib-2.0.30: GLib bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | Safe-Inferred
Language | Haskell2010

GI.GLib.Structs.PathBuf

Contents

- Exported types
- Methods
  - clear
  - clearToPath
  - equal
  - free
  - freeToPath
  - init
  - initFromPath
  - pop
  - push
  - setExtension
  - setFilename
  - toPath

Description

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

### c code

    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:

### c code

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

Since: 2.76

Synopsis

- newtype PathBuf = PathBuf (ManagedPtr PathBuf)
- newZeroPathBuf :: MonadIO m => m PathBuf
- pathBufClear :: (HasCallStack, MonadIO m) => PathBuf -> m ()
- pathBufClearToPath :: (HasCallStack, MonadIO m) => PathBuf -> m (Maybe [Char])
- pathBufEqual :: (HasCallStack, MonadIO m) => Ptr () -> Ptr () -> m Bool
- pathBufFree :: (HasCallStack, MonadIO m) => PathBuf -> m ()
- pathBufFreeToPath :: (HasCallStack, MonadIO m) => PathBuf -> m (Maybe [Char])
- pathBufInit :: (HasCallStack, MonadIO m) => PathBuf -> m PathBuf
- pathBufInitFromPath :: (HasCallStack, MonadIO m) => PathBuf -> Maybe [Char] -> m PathBuf
- pathBufPop :: (HasCallStack, MonadIO m) => PathBuf -> m Bool
- pathBufPush :: (HasCallStack, MonadIO m) => PathBuf -> [Char] -> m PathBuf
- pathBufSetExtension :: (HasCallStack, MonadIO m) => PathBuf -> Maybe [Char] -> m Bool
- pathBufSetFilename :: (HasCallStack, MonadIO m) => PathBuf -> [Char] -> m Bool
- pathBufToPath :: (HasCallStack, MonadIO m) => PathBuf -> m (Maybe [Char])

# Exported types

newtype PathBuf Source #

Memory-managed wrapper type.

Constructors

PathBuf (ManagedPtr PathBuf) |

#### Instances

Instances details

Eq PathBuf Source # |
Instance details Defined in GI.GLib.Structs.PathBuf Methods (==) :: PathBuf -> PathBuf -> Bool Source # (/=) :: PathBuf -> PathBuf -> Bool Source #
BoxedPtr PathBuf Source # |
Instance details Defined in GI.GLib.Structs.PathBuf Methods boxedPtrCopy :: PathBuf -> IO PathBuf Source # boxedPtrFree :: PathBuf -> IO () Source #
CallocPtr PathBuf Source # |
Instance details Defined in GI.GLib.Structs.PathBuf Methods boxedPtrCalloc :: IO (Ptr PathBuf) Source #
ManagedPtrNewtype PathBuf Source # |
Instance details Defined in GI.GLib.Structs.PathBuf Methods toManagedPtr :: PathBuf -> ManagedPtr PathBuf Source #
tag ~ 'AttrSet => Constructible PathBuf tag Source # |
Instance details Defined in GI.GLib.Structs.PathBuf Methods new :: MonadIO m => (ManagedPtr PathBuf -> PathBuf) -> [AttrOp PathBuf tag] -> m PathBuf Source #

newZeroPathBuf :: MonadIO m => m PathBuf Source #

Construct a `PathBuf` struct initialized to zero.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

clear, clearToPath, free, freeToPath, init, initFromPath, pop, push, toPath.

#### Getters

None.

#### Setters

setExtension, setFilename.

## clear

pathBufClear Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuf | `buf`: a path buffer
-> m () |

Clears the contents of the path buffer.

This function should be use to free the resources in a stack-allocated `GPathBuf` initialized using `pathBufInit` or `pathBufInitFromPath`.

Since: 2.76

## clearToPath

pathBufClearToPath Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuf | `buf`: a path buffer
-> m (Maybe [Char]) | Returns: the built path

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

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

See also: `pathBufToPath`

Since: 2.76

## equal

pathBufEqual Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Ptr () | `v1`: a path buffer to compare
-> Ptr () | `v2`: a path buffer to compare
-> m Bool | Returns: `TRUE` if the two path buffers are equal, and `FALSE` otherwise

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.

Since: 2.76

## free

pathBufFree Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuf | `buf`: a path buffer
-> m () |

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

Since: 2.76

## freeToPath

pathBufFreeToPath Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuf | `buf`: a path buffer
-> m (Maybe [Char]) | Returns: the path

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: `pathBufToPath`

Since: 2.76

## init

pathBufInit Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuf | `buf`: a path buffer
-> m PathBuf | Returns: the initialized path builder

Initializes a `GPathBuf` instance.

Since: 2.76

## initFromPath

pathBufInitFromPath Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuf | `buf`: a path buffer
-> Maybe [Char] | `path`: a file system path
-> m PathBuf | Returns: the initialized path builder

Initializes a `GPathBuf` instance with the given path.

Since: 2.76

## pop

pathBufPop Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuf | `buf`: a path buffer
-> m Bool | Returns: `TRUE` if the buffer was modified and `FALSE` otherwise

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.

### C code

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

Since: 2.76

## push

pathBufPush Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuf | `buf`: a path buffer
-> [Char] | `path`: a path
-> m PathBuf | Returns: the same pointer to `buf`, for convenience

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

### C code

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

Since: 2.76

## setExtension

pathBufSetExtension Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuf | `buf`: a path buffer
-> Maybe [Char] | `extension`: the file extension
-> m Bool | Returns: `TRUE` if the extension was replaced, and `FALSE` otherwise

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.

Since: 2.76

## setFilename

pathBufSetFilename Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuf | `buf`: a path buffer
-> [Char] | `fileName`: the file name in the path
-> m Bool | Returns: `TRUE` if the file name was replaced, and `FALSE` otherwise

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 `fileName`.

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

### C code

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

Since: 2.76

## toPath

pathBufToPath Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuf | `buf`: a path buffer
-> m (Maybe [Char]) | Returns: the path

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`.

Since: 2.76