[glib/wip/menuitem-api: 1/4] GVariant: add g_variant_check_format_string()

[Ryan Lortie <ryanl src gnome org>]

commit b502034d1628cae9ca2fef9c0feaf0634ccf15b5
Author: Ryan Lortie <desrt desrt ca>
Date:   Sat Aug 18 14:12:55 2012 -0400

    GVariant: add g_variant_check_format_string()
    
    For some time now people have been asking for a way to check for type
    compatibility between GVariant instances and format strings.  There are
    several APIs inside of GLib itself that would benefit from this.
    
    This patch introduces a way to do that.

 docs/reference/glib/glib-sections.txt |    1 +
 glib/glib.symbols                     |    1 +
 glib/gvariant.c                       |   66 +++++++++++++++++++++++++++++++++
 glib/gvariant.h                       |    4 +-
 4 files changed, 71 insertions(+), 1 deletions(-)
---
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index a7f0a65..b318a94 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -3057,6 +3057,7 @@ g_variant_classify
 GVariantClass
 
 <SUBSECTION>
+g_variant_check_format_string
 g_variant_get
 g_variant_get_va
 g_variant_new
diff --git a/glib/glib.symbols b/glib/glib.symbols
index 49c6442..ffcc679 100644
--- a/glib/glib.symbols
+++ b/glib/glib.symbols
@@ -1558,6 +1558,7 @@ g_variant_builder_end
 g_variant_builder_new
 g_variant_builder_unref
 g_variant_builder_ref
+g_variant_check_format_string
 g_variant_new_va
 g_variant_get_va
 g_variant_new
diff --git a/glib/gvariant.c b/glib/gvariant.c
index 5f2337c..6e948fe 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -3741,6 +3741,72 @@ g_variant_format_string_scan (const gchar  *string,
   return TRUE;
 }
 
+/**
+ * g_variant_check_format_string:
+ * @value: a #GVariant
+ * @format_string: a valid #GVariant format string
+ * @copy_only: %TRUE to ensure the format string makes deep copies
+ *
+ * Checks if calling g_variant_get() with @format_string on @value would
+ * be valid from a type-compatibility standpoint.  @format_string is
+ * assumed to be a valid format string (from a syntactic standpoint).
+ *
+ * If @copy_only is %TRUE then this function additionally checks that it
+ * would be safe to call g_variant_unref() on @value immediately after
+ * the call to g_variant_get() without invalidating the result.  This is
+ * only possible if deep copies are made (ie: there are no pointers to
+ * the data inside of the soon-to-be-freed #GVariant instance).
+ *
+ * This function is meant to be used by functions that wish to provide
+ * varargs accessors to #GVariant values of uncertain values (eg:
+ * g_variant_lookup() or g_menu_model_get_item_attribute()).
+ *
+ * Returns: %TRUE if @format_string is safe to use
+ *
+ * Since: 2.34
+ */
+gboolean
+g_variant_check_format_string (GVariant    *value,
+                               const gchar *format_string,
+                               gboolean     copy_only)
+{
+  const gchar *type_string;
+
+  /* Interesting factoid: assuming a format string is valid, it can be
+   * converted to a type string by removing all '@' '&' and '^'
+   * characters.
+   *
+   * Instead of doing that, we can just skip those characters when
+   * comparing it to the type string of @value.
+   *
+   * For the copy-only case we can just drop the '&' from the list of
+   * characters to skip over.  A '&' will never appear in a type string
+   * so we know that it won't be possible to return %TRUE if it is in a
+   * format string.
+   */
+  type_string = g_variant_get_type_string (value);
+
+  while (*type_string || *format_string)
+    {
+      /* We may have '^&ay' so we have to check for the '^' first.
+       */
+      if (*format_string == '^' || *format_string == '@')
+        format_string++;
+
+      /* Only accept '&' if copy_only is FALSE, as above */
+      if (!copy_only && *format_string == '&')
+        format_string++;
+
+      if (*format_string != *type_string)
+        return FALSE;
+
+      format_string++;
+      type_string++;
+    }
+
+  return TRUE;
+}
+
 /*< private >
  * g_variant_format_string_scan_type:
  * @string: a string that may be prefixed with a format string
diff --git a/glib/gvariant.h b/glib/gvariant.h
index d0cd857..3c92d21 100644
--- a/glib/gvariant.h
+++ b/glib/gvariant.h
@@ -265,7 +265,9 @@ void                            g_variant_get_va                        (GVarian
                                                                          const gchar          *format_string,
                                                                          const gchar         **endptr,
                                                                          va_list              *app);
-
+gboolean                        g_variant_check_format_string           (GVariant             *value,
+                                                                         const gchar          *format_string,
+                                                                         gboolean              copy_only);
 
 GVariant *                      g_variant_parse                         (const GVariantType   *type,
                                                                          const gchar          *text,