[json-glib] node: Add typed initializers

[Emmanuele Bassi <ebassi src gnome org>]

commit 615538100a42063ca0b84b5bb9c8a6a046a89e0b
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sat Oct 27 11:44:30 2012 +0100

    node: Add typed initializers
    
    We should simplify the JsonNode API a bit, especially when it comes to
    initializing nodes. Instead of a two-step "new(<type>) followed by a
    set_<type>(value)" API, we can provide a "init_<type>(value)" API that
    can take any existing JsonNode and initialize it to the given type.
    
    This makes the JsonNode creation more concise and reliable; it also
    allows to implicitly re-initialize JsonNodes without requiring the user
    to de-allocate/re-allocate them first.

 doc/reference/json-glib-sections.txt |    9 +
 json-glib/json-glib.symbols          |    9 +
 json-glib/json-node.c                |  303 ++++++++++++++++++++++++++++++----
 json-glib/json-types.h               |   19 ++
 4 files changed, 306 insertions(+), 34 deletions(-)
---
diff --git a/doc/reference/json-glib-sections.txt b/doc/reference/json-glib-sections.txt
index b18ebe7..86876cf 100644
--- a/doc/reference/json-glib-sections.txt
+++ b/doc/reference/json-glib-sections.txt
@@ -91,6 +91,15 @@ JSON_NODE_HOLDS_VALUE
 JSON_NODE_HOLDS_OBJECT
 JSON_NODE_HOLDS_ARRAY
 JSON_NODE_HOLDS_NULL
+json_node_alloc
+json_node_init
+json_node_init_int
+json_node_init_double
+json_node_init_boolean
+json_node_init_string
+json_node_init_null
+json_node_init_object
+json_node_init_array
 json_node_new
 json_node_copy
 json_node_free
diff --git a/json-glib/json-glib.symbols b/json-glib/json-glib.symbols
index 93f3827..d5b08c4 100644
--- a/json-glib/json-glib.symbols
+++ b/json-glib/json-glib.symbols
@@ -68,6 +68,7 @@ json_gvariant_deserialize
 json_gvariant_deserialize_data
 json_gvariant_serialize
 json_gvariant_serialize_data
+json_node_alloc
 json_node_copy
 json_node_dup_array
 json_node_dup_object
@@ -84,6 +85,14 @@ json_node_get_string
 json_node_get_type
 json_node_get_value
 json_node_get_value_type
+json_node_init_array
+json_node_init_boolean
+json_node_init_double
+json_node_init_int
+json_node_init_null
+json_node_init_object
+json_node_init_string
+json_node_init
 json_node_is_null
 json_node_new
 json_node_set_array
