[glib/gvariant] Add some higher level GVariant convenience API

[Ryan Lortie <ryanl src gnome org>]

commit 114cf18c662366dfb31260edc128c6f020619d3e
Author: Ryan Lortie <desrt desrt ca>
Date:   Sun Jun 14 16:55:58 2009 -0400

    Add some higher level GVariant convenience API
    
    g_variant_get_child: unpack a child element
    g_variant_lookup_value: lookup a GVariant from a string dictionary
    g_variant_lookup: lookup and unpack from a string dictionary

 docs/reference/glib/glib-sections.txt |    3 +
 glib/glib.symbols                     |    3 +
 glib/gvariant-util.c                  |   34 ++++++++++++++
 glib/gvariant-valist.c                |   79 +++++++++++++++++++++++++++++++++
 glib/gvariant.h                       |   12 +++++-
 5 files changed, 130 insertions(+), 1 deletions(-)
---
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index f720549..4652cb9 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -2804,6 +2804,9 @@ g_variant_dup_strv
 <SUBSECTION>
 g_variant_n_children
 g_variant_get_child_value
+g_variant_get_child
+g_variant_lookup_value
+g_variant_lookup
 g_variant_get_fixed
 g_variant_get_fixed_array
 
diff --git a/glib/glib.symbols b/glib/glib.symbols
index 2b5a9ce..2387f8d 100644
--- a/glib/glib.symbols
+++ b/glib/glib.symbols
@@ -1693,6 +1693,7 @@ g_variant_builder_check_end
 g_variant_builder_new
 g_variant_builder_end
 g_variant_builder_cancel
+g_variant_lookup_value
 #endif
 
 #if IN_FILE(_gvariant_markup_c_)
@@ -1712,6 +1713,8 @@ g_variant_get
 g_variant_format_string_scan
 g_variant_new_va
 g_variant_get_va
+g_variant_get_child
+g_variant_lookup
 #endif
 #endif
 
diff --git a/glib/gvariant-util.c b/glib/gvariant-util.c
index 56ba795..7e374ac 100644
--- a/glib/gvariant-util.c
+++ b/glib/gvariant-util.c
@@ -1883,5 +1883,39 @@ g_variant_dup_strv (GVariant *value,
   return result;
 }
 
+/**
+ * g_variant_lookup_value:
+ * @dictionary: a #GVariant dictionary, keyed by strings
+ * @key: a string to lookup in the dictionary
+ * @returns: the value corresponding to @key, or %NULL
+
+ * Looks up @key in @dictionary.  This is essentially a convenience
+ * function for dealing with the extremely common case of a dictionary
+ * keyed by strings.
+ *
+ * In the case that the key is found, the corresponding value is
+ * returned; not the dictionary entry.  If the key is not found then
+ * this function returns %NULL.
+ **/
+GVariant *
+g_variant_lookup_value (GVariant    *dictionary,
+                        const gchar *key)
+{
+  GVariantIter iter;
+  const gchar *_key;
+  GVariant *value;
+  GVariant *result = NULL;
+
+  g_variant_iter_init (&iter, dictionary);
+  while (g_variant_iter_next (&iter, "{&s*}", &_key, &value))
+    if (strcmp (_key, key) == 0)
+      {
+        result = g_variant_ref (value);
+        g_variant_iter_cancel (&iter);
+      }
+
+  return result;
+}
+
 #define _gvariant_util_c_
 #include "galiasdef.c"
diff --git a/glib/gvariant-valist.c b/glib/gvariant-valist.c
index 5d85aef..daec123 100644
--- a/glib/gvariant-valist.c
+++ b/glib/gvariant-valist.c
@@ -1416,5 +1416,84 @@ g_variant_builder_add (GVariantBuilder *builder,
   g_variant_builder_add_value (builder, variant);
 }
 
+/**
+ * g_variant_get_child:
+ * @value: a container #GVariant
+ * @index: the index of the child to deconstruct
+ * @format_string: a #GVariant format string
+ * @...: arguments, as per @format_string
+ *
+ * Reads a child item out of a container #GVariant instance and
+ * deconstructs it according to @format_string.  This call is
+ * essentially a combination of g_variant_get_child_value() and
+ * g_variant_get().
+ **/
+void
+g_variant_get_child (GVariant    *value,
+                     gint         index,
+                     const gchar *format_string,
+                     ...)
+{
+  GVariant *child;
+  va_list ap;
+
+  g_variant_flatten (value);
+  child = g_variant_get_child_value (value, index);
+  va_start (ap, format_string);
+  g_variant_get_va (child, NULL, &format_string, &ap);
+  va_end (ap);
+
+  g_variant_unref (child);
+}
+
+/**
+ * g_variant_lookup:
+ * @dictionary: a #GVariant dictionary, keyed by strings
+ * @key: a string to lookup in the dictionary
+ * @format_string: a #GVariant format string, or %NULL
+ * @...: arguments, as per @format_string
+ * @returns: %TRUE if @key was found, else %FALSE
+ *
+ * Looks up @key in @dictionary and deconstructs it according to
+ * @format_string.  This call is essentially a combination of
+ * g_variant_lookup_value() and g_variant_get().
+ *
+ * If @key is not found, then no deconstruction occurs (ie: the argument
+ * list is left untouched) and %FALSE is returned.  If @key is found
+ * then %TRUE is returned.
+ *
+ * As a special case, if @format_string is %NULL then the lookup occurs
+ * but no deconstruction is preformed.  This is useful for checking (via
+ * the return value) if a key is in the dictionary or not.
+ **/
+gboolean
+g_variant_lookup (GVariant    *dictionary,
+                  const gchar *key,
+                  const gchar *format_string,
+                  ...)
+{
+  GVariant *child;
+  va_list ap;
+
+  if (format_string)
+    g_variant_flatten (dictionary);
+
+  child = g_variant_lookup_value (dictionary, key);
+
+  if (child == NULL)
+    return FALSE;
+
+  if (format_string)
+    {
+      va_start (ap, format_string);
+      g_variant_get_va (child, NULL, &format_string, &ap);
+      va_end (ap);
+    }
+
+  g_variant_unref (child);
+
+  return TRUE;
+}
+
 #define _gvariant_valist_c_
 #include "galiasdef.c"
diff --git a/glib/gvariant.h b/glib/gvariant.h
index bebe9b0..d8d7cba 100644
--- a/glib/gvariant.h
+++ b/glib/gvariant.h
@@ -100,9 +100,19 @@ gconstpointer                   g_variant_get_fixed                     (GVarian
 gconstpointer                   g_variant_get_fixed_array               (GVariant             *value,
                                                                          gsize                 elem_size,
                                                                          gsize                *length);
+gsize                           g_variant_n_children                    (GVariant             *value);
 GVariant                       *g_variant_get_child_value               (GVariant             *value,
                                                                          gsize                 index);
-gsize                           g_variant_n_children                    (GVariant             *value);
+void                            g_variant_get_child                     (GVariant             *value,
+                                                                         gint                  index,
+                                                                         const gchar          *format_string,
+                                                                         ...);
+GVariant                       *g_variant_lookup_value                  (GVariant             *dictionary,
+                                                                         const gchar          *key);
+gboolean                        g_variant_lookup                        (GVariant             *dictionary,
+                                                                         const gchar          *key,
+                                                                         const gchar          *format_string,
+                                                                         ...);
 
 /* GVariantIter */
 gsize                           g_variant_iter_init                     (GVariantIter         *iter,