Package ch.bailu.gtk.glib

Class VariantDict

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.type.Record
ch.bailu.gtk.glib.VariantDict
All Implemented Interfaces:
PointerInterface
public class VariantDict extends Record
#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 
<!-- language="C" -->
   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 
<!-- language="C" -->
   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;
   }

https://docs.gtk.org/glib/struct.VariantDict.html

  • Constructor Details

    • VariantDict

      public VariantDict(PointerContainer pointer)

    • VariantDict

      public VariantDict(@Nullable Variant from_asv)
      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.
      Parameters:
      from_asv - the #GVariant with which to initialise the dictionary

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • clear

      public void 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.

    • contains

      public boolean contains(@Nonnull Str key)
      Checks if @key exists in @dict.
      Parameters:
      key - the key to look up in the dictionary
      Returns:
      %TRUE if @key is in @dict

    • contains

      public boolean contains(String key)
      Checks if @key exists in @dict.
      Parameters:
      key - the key to look up in the dictionary
      Returns:
      %TRUE if @key is in @dict

    • end

      public Variant 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).
      Returns:
      a new, floating, #GVariant

    • init

      public void init(@Nullable Variant 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.
      Parameters:
      from_asv - the initial value for @dict

    • insert

      public void insert(@Nonnull Str key, @Nonnull Str format_string, Object... _elipse)
      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().
      Parameters:
      key - the key to insert a value for
      format_string - a #GVariant varargs format string
      _elipse - arguments, as per @format_string

    • insert

      public void insert(String key, String format_string, Object... _elipse)
      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().
      Parameters:
      key - the key to insert a value for
      format_string - a #GVariant varargs format string
      _elipse - arguments, as per @format_string

    • insertValue

      public void insertValue(@Nonnull Str key, @Nonnull Variant value)
      Inserts (or replaces) a key in a #GVariantDict.

      @value is consumed if it is floating.
      Parameters:
      key - the key to insert a value for
      value - the value to insert

    • insertValue

      public void insertValue(String key, @Nonnull Variant value)
      Inserts (or replaces) a key in a #GVariantDict.

      @value is consumed if it is floating.
      Parameters:
      key - the key to insert a value for
      value - the value to insert

    • lookup

      public boolean lookup(@Nonnull Str key, @Nonnull Str format_string, Object... _elipse)
      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. 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][gvariant-format-strings-pointers].
      Parameters:
      key - the key to look up in the dictionary
      format_string - a GVariant format string
      _elipse - the arguments to unpack the value into
      Returns:
      %TRUE if a value was unpacked

    • lookup

      public boolean lookup(String key, String format_string, Object... _elipse)
      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. 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][gvariant-format-strings-pointers].
      Parameters:
      key - the key to look up in the dictionary
      format_string - a GVariant format string
      _elipse - the arguments to unpack the value into
      Returns:
      %TRUE if a value was unpacked

    • lookupValue

      public Variant lookupValue(@Nonnull Str key, @Nullable VariantType 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.
      Parameters:
      key - the key to look up in the dictionary
      expected_type - a #GVariantType, or %NULL
      Returns:
      the value of the dictionary key, or %NULL

    • lookupValue

      public Variant lookupValue(String key, @Nullable VariantType 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.
      Parameters:
      key - the key to look up in the dictionary
      expected_type - a #GVariantType, or %NULL
      Returns:
      the value of the dictionary key, or %NULL

    • ref

      public VariantDict ref()
      Increases the reference count on @dict.

      Don't call this on stack-allocated #GVariantDict instances or bad
      things will happen.
      Returns:
      a new reference to @dict

    • remove

      public boolean remove(@Nonnull Str key)
      Removes a key and its associated value from a #GVariantDict.
      Parameters:
      key - the key to remove
      Returns:
      %TRUE if the key was found and removed

    • remove

      public boolean remove(String key)
      Removes a key and its associated value from a #GVariantDict.
      Parameters:
      key - the key to remove
      Returns:
      %TRUE if the key was found and removed

    • unref

      public void 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.

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()