diff --git a/json-glib/json-node.c b/json-glib/json-node.c
index c51ee7f..f2b5e69 100644
--- a/json-glib/json-node.c
+++ b/json-glib/json-node.c
@@ -89,25 +89,280 @@ json_node_get_value_type (JsonNode *node)
 }
 
 /**
+ * json_node_alloc:
+ *
+ * Allocates a new #JsonNode. Use json_node_init() and its variants
+ * to initialize the returned value.
+ *
+ * Return value: (transfer full): the newly allocated #JsonNode. Use
+ *   json_node_free() to free the resources allocated by this function
+ *
+ * Since: 0.16
+ */
+JsonNode *
+json_node_alloc (void)
+{
+  return g_slice_new0 (JsonNode);
+}
+
+static void
+json_node_unset (JsonNode *node)
+{
+  g_assert (node != NULL);
+
+  switch (node->type)
+    {
+    case JSON_NODE_OBJECT:
+      if (node->data.object)
+        json_object_unref (node->data.object);
+      break;
+
+    case JSON_NODE_ARRAY:
+      if (node->data.array)
+        json_array_unref (node->data.array);
+      break;
+
+    case JSON_NODE_VALUE:
+      if (node->data.value)
+        json_value_unref (node->data.value);
+      break;
+
+    case JSON_NODE_NULL:
+      break;
+    }
+}
+
+/**
+ * json_node_init:
+ * @node: the #JsonNode to initialize
+ * @type: the type of JSON node to initialize @node to
+ *
+ * Initializes a @node to a specific @type.
+ *
+ * If the node has already been initialized once, it will be reset to
+ * the given type, and any data contained will be cleared.
+ *
+ * Return value: (transfer none): the initialized #JsonNode
+ *
+ * Since: 0.16
+ */
+JsonNode *
+json_node_init (JsonNode *node,
+                JsonNodeType type)
+{
+  g_return_val_if_fail (type >= JSON_NODE_OBJECT &&
+                        type <= JSON_NODE_NULL, NULL);
+
+  json_node_unset (node);
+
+  node->type = type;
+
+  return node;
+}
+
+/**
+ * json_node_init_object:
+ * @node: the #JsonNode to initialize
+ * @object: (allow-none): the #JsonObject to initialize @node with, or %NULL
+ *
+ * Initializes @node to %JSON_NODE_OBJECT and sets @object into it.
+ *
+ * This function will take a reference on @object.
+ *
+ * If the node has already been initialized once, it will be reset to
+ * the given type, and any data contained will be cleared.
+ *
+ * Return value: the initialized #JsonNode
+ *
+ * Since: 0.16
+ */
+JsonNode *
+json_node_init_object (JsonNode   *node,
+                       JsonObject *object)
+{
+  g_return_val_if_fail (node != NULL, NULL);
+  
+  json_node_init (node, JSON_NODE_OBJECT);
+  json_node_set_object (node, object);
+
+  return node;
+}
+
+/**
+ * json_node_init_array:
+ * @node: the #JsonNode to initialize
+ * @array: (allow-none): the #JsonArray to initialize @node with, or %NULL
+ *
+ * Initializes @node to %JSON_NODE_ARRAY and sets @array into it.
+ *
+ * This function will take a reference on @array.
+ *
+ * If the node has already been initialized once, it will be reset to
+ * the given type, and any data contained will be cleared.
+ *
+ * Return value: the initialized #JsonNode
+ *
+ * Since: 0.16
+ */
+JsonNode *
+json_node_init_array (JsonNode  *node,
+                      JsonArray *array)
+{
+  g_return_val_if_fail (node != NULL, NULL);
+
+  json_node_init (node, JSON_NODE_ARRAY);
+  json_node_set_array (node, array);
+
+  return node;
+}
+
+/**
+ * json_node_init_int:
+ * @node: the #JsonNode to initialize
+ * @value: an integer
+ *
+ * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ *
+ * If the node has already been initialized once, it will be reset to
+ * the given type, and any data contained will be cleared.
+ *
+ * Return value: the initialized #JsonNode
+ *
+ * Since: 0.16
+ */
+JsonNode *
+json_node_init_int (JsonNode *node,
+                    gint64    value)
+{
+  g_return_val_if_fail (node != NULL, NULL);
+
+  json_node_init (node, JSON_NODE_VALUE);
+  json_node_set_int (node, value);
+
+  return node;
+}
+
+/**
+ * json_node_init_double:
+ * @node: the #JsonNode to initialize
+ * @value: a floating point value
+ *
+ * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ *
+ * If the node has already been initialized once, it will be reset to
+ * the given type, and any data contained will be cleared.
+ *
+ * Return value: the initialized #JsonNode
+ *
+ * Since: 0.16
+ */
+JsonNode *
+json_node_init_double (JsonNode *node,
+                       gdouble   value)
+{
+  g_return_val_if_fail (node != NULL, NULL);
+
+  json_node_init (node, JSON_NODE_VALUE);
+  json_node_set_double (node, value);
+
+  return node;
+}
+
+/**
+ * json_node_init_boolean:
+ * @node: the #JsonNode to initialize
+ * @value: a boolean value
+ *
+ * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ *
+ * If the node has already been initialized once, it will be reset to
+ * the given type, and any data contained will be cleared.
+ *
+ * Return value: the initialized #JsonNode
+ *
+ * Since: 0.16
+ */
+JsonNode *
+json_node_init_boolean (JsonNode *node,
+                        gboolean  value)
+{
+  g_return_val_if_fail (node != NULL, NULL);
+
+  json_node_init (node, JSON_NODE_VALUE);
+  json_node_set_boolean (node, value);
+
+  return node;
+}
+
+/**
+ * json_node_init_string:
+ * @node: the #JsonNode to initialize
+ * @value: (allow-none): a string value
+ *
+ * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ *
+ * If the node has already been initialized once, it will be reset to
+ * the given type, and any data contained will be cleared.
+ *
+ * Return value: the initialized #JsonNode
+ *
+ * Since: 0.16
+ */
+JsonNode *
+json_node_init_string (JsonNode   *node,
+                       const char *value)
+{
+  g_return_val_if_fail (node != NULL, NULL);
+
+  json_node_init (node, JSON_NODE_VALUE);
+  json_node_set_string (node, value);
+
+  return node;
+}
+
+/**
+ * json_node_init_null:
+ * @node: the #JsonNode to initialize
+ *
+ * Initializes @node to %JSON_NODE_NULL.
+ *
+ * If the node has already been initialized once, it will be reset to
+ * the given type, and any data contained will be cleared.
+ *
+ * Return value: the initialized #JsonNode
+ *
+ * Since: 0.16
+ */
+JsonNode *
+json_node_init_null (JsonNode *node)
+{
+  g_return_val_if_fail (node != NULL, NULL);
+
+  return json_node_init (node, JSON_NODE_NULL);
+}
+
+/**
  * json_node_new:
  * @type: a #JsonNodeType
  *
  * Creates a new #JsonNode of @type.
  *
+ * This is a convenience function for json_node_alloc() and json_node_init(),
+ * and it's the equivalent of:
+ *
+ * |[
+ *   return json_node_init (json_node_alloc (), type);
+ * ]|
+ *
  * Return value: the newly created #JsonNode
  */
 JsonNode *
 json_node_new (JsonNodeType type)
 {
-  JsonNode *data;
-
   g_return_val_if_fail (type >= JSON_NODE_OBJECT &&
                         type <= JSON_NODE_NULL, NULL);
 
-  data = g_slice_new0 (JsonNode);
-  data->type = type;
-
-  return data;
+  return json_node_init (json_node_alloc (), type);
 }
 
 /**
@@ -156,7 +411,7 @@ json_node_copy (JsonNode *node)
 
 /**
  * json_node_set_object:
- * @node: a #JsonNode
+ * @node: a #JsonNode initialized to %JSON_NODE_OBJECT
  * @object: a #JsonObject
  *
  * Sets @objects inside @node. The reference count of @object is increased.
@@ -168,7 +423,7 @@ json_node_set_object (JsonNode   *node,
   g_return_if_fail (node != NULL);
   g_return_if_fail (JSON_NODE_TYPE (node) == JSON_NODE_OBJECT);
 
-  if (node->data.object)
+  if (node->data.object != NULL)
     json_object_unref (node->data.object);
 
   if (object)
@@ -179,7 +434,7 @@ json_node_set_object (JsonNode   *node,
 
 /**
  * json_node_take_object:
- * @node: a #JsonNode
+ * @node: a #JsonNode initialized to %JSON_NODE_OBJECT
  * @object: (transfer full): a #JsonObject
  *
  * Sets @object inside @node. The reference count of @object is not increased.
@@ -241,7 +496,7 @@ json_node_dup_object (JsonNode *node)
 
 /**
  * json_node_set_array:
- * @node: a #JsonNode
+ * @node: a #JsonNode initialized to %JSON_NODE_ARRAY
  * @array: a #JsonArray
  *
  * Sets @array inside @node and increases the #JsonArray reference count
@@ -264,7 +519,7 @@ json_node_set_array (JsonNode  *node,
 
 /**
  * json_node_take_array:
- * @node: a #JsonNode
+ * @node: a #JsonNode initialized to %JSON_NODE_ARRAY
  * @array: (transfer full): a #JsonArray
  *
  * Sets @array into @node without increasing the #JsonArray reference count.
@@ -369,7 +624,7 @@ json_node_get_value (JsonNode *node,
 
 /**
  * json_node_set_value:
- * @node: a #JsonNode
+ * @node: a #JsonNode initialized to %JSON_NODE_VALUE
  * @value: the #GValue to set
  *
  * Sets @value inside @node. The passed #GValue is copied into the #JsonNode
@@ -436,27 +691,7 @@ json_node_free (JsonNode *node)
 {
   if (G_LIKELY (node))
     {
-      switch (node->type)
-        {
-        case JSON_NODE_OBJECT:
-          if (node->data.object)
-            json_object_unref (node->data.object);
-          break;
-
-        case JSON_NODE_ARRAY:
-          if (node->data.array)
-            json_array_unref (node->data.array);
-          break;
-
-        case JSON_NODE_VALUE:
-          if (node->data.value)
-            json_value_unref (node->data.value);
-          break;
-
-        case JSON_NODE_NULL:
-          break;
-        }
-
+      json_node_unset (node);
       g_slice_free (JsonNode, node);
     }
 }
@@ -552,7 +787,7 @@ json_node_get_parent (JsonNode *node)
 
 /**
  * json_node_set_string:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a #JsonNode initialized to %JSON_NODE_VALUE
  * @value: a string value
  *
  * Sets @value as the string content of the @node, replacing any existing
diff --git a/json-glib/json-types.h b/json-glib/json-types.h
index db9571e..3f7ff52 100644
--- a/json-glib/json-types.h
+++ b/json-glib/json-types.h
@@ -185,8 +185,27 @@ typedef void (* JsonArrayForeach) (JsonArray  *array,
  */
 GType                 json_node_get_type        (void) G_GNUC_CONST;
 JsonNode *            json_node_new             (JsonNodeType  type);
+
+JsonNode *            json_node_alloc           (void);
+JsonNode *            json_node_init            (JsonNode     *node,
+                                                 JsonNodeType  type);
+JsonNode *            json_node_init_object     (JsonNode     *node,
+                                                 JsonObject   *object);
+JsonNode *            json_node_init_array      (JsonNode     *node,
+                                                 JsonArray    *array);
+JsonNode *            json_node_init_int        (JsonNode     *node,
+                                                 gint64        value);
+JsonNode *            json_node_init_double     (JsonNode     *node,
+                                                 gdouble       value);
+JsonNode *            json_node_init_boolean    (JsonNode     *node,
+                                                 gboolean      value);
+JsonNode *            json_node_init_string     (JsonNode     *node,
+                                                 const char   *value);
+JsonNode *            json_node_init_null       (JsonNode     *node);
+
 JsonNode *            json_node_copy            (JsonNode     *node);
 void                  json_node_free            (JsonNode     *node);
+
 JsonNodeType          json_node_get_node_type   (JsonNode     *node);
 GType                 json_node_get_value_type  (JsonNode     *node);
 void                  json_node_set_parent      (JsonNode     *node,