[json-glib] Add convenience accessors to JsonArray

[Emmanuele Bassi <ebassi src gnome org>]

commit e437ce609e333c5b8ede21174dfba032c1bbfb00
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Fri Apr 17 14:49:25 2009 +0100

    Add convenience accessors to JsonArray
    
    Like commit 5bb6ea91 did for JsonObject, we should add typed
    convenience accessors to JsonArray in order to cut down the
    amount of nodes needed when parsing and generating JSON data
    streams.
    
    As for JsonObject, the amount of types is small enough to avoid
    the combinatorial API explosion.
---
 doc/reference/json-glib-sections.txt |   22 ++-
 json-glib/json-array.c               |  386 ++++++++++++++++++++++++++++++++++
 json-glib/json-types.h               |   57 ++++--
 3 files changed, 447 insertions(+), 18 deletions(-)

diff --git a/doc/reference/json-glib-sections.txt b/doc/reference/json-glib-sections.txt
index b541b12..615654c 100644
--- a/doc/reference/json-glib-sections.txt
+++ b/doc/reference/json-glib-sections.txt
@@ -1,6 +1,6 @@
 <SECTION>
 <FILE>json-object</FILE>
-<TITLE>JsonObject</TITLE>
+<TITLE>JSON Object</TITLE>
 JsonObject
 json_object_new
 json_object_ref
@@ -40,7 +40,7 @@ json_object_get_type
 
 <SECTION>
 <FILE>json-array</FILE>
-<TITLE>JsonArray</TITLE>
+<TITLE>JSON Array</TITLE>
 JsonArray
 json_array_new
 json_array_sized_new
@@ -55,6 +55,22 @@ json_array_get_elements
 json_array_get_length
 json_array_remove_element
 
+<SUBSECTION>
+json_array_add_array_element
+json_array_get_array_element
+json_array_add_boolean_element
+json_array_get_boolean_element
+json_array_add_double_element
+json_array_get_double_element
+json_array_add_int_element
+json_array_get_int_element
+json_array_add_null_element
+json_array_get_null_element
+json_array_add_object_element
+json_array_get_object_element
+json_array_add_string_element
+json_array_get_string_element
+
 <SUBSECTION Private>
 JSON_TYPE_ARRAY
 json_array_get_type
@@ -62,7 +78,7 @@ json_array_get_type
 
 <SECTION>
 <FILE>json-node</FILE>
-<TITLE>JsonNode</TITLE>
+<TITLE>JSON Node</TITLE>
 JsonNodeType
 JSON_NODE_TYPE
 JsonNode
