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 |
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; }
- newtype VariantDict = VariantDict (ManagedPtr VariantDict)
- noVariantDict :: Maybe VariantDict
- data VariantDictClearMethodInfo
- variantDictClear :: (HasCallStack, MonadIO m) => VariantDict -> m ()
- data VariantDictContainsMethodInfo
- variantDictContains :: (HasCallStack, MonadIO m) => VariantDict -> Text -> m Bool
- data VariantDictEndMethodInfo
- variantDictEnd :: (HasCallStack, MonadIO m) => VariantDict -> m GVariant
- data VariantDictInsertValueMethodInfo
- variantDictInsertValue :: (HasCallStack, MonadIO m) => VariantDict -> Text -> GVariant -> m ()
- data VariantDictLookupValueMethodInfo
- variantDictLookupValue :: (HasCallStack, MonadIO m) => VariantDict -> Text -> Maybe VariantType -> m GVariant
- variantDictNew :: (HasCallStack, MonadIO m) => Maybe GVariant -> m VariantDict
- data VariantDictRefMethodInfo
- variantDictRef :: (HasCallStack, MonadIO m) => VariantDict -> m VariantDict
- data VariantDictRemoveMethodInfo
- variantDictRemove :: (HasCallStack, MonadIO m) => VariantDict -> Text -> m Bool
- data VariantDictUnrefMethodInfo
- variantDictUnref :: (HasCallStack, MonadIO m) => VariantDict -> m ()
Exported types
newtype VariantDict Source #
Methods
clear
data VariantDictClearMethodInfo Source #
((~) * signature (m ()), MonadIO m) => MethodInfo * VariantDictClearMethodInfo VariantDict signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> 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 #
((~) * signature (Text -> m Bool), MonadIO m) => MethodInfo * VariantDictContainsMethodInfo VariantDict signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> VariantDict |
|
-> Text |
|
-> m Bool | Returns: |
Checks if key
exists in dict
.
Since: 2.40
end
data VariantDictEndMethodInfo Source #
((~) * signature (m GVariant), MonadIO m) => MethodInfo * VariantDictEndMethodInfo VariantDict signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> VariantDict |
|
-> m GVariant | Returns: a new, floating, |
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 #
((~) * signature (Text -> GVariant -> m ()), MonadIO m) => MethodInfo * VariantDictInsertValueMethodInfo VariantDict signature Source # | |
variantDictInsertValue Source #
:: (HasCallStack, MonadIO m) | |
=> VariantDict |
|
-> Text |
|
-> GVariant |
|
-> m () |
lookupValue
data VariantDictLookupValueMethodInfo Source #
((~) * signature (Text -> Maybe VariantType -> m GVariant), MonadIO m) => MethodInfo * VariantDictLookupValueMethodInfo VariantDict signature Source # | |
variantDictLookupValue Source #
:: (HasCallStack, MonadIO m) | |
=> VariantDict |
|
-> Text |
|
-> Maybe VariantType |
|
-> m GVariant | Returns: the value of the dictionary key, or |
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
:: (HasCallStack, MonadIO m) | |
=> Maybe GVariant |
|
-> m VariantDict | Returns: a |
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 #
((~) * signature (m VariantDict), MonadIO m) => MethodInfo * VariantDictRefMethodInfo VariantDict signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> VariantDict |
|
-> m VariantDict | Returns: a new reference to |
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 #
((~) * signature (Text -> m Bool), MonadIO m) => MethodInfo * VariantDictRemoveMethodInfo VariantDict signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> VariantDict |
|
-> Text |
|
-> m Bool | Returns: |
Removes a key and its associated value from a VariantDict
.
Since: 2.40
unref
data VariantDictUnrefMethodInfo Source #
((~) * signature (m ()), MonadIO m) => MethodInfo * VariantDictUnrefMethodInfo VariantDict signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> 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