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

Contents

- Exported types
- Methods
  - init
  - next

Description

Many URI schemes include one or more attribute/value pairs as part of the URI value. For example `scheme://server/path?query=string&is=there` has two attributes – `query=string` and `is=there` – in its query part.

A `UriParamsIter` structure represents an iterator that can be used to iterate over the attribute/value pairs of a URI query string. `UriParamsIter` structures are typically allocated on the stack and then initialized with `uriParamsIterInit`. See the documentation for `uriParamsIterInit` for a usage example.

Since: 2.66

Synopsis

- newtype UriParamsIter = UriParamsIter (ManagedPtr UriParamsIter)
- newZeroUriParamsIter :: MonadIO m => m UriParamsIter
- uriParamsIterInit :: (HasCallStack, MonadIO m) => UriParamsIter -> Text -> Int64 -> Text -> [UriParamsFlags] -> m ()
- uriParamsIterNext :: (HasCallStack, MonadIO m) => UriParamsIter -> m (Maybe Text, Maybe Text)

# Exported types

newtype UriParamsIter Source #

Memory-managed wrapper type.

Constructors

UriParamsIter (ManagedPtr UriParamsIter) |

#### Instances

Instances details

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

newZeroUriParamsIter :: MonadIO m => m UriParamsIter Source #

Construct a `UriParamsIter` struct initialized to zero.

# Methods

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

Expand

#### Methods

init, next.

#### Getters

None.

#### Setters

None.

## init

uriParamsIterInit Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> UriParamsIter | `iter`: an uninitialized `UriParamsIter`
-> Text | `params`: a `%`-encoded string containing `attribute=value` parameters
-> Int64 | `length`: the length of `params`, or `-1` if it is nul-terminated
-> Text | `separators`: the separator byte character set between parameters. (usually `&`, but sometimes `;` or both `&;`). Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters. You may pass an empty set, in which case no splitting will occur.
-> [UriParamsFlags] | `flags`: flags to modify the way the parameters are handled.
-> m () |

Initializes an attribute/value pair iterator.

The iterator keeps pointers to the `params` and `separators` arguments, those variables must thus outlive the iterator and not be modified during the iteration.

If `UriParamsFlagsWwwForm` is passed in `flags`, `+` characters in the param string will be replaced with spaces in the output. For example, `foo=bar+baz` will give attribute `foo` with value `bar baz`. This is commonly used on the web (the `https` and `http` schemes only), but is deprecated in favour of the equivalent of encoding spaces as `%20`.

Unlike with `uriParseParams`, `UriParamsFlagsCaseInsensitive` has no effect if passed to `flags` for `uriParamsIterInit`. The caller is responsible for doing their own case-insensitive comparisons.

### C code

    GUriParamsIter iter;
    GError *error = NULL;
    gchar *unowned_attr, *unowned_value;

    g_uri_params_iter_init (&iter, "foo=bar&baz=bar&Foo=frob&baz=bar2", -1, "&", G_URI_PARAMS_NONE);
    while (g_uri_params_iter_next (&iter, &unowned_attr, &unowned_value, &error))
      {
        g_autofree gchar *attr = g_steal_pointer (&unowned_attr);
        g_autofree gchar *value = g_steal_pointer (&unowned_value);
        // do something with attr and value; this code will be called 4 times
        // for the params string in this example: once with attr=foo and value=bar,
        // then with baz/bar, then Foo/frob, then baz/bar2.
      }
    if (error)
      // handle parsing error

Since: 2.66

## next

uriParamsIterNext Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> UriParamsIter | `iter`: an initialized `UriParamsIter`
-> m (Maybe Text, Maybe Text) | (Can throw `GError`)

Advances `iter` and retrieves the next attribute/value. `False` is returned if an error has occurred (in which case `error` is set), or if the end of the iteration is reached (in which case `attribute` and `value` are set to `Nothing` and the iterator becomes invalid). If `True` is returned, `uriParamsIterNext` may be called again to receive another attribute/value pair.

Note that the same `attribute` may be returned multiple times, since URIs allow repeated attributes.

Since: 2.66