GI.GLib.Structs.UriParamsIter

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

Exported types

newtype UriParamsIter

Memory-managed wrapper type.

Constructors

UriParamsIter (ManagedPtr UriParamsIter)

Instances

Eq UriParamsIter

Defined in GI.GLib.Structs.UriParamsIter

Methods

(==) :: UriParamsIter -> UriParamsIter -> Bool

(/=) :: UriParamsIter -> UriParamsIter -> Bool

BoxedPtr UriParamsIter

Defined in GI.GLib.Structs.UriParamsIter

Methods

boxedPtrCopy :: UriParamsIter -> IO UriParamsIter

boxedPtrFree :: UriParamsIter -> IO ()

CallocPtr UriParamsIter

Defined in GI.GLib.Structs.UriParamsIter

Methods

boxedPtrCalloc :: IO (Ptr UriParamsIter)

ManagedPtrNewtype UriParamsIter

Defined in GI.GLib.Structs.UriParamsIter

Methods

toManagedPtr :: UriParamsIter -> ManagedPtr UriParamsIter

tag ~ 'AttrSet => Constructible UriParamsIter tag

Defined in GI.GLib.Structs.UriParamsIter

Methods

new :: MonadIO m => (ManagedPtr UriParamsIter -> UriParamsIter) -> [AttrOp UriParamsIter tag] -> m UriParamsIter

newZeroUriParamsIter :: MonadIO m => m UriParamsIter

Construct a UriParamsIter struct initialized to zero.

Methods

Click to display all available methods, including inherited ones

Methods

init, next.

Getters

None.

Setters

None.

init

uriParamsIterInit

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

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