class: GVariantDict

[44:7] extends: object

#GVariantDict 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. #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT dictionaries. It is possible to use #GVariantDict allocated on the stack or on the heap. When using a stack-allocated #GVariantDict, you begin with a call to g_variant_dict_init() and free the resources with a call to g_variant_dict_clear(). Heap-allocated #GVariantDict follows normal refcounting rules: you allocate it with g_variant_dict_new() and use g_variant_dict_ref() and g_variant_dict_unref(). g_variant_dict_end() is used to convert the #GVariantDict 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 g_variant_dict_unref() afterwards. You will typically want to use a heap-allocated #GVariantDict 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 |[ 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 |[ 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; } ]|

Members

handleObj
lib
retainedCallbacks
signalHandlerNames
signalSetterHandlers

Methods

GVariantDict (from_asv = null)

Allocates and initialises a new #GVariantDict. You should call g_variant_dict_unref() 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 #GVariantDict directly on the stack of the calling function and initialise it with g_variant_dict_init(). This is particularly useful when you are using #GVariantDict to construct a #GVariant.
- @p from_asv is the #GVariant with which to initialise the dictionary.
toNativeHandle (Source)

Normalizes a constructor argument into a raw pointer carrier. Accepts a raw NativeHandle, a raw NativeBuffer returned from fn.call(...), another generated wrapper exposing handle(), or null. Returns null when the argument carries no pointer.
- @p Source is the raw handle, raw buffer, wrapper, or null.
- @r A raw pointer carrier or null when no pointer is present.
getLib ()

Returns the opened native library for this generated wrapper.
- @r The opened native library.
handle ()

Returns the wrapped NativeHandle.
- @r The wrapped NativeHandle.
isNull ()

Returns true when the wrapped handle is null.
- @r A bool.
describe ()

Returns a small string for debugging generated wrappers.
- @r A string.
clear ()

Releases all memory associated with a #GVariantDict without freeing the #GVariantDict structure itself. It typically only makes sense to do this on a stack-allocated #GVariantDict if you want to abort building the value part-way through. This function need not be called if you call g_variant_dict_end() and it also doesn't need to be called on dicts allocated with g_variant_dict_new (see g_variant_dict_unref() for that). It is valid to call this function on either an initialised #GVariantDict or one that was previously cleared by an earlier call to g_variant_dict_clear() but it is not valid to call this function on uninitialised memory.
- @r None.
contains (string key)

Checks if @key exists in @dict.
- @p key is the key to look up in the dictionary.
- @r %TRUE if @key is in @dict.
end ()

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 #GVariantDict) or by reinitialising it with g_variant_dict_init() (in the case of stack-allocated).
- @r a new, floating, #GVariant.
init (object from_asv)

Initialises a #GVariantDict structure. If @from_asv is given, it is used to initialise the dictionary. This function completely ignores the previous contents of @dict. On one hand this means that it is valid to pass in completely uninitialised memory. On the other hand, this means that if you are initialising over top of an existing #GVariantDict you need to first call g_variant_dict_clear() in order to avoid leaking memory. You must not call g_variant_dict_ref() or g_variant_dict_unref() on a #GVariantDict that was initialised with this function. If you ever pass a reference to a #GVariantDict outside of the control of your own code then you should assume that the person receiving that reference may try to use reference counting; you should use g_variant_dict_new() instead of this function.
- @p from_asv is the initial value for @dict.
- @r None.
insert (string key, string format_string, list varargs)

Inserts a value into a #GVariantDict. This call is a convenience wrapper that is exactly equivalent to calling g_variant_new() followed by g_variant_dict_insert_value().
- @p key is the key to insert a value for.
- @p format_string is a #GVariant varargs format string.
- @p ... is arguments, as per @format_string.
- @r None.
insert_value (string key, object value)

Inserts (or replaces) a key in a #GVariantDict. @value is consumed if it is floating.
- @p key is the key to insert a value for.
- @p value is the value to insert.
- @r None.
lookup (string key, string format_string, list varargs)

Looks up a value in a #GVariantDict. This function is a wrapper around g_variant_dict_lookup_value() and g_variant_get(). In the case that %NULL would have been returned, this function returns %FALSE and does not modify the values of the arguments passed in to @.... Otherwise, it unpacks the returned value and returns %TRUE. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on GVariant format strings.
- @p key is the key to look up in the dictionary.
- @p format_string is a GVariant format string.
- @p ... is the arguments to unpack the value into.
- @r %TRUE if a value was unpacked.
lookup_value (string key, object expected_type)

Looks up a value in a #GVariantDict. If @key is not found in @dictionary, %NULL is returned. The @expected_type string specifies what type of value is expected. If the value associated with @key has a different type then %NULL is returned. If the key is found and the value has the correct type, it is returned. If @expected_type was specified then any non-%NULL return value will have this type.
- @p key is the key to look up in the dictionary.
- @p expected_type is a #GVariantType, or %NULL.
- @r the value of the dictionary key, or %NULL.
ref ()

Increases the reference count on @dict. Don't call this on stack-allocated #GVariantDict instances or bad things will happen.
- @r a new reference to @dict.
remove (string key)

Removes a key and its associated value from a #GVariantDict.
- @p key is the key to remove.
- @r %TRUE if the key was found and removed.
unref ()

Decreases the reference count on @dict. In the event that there are no more references, releases all memory associated with the #GVariantDict. Don't call this on stack-allocated #GVariantDict instances or bad things will happen.
- @r None.