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

Contents

- Exported types
- Methods
  - addValue
  - close
  - end
  - new
  - open
  - ref
  - unref

Description

A utility type for constructing container-type `GVariant` instances.

This is an opaque structure and may only be accessed using the following functions.

`VariantBuilder` is not threadsafe in any way. Do not attempt to access it from more than one thread.

Synopsis

- newtype VariantBuilder = VariantBuilder (ManagedPtr VariantBuilder)
- variantBuilderAddValue :: (HasCallStack, MonadIO m) => VariantBuilder -> GVariant -> m ()
- variantBuilderClose :: (HasCallStack, MonadIO m) => VariantBuilder -> m ()
- variantBuilderEnd :: (HasCallStack, MonadIO m) => VariantBuilder -> m GVariant
- variantBuilderNew :: (HasCallStack, MonadIO m) => VariantType -> m VariantBuilder
- variantBuilderOpen :: (HasCallStack, MonadIO m) => VariantBuilder -> VariantType -> m ()
- variantBuilderRef :: (HasCallStack, MonadIO m) => VariantBuilder -> m VariantBuilder
- variantBuilderUnref :: (HasCallStack, MonadIO m) => VariantBuilder -> m ()

# Exported types

newtype VariantBuilder Source #

Memory-managed wrapper type.

Constructors

VariantBuilder (ManagedPtr VariantBuilder) |

#### Instances

Instances details

Eq VariantBuilder Source # |
Instance details Defined in GI.GLib.Structs.VariantBuilder Methods (==) :: VariantBuilder -> VariantBuilder -> Bool Source # (/=) :: VariantBuilder -> VariantBuilder -> Bool Source #
GBoxed VariantBuilder Source # |
Instance details Defined in GI.GLib.Structs.VariantBuilder
ManagedPtrNewtype VariantBuilder Source # |
Instance details Defined in GI.GLib.Structs.VariantBuilder Methods toManagedPtr :: VariantBuilder -> ManagedPtr VariantBuilder Source #
TypedObject VariantBuilder Source # |
Instance details Defined in GI.GLib.Structs.VariantBuilder Methods glibType :: IO GType Source #
HasParentTypes VariantBuilder Source # |
Instance details Defined in GI.GLib.Structs.VariantBuilder
IsGValue (Maybe VariantBuilder) Source # | Convert `VariantBuilder` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.GLib.Structs.VariantBuilder Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe VariantBuilder -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe VariantBuilder) Source #
type ParentTypes VariantBuilder Source # |
Instance details Defined in GI.GLib.Structs.VariantBuilder type ParentTypes VariantBuilder = '[] :: [Type]

# Methods

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

Expand

#### Methods

addValue, close, end, open, ref, unref.

#### Getters

None.

#### Setters

None.

## addValue

variantBuilderAddValue Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantBuilder | `builder`: a `VariantBuilder`
-> GVariant | `value`: a `GVariant`
-> m () |

Adds `value` to `builder`.

It is an error to call this function in any way that would create an inconsistent value to be constructed. Some examples of this are putting different types of items into an array, putting the wrong types or number of items in a tuple, putting more than one value into a variant, etc.

If `value` is a floating reference (see `variantRefSink`), the `builder` instance takes ownership of `value`.

Since: 2.24

## close

variantBuilderClose Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantBuilder | `builder`: a `VariantBuilder`
-> m () |

Closes the subcontainer inside the given `builder` that was opened by the most recent call to `variantBuilderOpen`.

It is an error to call this function in any way that would create an inconsistent value to be constructed (ie: too few values added to the subcontainer).

Since: 2.24

## end

variantBuilderEnd Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantBuilder | `builder`: a `VariantBuilder`
-> m GVariant | Returns: a new, floating, `GVariant`

Ends the builder process and returns the constructed value.

It is not permissible to use `builder` in any way after this call except for reference counting operations (in the case of a heap-allocated `VariantBuilder`) or by reinitialising it with `g_variant_builder_init()` (in the case of stack-allocated). This means that for the stack-allocated builders there is no need to call `g_variant_builder_clear()` after the call to `variantBuilderEnd`.

It is an error to call this function in any way that would create an inconsistent value to be constructed (ie: insufficient number of items added to a container with a specific number of children required). It is also an error to call this function if the builder was created with an indefinite array or maybe type and no children have been added; in this case it is impossible to infer the type of the empty array.

Since: 2.24

## new

variantBuilderNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantType | `type`: a container type
-> m VariantBuilder | Returns: a `VariantBuilder`

Allocates and initialises a new `VariantBuilder`.

You should call `variantBuilderUnref` on the return value when it is no longer needed. The memory will not be automatically freed by any other call.

In most cases it is easier to place a `VariantBuilder` directly on the stack of the calling function and initialise it with `g_variant_builder_init()`.

Since: 2.24

## open

variantBuilderOpen Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantBuilder | `builder`: a `VariantBuilder`
-> VariantType | `type`: the `VariantType` of the container
-> m () |

Opens a subcontainer inside the given `builder`. When done adding items to the subcontainer, `variantBuilderClose` must be called. `type` is the type of the container: so to build a tuple of several values, `type` must include the tuple itself.

It is an error to call this function in any way that would cause an inconsistent value to be constructed (ie: adding too many values or a value of an incorrect type).

Example of building a nested variant:

### C code

    GVariantBuilder builder;
    guint32 some_number = get_number ();
    g_autoptr (GHashTable) some_dict = get_dict ();
    GHashTableIter iter;
    const gchar *key;
    const GVariant *value;
    g_autoptr (GVariant) output = NULL;

    g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})"));
    g_variant_builder_add (&builder, "u", some_number);
    g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}"));

    g_hash_table_iter_init (&iter, some_dict);
    while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value))
      {
        g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}"));
        g_variant_builder_add (&builder, "s", key);
        g_variant_builder_add (&builder, "v", value);
        g_variant_builder_close (&builder);
      }

    g_variant_builder_close (&builder);

    output = g_variant_builder_end (&builder);

Since: 2.24

## ref

variantBuilderRef Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantBuilder | `builder`: a `VariantBuilder` allocated by `variantBuilderNew`
-> m VariantBuilder | Returns: a new reference to `builder`

Increases the reference count on `builder`.

Don't call this on stack-allocated `VariantBuilder` instances or bad things will happen.

Since: 2.24

## unref

variantBuilderUnref Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantBuilder | `builder`: a `VariantBuilder` allocated by `variantBuilderNew`
-> m () |

Decreases the reference count on `builder`.

In the event that there are no more references, releases all memory associated with the `VariantBuilder`.

Don't call this on stack-allocated `VariantBuilder` instances or bad things will happen.

Since: 2.24