Copyright	Will Thompson, Iñaki García Etxebarria and Jonas Platte
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell	None
Language	Haskell2010

GI.GLib.Structs.VariantDict

Contents

Exported types
Methods

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

Synopsis

Exported types

newtype VariantDict Source #

Constructors

VariantDict (ManagedPtr VariantDict)

Instances

BoxedObject VariantDict Source #
Methods boxedType :: VariantDict -> IO GType #
((~) * info (ResolveVariantDictMethod t VariantDict), MethodInfo * info VariantDict p) => IsLabel t (VariantDict -> p) Source #
Methods fromLabel :: Proxy# Symbol t -> VariantDict -> p #
((~) * info (ResolveVariantDictMethod t VariantDict), MethodInfo * info VariantDict p) => IsLabelProxy t (VariantDict -> p) Source #
Methods fromLabelProxy :: Proxy Symbol t -> VariantDict -> p #
HasAttributeList * VariantDict Source #

((~) * signature (m ()), MonadIO m) => MethodInfo * VariantDictUnrefMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictUnrefMethodInfo VariantDict -> signature -> s #
((~) * signature (Text -> m Bool), MonadIO m) => MethodInfo * VariantDictRemoveMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictRemoveMethodInfo VariantDict -> signature -> s #
((~) * signature (m VariantDict), MonadIO m) => MethodInfo * VariantDictRefMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictRefMethodInfo VariantDict -> signature -> s #
((~) * signature (Text -> Maybe VariantType -> m GVariant), MonadIO m) => MethodInfo * VariantDictLookupValueMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictLookupValueMethodInfo VariantDict -> signature -> s #
((~) * signature (Text -> GVariant -> m ()), MonadIO m) => MethodInfo * VariantDictInsertValueMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictInsertValueMethodInfo VariantDict -> signature -> s #
((~) * signature (m GVariant), MonadIO m) => MethodInfo * VariantDictEndMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictEndMethodInfo VariantDict -> signature -> s #
((~) * signature (Text -> m Bool), MonadIO m) => MethodInfo * VariantDictContainsMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictContainsMethodInfo VariantDict -> signature -> s #
((~) * signature (m ()), MonadIO m) => MethodInfo * VariantDictClearMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictClearMethodInfo VariantDict -> signature -> s #
type AttributeList VariantDict Source #
type AttributeList VariantDict

noVariantDict :: Maybe VariantDict Source #

Methods

clear

data VariantDictClearMethodInfo Source #

Instances

((~) * signature (m ()), MonadIO m) => MethodInfo * VariantDictClearMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictClearMethodInfo VariantDict -> signature -> s #

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

data VariantDictContainsMethodInfo Source #

Instances

((~) * signature (Text -> m Bool), MonadIO m) => MethodInfo * VariantDictContainsMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictContainsMethodInfo VariantDict -> signature -> s #

variantDictContains Source #

Arguments

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

Checks if key exists in dict.

Since: 2.40

end

data VariantDictEndMethodInfo Source #

Instances

((~) * signature (m GVariant), MonadIO m) => MethodInfo * VariantDictEndMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictEndMethodInfo VariantDict -> signature -> s #

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

data VariantDictInsertValueMethodInfo Source #

Instances

((~) * signature (Text -> GVariant -> m ()), MonadIO m) => MethodInfo * VariantDictInsertValueMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictInsertValueMethodInfo VariantDict -> signature -> s #

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

data VariantDictLookupValueMethodInfo Source #

Instances

((~) * signature (Text -> Maybe VariantType -> m GVariant), MonadIO m) => MethodInfo * VariantDictLookupValueMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictLookupValueMethodInfo VariantDict -> signature -> s #

variantDictLookupValue Source #

Arguments

:: (HasCallStack, MonadIO m)
=> VariantDict	`dict`: a `VariantDict`
-> Text	`key`: the key to lookup in the dictionary
-> Maybe VariantType	`expectedType`: a `VariantType`, or `Nothing`
-> m 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

data VariantDictRefMethodInfo Source #

Instances

((~) * signature (m VariantDict), MonadIO m) => MethodInfo * VariantDictRefMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictRefMethodInfo VariantDict -> signature -> s #

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

data VariantDictRemoveMethodInfo Source #

Instances

((~) * signature (Text -> m Bool), MonadIO m) => MethodInfo * VariantDictRemoveMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictRemoveMethodInfo VariantDict -> signature -> s #

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

data VariantDictUnrefMethodInfo Source #

Instances

((~) * signature (m ()), MonadIO m) => MethodInfo * VariantDictUnrefMethodInfo VariantDict signature Source #
Methods overloadedMethod :: MethodProxy VariantDictUnrefMethodInfo VariantDict -> signature -> s #

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