diff --git a/json-glib/json-array.c b/json-glib/json-array.c
index 4141b47..0b5d32a 100644
--- a/json-glib/json-array.c
+++ b/json-glib/json-array.c
@@ -231,6 +231,215 @@ json_array_get_element (JsonArray *array,
 }
 
 /**
+ * json_array_get_int_element:
+ * @array: a #JsonArray
+ * @index_: the index of the element to retrieve
+ *
+ * Conveniently retrieves the integer value of the element at @index_
+ * inside @array
+ *
+ * See also: json_array_get_element(), json_node_get_int()
+ *
+ * Return value: the integer value
+ *
+ * Since: 0.8
+ */
+gint
+json_array_get_int_element (JsonArray *array,
+                            guint      index_)
+{
+  JsonNode *node;
+
+  g_return_val_if_fail (array != NULL, 0);
+  g_return_val_if_fail (index_ < array->elements->len, 0);
+
+  node = g_ptr_array_index (array->elements, index_);
+  g_return_val_if_fail (node != NULL, 0);
+  g_return_val_if_fail (JSON_NODE_TYPE (node) == JSON_NODE_VALUE, 0);
+
+  return json_node_get_int (node);
+}
+
+/**
+ * json_array_get_double_element:
+ * @array: a #JsonArray
+ * @index_: the index of the element to retrieve
+ *
+ * Conveniently retrieves the floating point value of the element at
+ * @index_ inside @array
+ *
+ * See also: json_array_get_element(), json_node_get_double()
+ *
+ * Return value: the floating point value
+ *
+ * Since: 0.8
+ */
+gdouble
+json_array_get_double_element (JsonArray *array,
+                               guint      index_)
+{
+  JsonNode *node;
+
+  g_return_val_if_fail (array != NULL, 0.0);
+  g_return_val_if_fail (index_ < array->elements->len, 0.0);
+
+  node = g_ptr_array_index (array->elements, index_);
+  g_return_val_if_fail (node != NULL, 0.0);
+  g_return_val_if_fail (JSON_NODE_TYPE (node) == JSON_NODE_VALUE, 0.0);
+
+  return json_node_get_double (node);
+}
+
+/**
+ * json_array_get_boolean_element:
+ * @array: a #JsonArray
+ * @index_: the index of the element to retrieve
+ *
+ * Conveniently retrieves the boolean value of the element at @index_
+ * inside @array
+ *
+ * See also: json_array_get_element(), json_node_get_boolean()
+ *
+ * Return value: the integer value
+ *
+ * Since: 0.8
+ */
+gboolean
+json_array_get_boolean_element (JsonArray *array,
+                                guint      index_)
+{
+  JsonNode *node;
+
+  g_return_val_if_fail (array != NULL, FALSE);
+  g_return_val_if_fail (index_ < array->elements->len, FALSE);
+
+  node = g_ptr_array_index (array->elements, index_);
+  g_return_val_if_fail (node != NULL, FALSE);
+  g_return_val_if_fail (JSON_NODE_TYPE (node) == JSON_NODE_VALUE, FALSE);
+
+  return json_node_get_boolean (node);
+}
+
+/**
+ * json_array_get_string_element:
+ * @array: a #JsonArray
+ * @index_: the index of the element to retrieve
+ *
+ * Conveniently retrieves the string value of the element at @index_
+ * inside @array
+ *
+ * See also: json_array_get_element(), json_node_get_string()
+ *
+ * Return value: the string value; the returned string is owned by
+ *   the #JsonArray and should not be modified or freed
+ *
+ * Since: 0.8
+ */
+G_CONST_RETURN gchar *
+json_array_get_string_element (JsonArray *array,
+                               guint      index_)
+{
+  JsonNode *node;
+
+  g_return_val_if_fail (array != NULL, NULL);
+  g_return_val_if_fail (index_ < array->elements->len, NULL);
+
+  node = g_ptr_array_index (array->elements, index_);
+  g_return_val_if_fail (node != NULL, NULL);
+  g_return_val_if_fail (JSON_NODE_TYPE (node) == JSON_NODE_VALUE, NULL);
+
+  return json_node_get_string (node);
+}
+
+/**
+ * json_array_get_null_element:
+ * @array: a #JsonArray
+ * @index_: the index of the element to retrieve
+ *
+ * Conveniently retrieves whether the element at @index_ is set to null
+ *
+ * See also: json_array_get_element(), JSON_NODE_TYPE(), %JSON_NODE_NULL
+ *
+ * Return value: %TRUE if the element is null
+ *
+ * Since: 0.8
+ */
+gboolean
+json_array_get_null_element (JsonArray *array,
+                             guint      index_)
+{
+  JsonNode *node;
+
+  g_return_val_if_fail (array != NULL, FALSE);
+  g_return_val_if_fail (index_ < array->elements->len, FALSE);
+
+  node = g_ptr_array_index (array->elements, index_);
+  g_return_val_if_fail (node != NULL, FALSE);
+
+  return JSON_NODE_TYPE (node) == JSON_NODE_NULL;
+}
+
+/**
+ * json_array_get_array_element:
+ * @array: a #JsonArray
+ * @index_: the index of the element to retrieve
+ *
+ * Conveniently retrieves the array from the element at @index_
+ * inside @array
+ *
+ * See also: json_array_get_element(), json_node_get_array()
+ *
+ * Return value: the array
+ *
+ * Since: 0.8
+ */
+JsonArray *
+json_array_get_array_element (JsonArray *array,
+                              guint      index_)
+{
+  JsonNode *node;
+
+  g_return_val_if_fail (array != NULL, NULL);
+  g_return_val_if_fail (index_ < array->elements->len, NULL);
+
+  node = g_ptr_array_index (array->elements, index_);
+  g_return_val_if_fail (node != NULL, NULL);
+  g_return_val_if_fail (JSON_NODE_TYPE (node) == JSON_NODE_ARRAY, NULL);
+
+  return json_node_get_array (node);
+}
+
+/**
+ * json_array_get_object_element:
+ * @array: a #JsonArray
+ * @index_: the index of the element to retrieve
+ *
+ * Conveniently retrieves the object from the element at @index_
+ * inside @array
+ *
+ * See also: json_array_get_element(), json_node_get_object()
+ *
+ * Return value: the object
+ *
+ * Since: 0.8
+ */
+JsonObject *
+json_array_get_object_element (JsonArray *array,
+                               guint      index_)
+{
+  JsonNode *node;
+
+  g_return_val_if_fail (array != NULL, NULL);
+  g_return_val_if_fail (index_ < array->elements->len, NULL);
+
+  node = g_ptr_array_index (array->elements, index_);
+  g_return_val_if_fail (node != NULL, NULL);
+  g_return_val_if_fail (JSON_NODE_TYPE (node) == JSON_NODE_OBJECT, NULL);
+
+  return json_node_get_object (node);
+}
+
+/**
  * json_array_get_length:
  * @array: a #JsonArray
  *
@@ -265,6 +474,183 @@ json_array_add_element (JsonArray *array,
 }
 
 /**
+ * json_array_add_int_element:
+ * @array: a #JsonArray
+ * @value: an integer value
+ *
+ * Conveniently adds an integer @value into @array
+ *
+ * See also: json_array_add_element(), json_node_set_int()
+ *
+ * Since: 0.8
+ */
+void
+json_array_add_int_element (JsonArray *array,
+                            gint       value)
+{
+  JsonNode *node;
+
+  g_return_if_fail (array != NULL);
+
+  node = json_node_new (JSON_NODE_VALUE);
+  json_node_set_int (node, value);
+
+  g_ptr_array_add (array->elements, node);
+}
+
+/**
+ * json_array_add_double_element:
+ * @array: a #JsonArray
+ * @value: a floating point value
+ *
+ * Conveniently adds a floating point @value into @array
+ *
+ * See also: json_array_add_element(), json_node_set_double()
+ *
+ * Since: 0.8
+ */
+void
+json_array_add_double_element (JsonArray *array,
+                               gdouble    value)
+{
+  JsonNode *node;
+
+  g_return_if_fail (array != NULL);
+
+  node = json_node_new (JSON_NODE_VALUE);
+  json_node_set_double (node, value);
+
+  g_ptr_array_add (array->elements, node);
+}
+
+/**
+ * json_array_add_boolean_element:
+ * @array: a #JsonArray
+ * @value: a boolean value
+ *
+ * Conveniently adds a boolean @value into @array
+ *
+ * See also: json_array_add_element(), json_node_set_boolean()
+ *
+ * Since: 0.8
+ */
+void
+json_array_add_boolean_element (JsonArray *array,
+                                gboolean   value)
+{
+  JsonNode *node;
+
+  g_return_if_fail (array != NULL);
+
+  node = json_node_new (JSON_NODE_VALUE);
+  json_node_set_boolean (node, value);
+
+  g_ptr_array_add (array->elements, node);
+}
+
+/**
+ * json_array_add_string_element:
+ * @array: a #JsonArray
+ * @value: a string value
+ *
+ * Conveniently adds a string @value into @array
+ *
+ * See also: json_array_add_element(), json_node_set_string()
+ *
+ * Since: 0.8
+ */
+void
+json_array_add_string_element (JsonArray   *array,
+                               const gchar *value)
+{
+  JsonNode *node;
+
+  g_return_if_fail (array != NULL);
+  g_return_if_fail (value != NULL);
+
+  node = json_node_new (JSON_NODE_VALUE);
+  json_node_set_string (node, value);
+
+  g_ptr_array_add (array->elements, node);
+}
+
+/**
+ * json_array_add_null_element:
+ * @array: a #JsonArray
+ *
+ * Conveniently adds a null element into @array
+ *
+ * See also: json_array_add_element(), %JSON_NODE_NULL
+ *
+ * Since: 0.8
+ */
+void
+json_array_add_null_element (JsonArray *array)
+{
+  JsonNode *node;
+
+  g_return_if_fail (array != NULL);
+
+  node = json_node_new (JSON_NODE_NULL);
+
+  g_ptr_array_add (array->elements, node);
+}
+
+/**
+ * json_array_add_array_element:
+ * @array: a #JsonArray
+ * @value: a #JsonArray
+ *
+ * Conveniently adds an array into @array. The @array takes ownership
+ * of the newly added #JsonArray
+ *
+ * See also: json_array_add_element(), json_node_take_array()
+ *
+ * Since: 0.8
+ */
+void
+json_array_add_array_element (JsonArray *array,
+                              JsonArray *value)
+{
+  JsonNode *node;
+
+  g_return_if_fail (array != NULL);
+  g_return_if_fail (value != NULL);
+
+  node = json_node_new (JSON_NODE_ARRAY);
+  json_node_take_array (node, value);
+
+  g_ptr_array_add (array->elements, node);
+}
+
+/**
+ * json_array_add_object_element:
+ * @array: a #JsonArray
+ * @value: a #JsonObject
+ *
+ * Conveniently adds an object into @array. The @array takes ownership
+ * of the newly added #JsonObject
+ *
+ * See also: json_array_add_element(), json_node_take_object()
+ *
+ * Since: 0.8
+ */
+void
+json_array_add_object_element (JsonArray  *array,
+                               JsonObject *value)
+{
+  JsonNode *node;
+
+  g_return_if_fail (array != NULL);
+  g_return_if_fail (value != NULL);
+
+  node = json_node_new (JSON_NODE_OBJECT);
+  json_node_take_object (node, value);
+
+  g_ptr_array_add (array->elements, node);
+}
+
+/**
  * json_array_remove_element:
  * @array: a #JsonArray
  * @index_: the position of the element to be removed
diff --git a/json-glib/json-types.h b/json-glib/json-types.h
index 5b07de6..8d60a9d 100644
--- a/json-glib/json-types.h
+++ b/json-glib/json-types.h
@@ -196,21 +196,48 @@ void                  json_object_remove_member      (JsonObject  *object,
 GList *               json_object_get_values         (JsonObject  *object);
 guint                 json_object_get_size           (JsonObject  *object);
 
-GType                 json_array_get_type       (void) G_GNUC_CONST;
-JsonArray *           json_array_new            (void);
-JsonArray *           json_array_sized_new      (guint        n_elements);
-JsonArray *           json_array_ref            (JsonArray   *array);
-void                  json_array_unref          (JsonArray   *array);
-void                  json_array_add_element    (JsonArray   *array,
-                                                 JsonNode    *node);
-GList *               json_array_get_elements   (JsonArray   *array);
-JsonNode *            json_array_get_element    (JsonArray   *array,
-                                                 guint        index_);
-JsonNode *            json_array_dup_element    (JsonArray   *array,
-                                                 guint        index_);
-void                  json_array_remove_element (JsonArray   *array,
-                                                 guint        index_);
-guint                 json_array_get_length     (JsonArray   *array);
+GType                 json_array_get_type            (void) G_GNUC_CONST;
+JsonArray *           json_array_new                 (void);
+JsonArray *           json_array_sized_new           (guint        n_elements);
+JsonArray *           json_array_ref                 (JsonArray   *array);
+void                  json_array_unref               (JsonArray   *array);
+void                  json_array_add_element         (JsonArray   *array,
+                                                      JsonNode    *node);
+void                  json_array_add_int_element     (JsonArray   *array,
+                                                      gint         value);
+void                  json_array_add_double_element  (JsonArray   *array,
+                                                      gdouble      value);
+void                  json_array_add_boolean_element (JsonArray   *array,
+                                                      gboolean     value);
+void                  json_array_add_string_element  (JsonArray   *array,
+                                                      const gchar *value);
+void                  json_array_add_null_element    (JsonArray   *array);
+void                  json_array_add_array_element   (JsonArray   *array,
+                                                      JsonArray   *value);
+void                  json_array_add_object_element  (JsonArray   *array,
+                                                      JsonObject  *value);
+GList *               json_array_get_elements        (JsonArray   *array);
+JsonNode *            json_array_get_element         (JsonArray   *array,
+                                                      guint        index_);
+gint                  json_array_get_int_element     (JsonArray   *array,
+                                                      guint        index_);
+gdouble               json_array_get_double_element  (JsonArray   *array,
+                                                      guint        index_);
+gboolean              json_array_get_boolean_element (JsonArray   *array,
+                                                      guint        index_);
+G_CONST_RETURN gchar *json_array_get_string_element  (JsonArray   *array,
+                                                      guint        index_);
+gboolean              json_array_get_null_element    (JsonArray   *array,
+                                                      guint        index_);
+JsonArray *           json_array_get_array_element   (JsonArray   *array,
+                                                      guint        index_);
+JsonObject *          json_array_get_object_element  (JsonArray   *array,
+                                                      guint        index_);
+JsonNode *            json_array_dup_element         (JsonArray   *array,
+                                                      guint        index_);
+void                  json_array_remove_element      (JsonArray   *array,
+                                                      guint        index_);
+guint                 json_array_get_length          (JsonArray   *array);
 
 G_END_DECLS