[glib/gsettings] change GVariant parser to new-style API, document

[Ryan Lortie <ryanl src gnome org>]

commit 0847dfc4fb9d9ac0b6beeb9ff1b34d2af0fafe67
Author: Ryan Lortie <desrt desrt ca>
Date:   Thu Aug 27 22:06:47 2009 -0400

    change GVariant parser to new-style API, document

 glib/gvariant-parser.c |   78 ++++++++++++++++++++++++++++++++++++++---------
 glib/gvariant.h        |    5 ++-
 2 files changed, 66 insertions(+), 17 deletions(-)
---
diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c
index 1d657ea..be19cf0 100644
--- a/glib/gvariant-parser.c
+++ b/glib/gvariant-parser.c
@@ -2019,9 +2019,47 @@ parse (TokenStream *stream,
   return result;
 }
 
+/**
+ * g_variant_parse_full:
+ * @text: a string containing a GVariant in text form
+ * @limit: a pointer to the end of @text, or %NULL
+ * @endptr: a location to store the end pointer, or %NULL
+ * @type: a #GVariantType, or %NULL
+ * @error: an #GVariantParseError, or %NULL
+ * @Returns: a floating #GVariant, or %NULL
+ *
+ * Parses a #GVariant from a text representation.  This is the
+ * generalised form of g_variant_parse().  See that call for a simpler
+ * interface.
+ *
+ * A single #GVariant is parsed from the content of @text.
+ *
+ * The memory at @limit will never be accessed and the parser behaves as
+ * if the character at @limit is the nul terminator.  This has the
+ * effect of bounding @text.
+ *
+ * If @endptr is non-%NULL then @text is permitted to contain data
+ * following the value that this function parses and @endptr will be
+ * updated to point to the first character past the end of the text
+ * parsed by this function.  If @endptr is %NULL and there is extra data
+ * then an error is returned.
+ *
+ * If @type is non-%NULL then the value will be parsed to have that
+ * type.  This may result in additional parse errors (in the case that
+ * the parsed value doesn't fit the type) but may also result in fewer
+ * errors (in the case that the type would have been ambiguous, such as
+ * with empty arrays).
+ *
+ * In the event that the parsing is successful, the resulting #GVariant
+ * is returned.
+ *
+ * In case of any error, %NULL will be returned.  If @error is non-%NULL
+ * then it will be set to reflect the error that occured.
+ **/
 GVariant *
-g_variant_parse_full (const gchar        **text,
-                      const gchar         *end,
+g_variant_parse_full (const gchar         *text,
+                      const gchar         *limit,
+                      const gchar        **endptr,
                       const GVariantType  *type,
                       GVariantParseError  *error)
 {
@@ -2030,17 +2068,35 @@ g_variant_parse_full (const gchar        **text,
   AST *ast;
 
   g_return_val_if_fail (text != NULL, NULL);
-  g_return_val_if_fail (*text == end || *text != NULL, NULL);
+  g_return_val_if_fail (text == limit || text != NULL, NULL);
 
-  stream.stream = *text;
-  stream.end = end;
+  stream.stream = text;
+  stream.end = limit;
 
   if ((ast = parse (&stream, NULL)))
     {
       result = ast_resolve (ast, &stream.error);
 
       if (result != NULL)
-        *text = stream.stream;
+        {
+          if (endptr == NULL)
+            {
+              while (g_ascii_isspace (*text))
+                text++;
+
+              if (*text)
+                {
+                  set_error (&stream.error, text, text,
+                             "trailing text after value");
+                  g_variant_ref_sink (result);
+                  g_variant_unref (result);
+
+                  result = NULL;
+                }
+            }
+          else
+            *endptr = stream.stream;
+        }
 
       ast_free (ast);
     }
@@ -2120,15 +2176,7 @@ g_variant_parse (const gchar         *text,
   else
     end = NULL;
 
-  if ((result = g_variant_parse_full (&text, end, type, &parse_error)))
-    {
-      while (g_ascii_isspace (*text))
-        text++;
-
-      if (*text)
-        g_set_error (error, 0, 0, "%s", "trailing text after value");
-    }
-  else
+  if (!(result = g_variant_parse_full (text, end, NULL, type, &parse_error)))
     {
       g_set_error (error, 0, 0, "%s", parse_error.error);
       g_free (parse_error.error);
diff --git a/glib/gvariant.h b/glib/gvariant.h
index 51980e2..c5e7121 100644
--- a/glib/gvariant.h
+++ b/glib/gvariant.h
@@ -173,8 +173,9 @@ GVariant *                      g_variant_parsef                        (const g
                                                                          ...);
 GVariant *                      g_variant_parsef_va                     (const gchar          *format,
                                                                          va_list              *app);
-GVariant *                      g_variant_parse_full                    (const gchar         **text,
-                                                                         const gchar          *end,
+GVariant *                      g_variant_parse_full                    (const gchar          *text,
+                                                                         const gchar          *limit,
+                                                                         const gchar         **endptr,
                                                                          const GVariantType   *type,
                                                                          GVariantParseError   *error);