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 | None
Language | Haskell2010

GI.GLib.Structs.VariantDict

Contents

- Exported types
- Methods
  - clear
  - contains
  - end
  - insertValue
  - lookupValue
  - new
  - ref
  - remove
  - unref

Description

`VariantDict` is a mutable interface to `GVariant` dictionaries.

It can be used for doing a sequence of dictionary lookups in an efficient way on an existing `GVariant` dictionary or it can be used to construct new dictionaries with a hashtable-like interface. It can also be used for taking existing dictionaries and modifying them in order to create new ones.

`VariantDict` can only be used with `G_VARIANT_TYPE_VARDICT` dictionaries.

It is possible to use `VariantDict` allocated on the stack or on the heap. When using a stack-allocated `VariantDict`, you begin with a call to `g_variant_dict_init()` and free the resources with a call to `variantDictClear`.

Heap-allocated `VariantDict` follows normal refcounting rules: you allocate it with `variantDictNew` and use `variantDictRef` and `variantDictUnref`.

`variantDictEnd` is used to convert the `VariantDict` back into a dictionary-type `GVariant`. When used with stack-allocated instances, this also implicitly frees all associated memory, but for heap-allocated instances, you must still call `variantDictUnref` afterwards.

You will typically want to use a heap-allocated `VariantDict` when you expose it as part of an API. For most other uses, the stack-allocated form will be more convenient.

Consider the following two examples that do the same thing in each style: take an existing dictionary and look up the "count" uint32 key, adding 1 to it if it is found, or returning an error if the key is not found. Each returns the new dictionary as a floating `GVariant`.

## Using a stack-allocated GVariantDict

### C code

     GVariant *
     add_to_count (GVariant  *orig,
                   GError   **error)
     {
       GVariantDict dict;
       guint32 count;

       g_variant_dict_init (&dict, orig);
       if (!g_variant_dict_lookup (&dict, "count", "u", &count))
         {
           g_set_error (...);
           g_variant_dict_clear (&dict);
           return NULL;
         }

       g_variant_dict_insert (&dict, "count", "u", count + 1);

       return g_variant_dict_end (&dict);
     }

## Using heap-allocated GVariantDict

### C code

     GVariant *
     add_to_count (GVariant  *orig,
                   GError   **error)
     {
       GVariantDict *dict;
       GVariant *result;
       guint32 count;

       dict = g_variant_dict_new (orig);

       if (g_variant_dict_lookup (dict, "count", "u", &count))
         {
           g_variant_dict_insert (dict, "count", "u", count + 1);
           result = g_variant_dict_end (dict);
         }
       else
         {
           g_set_error (...);
           result = NULL;
         }

       g_variant_dict_unref (dict);

       return result;
     }

Since: 2.40

Synopsis

- newtype VariantDict = VariantDict (ManagedPtr VariantDict)
- variantDictClear :: (HasCallStack, MonadIO m) => VariantDict -> m ()
- variantDictContains :: (HasCallStack, MonadIO m) => VariantDict -> Text -> m Bool
- variantDictEnd :: (HasCallStack, MonadIO m) => VariantDict -> m GVariant
- variantDictInsertValue :: (HasCallStack, MonadIO m) => VariantDict -> Text -> GVariant -> m ()
- variantDictLookupValue :: (HasCallStack, MonadIO m) => VariantDict -> Text -> Maybe VariantType -> m (Maybe GVariant)
- variantDictNew :: (HasCallStack, MonadIO m) => Maybe GVariant -> m VariantDict
- variantDictRef :: (HasCallStack, MonadIO m) => VariantDict -> m VariantDict
- variantDictRemove :: (HasCallStack, MonadIO m) => VariantDict -> Text -> m Bool
- variantDictUnref :: (HasCallStack, MonadIO m) => VariantDict -> m ()

# Exported types

newtype VariantDict Source #

Memory-managed wrapper type.

Constructors

VariantDict (ManagedPtr VariantDict) |

#### Instances

Instances details

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

# Methods

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

Expand

#### Methods

clear, contains, end, insertValue, lookupValue, ref, remove, unref.

#### Getters

None.

#### Setters

None.

## clear

variantDictClear Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantDict | `dict`: a `VariantDict`
-> m () |

Releases all memory associated with a `VariantDict` without freeing the `VariantDict` structure itself.

It typically only makes sense to do this on a stack-allocated `VariantDict` if you want to abort building the value part-way through. This function need not be called if you call `variantDictEnd` and it also doesn't need to be called on dicts allocated with g_variant_dict_new (see `variantDictUnref` for that).

It is valid to call this function on either an initialised `VariantDict` or one that was previously cleared by an earlier call to `variantDictClear` but it is not valid to call this function on uninitialised memory.

Since: 2.40

## contains

variantDictContains Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantDict | `dict`: a `VariantDict`
-> Text | `key`: the key to look up in the dictionary
-> m Bool | Returns: `True` if `key` is in `dict`

Checks if `key` exists in `dict`.

Since: 2.40

## end

variantDictEnd Source #

Arguments

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

Returns the current value of `dict` as a `GVariant` of type `G_VARIANT_TYPE_VARDICT`, clearing it in the process.

It is not permissible to use `dict` in any way after this call except for reference counting operations (in the case of a heap-allocated `VariantDict`) or by reinitialising it with `g_variant_dict_init()` (in the case of stack-allocated).

Since: 2.40

## insertValue

variantDictInsertValue Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantDict | `dict`: a `VariantDict`
-> Text | `key`: the key to insert a value for
-> GVariant | `value`: the value to insert
-> m () |

Inserts (or replaces) a key in a `VariantDict`.

`value` is consumed if it is floating.

Since: 2.40

## lookupValue

variantDictLookupValue Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantDict | `dict`: a `VariantDict`
-> Text | `key`: the key to look up in the dictionary
-> Maybe VariantType | `expectedType`: a `VariantType`, or `Nothing`
-> m (Maybe GVariant) | Returns: the value of the dictionary key, or `Nothing`

Looks up a value in a `VariantDict`.

If `key` is not found in `dictionary`, `Nothing` is returned.

The `expectedType` string specifies what type of value is expected. If the value associated with `key` has a different type then `Nothing` is returned.

If the key is found and the value has the correct type, it is returned. If `expectedType` was specified then any non-`Nothing` return value will have this type.

Since: 2.40

## new

variantDictNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Maybe GVariant | `fromAsv`: the `GVariant` with which to initialise the dictionary
-> m VariantDict | Returns: a `VariantDict`

Allocates and initialises a new `VariantDict`.

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

In some cases it may be easier to place a `VariantDict` directly on the stack of the calling function and initialise it with `g_variant_dict_init()`. This is particularly useful when you are using `VariantDict` to construct a `GVariant`.

Since: 2.40

## ref

variantDictRef Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantDict | `dict`: a heap-allocated `VariantDict`
-> m VariantDict | Returns: a new reference to `dict`

Increases the reference count on `dict`.

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

Since: 2.40

## remove

variantDictRemove Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantDict | `dict`: a `VariantDict`
-> Text | `key`: the key to remove
-> m Bool | Returns: `True` if the key was found and removed

Removes a key and its associated value from a `VariantDict`.

Since: 2.40

## unref

variantDictUnref Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> VariantDict | `dict`: a heap-allocated `VariantDict`
-> m () |

Decreases the reference count on `dict`.

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

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

Since: 2.40