![]() |
![]() |
![]() |
JSON-GLib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
#include <json-glib/json-glib.h> enum JsonNodeType; JsonNode; #define JSON_NODE_TYPE (node) #define JSON_NODE_HOLDS (node, t) #define JSON_NODE_HOLDS_VALUE (node) #define JSON_NODE_HOLDS_OBJECT (node) #define JSON_NODE_HOLDS_ARRAY (node) #define JSON_NODE_HOLDS_NULL (node) JsonNode * json_node_alloc (void
); JsonNode * json_node_init (JsonNode *node
,JsonNodeType type
); 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_init_object (JsonNode *node
,JsonObject *object
); JsonNode * json_node_init_array (JsonNode *node
,JsonArray *array
); JsonNode * json_node_new (JsonNodeType type
); JsonNode * json_node_copy (JsonNode *node
); void json_node_free (JsonNode *node
); JsonNode * json_node_ref (JsonNode *node
); void json_node_unref (JsonNode *node
); gboolean json_node_is_immutable (JsonNode *node
); void json_node_seal (JsonNode *node
); guint json_node_hash (gconstpointer key
); gboolean json_node_equal (gconstpointer a
,gconstpointer b
); void json_node_set_array (JsonNode *node
,JsonArray *array
); void json_node_take_array (JsonNode *node
,JsonArray *array
); JsonArray * json_node_get_array (JsonNode *node
); JsonArray * json_node_dup_array (JsonNode *node
); void json_node_set_object (JsonNode *node
,JsonObject *object
); void json_node_take_object (JsonNode *node
,JsonObject *object
); JsonObject * json_node_get_object (JsonNode *node
); JsonObject * json_node_dup_object (JsonNode *node
); void json_node_set_value (JsonNode *node
,const GValue *value
); void json_node_get_value (JsonNode *node
,GValue *value
); void json_node_set_boolean (JsonNode *node
,gboolean value
); gboolean json_node_get_boolean (JsonNode *node
); void json_node_set_double (JsonNode *node
,gdouble value
); gdouble json_node_get_double (JsonNode *node
); void json_node_set_int (JsonNode *node
,gint64 value
); gint64 json_node_get_int (JsonNode *node
); void json_node_set_string (JsonNode *node
,const gchar *value
); const gchar * json_node_get_string (JsonNode *node
); gchar * json_node_dup_string (JsonNode *node
); void json_node_set_parent (JsonNode *node
,JsonNode *parent
); JsonNode * json_node_get_parent (JsonNode *node
); const gchar * json_node_type_name (JsonNode *node
); GType json_node_get_value_type (JsonNode *node
); JsonNodeType json_node_get_node_type (JsonNode *node
); gboolean json_node_is_null (JsonNode *node
); guint json_string_hash (gconstpointer key
); gboolean json_string_equal (gconstpointer a
,gconstpointer b
); gint json_string_compare (gconstpointer a
,gconstpointer b
);
A JsonNode is a generic container of elements inside a JSON stream. It can contain fundamental types (integers, booleans, floating point numbers, strings) and complex types (arrays and objects).
When parsing a JSON data stream you extract the root node and walk
the node tree by retrieving the type of data contained inside the
node with the JSON_NODE_TYPE
macro. If the node contains a fundamental
type you can retrieve a copy of the GValue holding it with the
json_node_get_value()
function, and then use the GValue API to extract
the data; if the node contains a complex type you can retrieve the
JsonObject or the JsonArray using json_node_get_object()
or
json_node_get_array()
respectively, and then retrieve the nodes
they contain.
A JsonNode may be marked as immutable using json_node_seal()
. This marks the
node and all its descendents as read-only, and means that subsequent calls to
setter functions (such as json_node_set_array()
) on them will abort as a
programmer error. By marking a node tree as immutable, it may be referenced
in multiple places and its hash value cached for fast lookups, without the
possibility of a value deep within the tree changing and affecting hash
values. Immutable JsonNodes may be passed to functions which retain a
reference to them without needing to take a copy.
JsonNode supports two types of memory management: alloc/free semantics, and
ref/unref semantics. The two may be mixed to a limited extent: nodes may be
allocated (which gives them a reference count of 1), referenced zero or more
times, unreferenced exactly that number of times (using json_node_unref()
),
then either unreferenced exactly once more or freed (using json_node_free()
)
to destroy them. json_node_free()
must not be used when a node might have a
reference count not equal to 1. To this end, json-glib uses json_node_copy()
and json_node_unref()
internally.
typedef enum { JSON_NODE_OBJECT, JSON_NODE_ARRAY, JSON_NODE_VALUE, JSON_NODE_NULL } JsonNodeType;
Indicates the content of a JsonNode.
The node contains a JsonObject | |
The node contains a JsonArray | |
The node contains a fundamental type | |
Special type, for nodes containing null |
typedef struct _JsonNode JsonNode;
A generic container of JSON data types. The contents of the JsonNode structure are private and should only be accessed via the provided functions and never directly.
#define JSON_NODE_TYPE(node) (json_node_get_node_type ((node)))
Evaluates to the JsonNodeType contained by node
|
a JsonNode |
#define JSON_NODE_HOLDS(node,t) (json_node_get_node_type ((node)) == (t))
Evaluates to TRUE
if the node
holds type t
|
a JsonNode |
|
a JsonNodeType |
Since 0.10
#define JSON_NODE_HOLDS_VALUE(node) (JSON_NODE_HOLDS ((node), JSON_NODE_VALUE))
Evaluates to TRUE
if node
holds a JSON_NODE_VALUE
|
a JsonNode |
Since 0.10
#define JSON_NODE_HOLDS_OBJECT(node) (JSON_NODE_HOLDS ((node), JSON_NODE_OBJECT))
Evaluates to TRUE
if node
holds a JSON_NODE_OBJECT
|
a JsonNode |
Since 0.10
#define JSON_NODE_HOLDS_ARRAY(node) (JSON_NODE_HOLDS ((node), JSON_NODE_ARRAY))
Evaluates to TRUE
if node
holds a JSON_NODE_ARRAY
|
a JsonNode |
Since 0.10
#define JSON_NODE_HOLDS_NULL(node) (JSON_NODE_HOLDS ((node), JSON_NODE_NULL))
Evaluates to TRUE
if node
holds a JSON_NODE_NULL
|
a JsonNode |
Since 0.10
JsonNode * json_node_alloc (void
);
Allocates a new JsonNode. Use json_node_init()
and its variants
to initialize the returned value.
Returns : |
the newly allocated JsonNode. Use
json_node_free() to free the resources allocated by this function. [transfer full]
|
Since 0.16
JsonNode * json_node_init (JsonNode *node
,JsonNodeType type
);
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.
|
the JsonNode to initialize |
|
the type of JSON node to initialize node to |
Returns : |
the initialized JsonNode. [transfer none] |
Since 0.16
JsonNode * json_node_init_int (JsonNode *node
,gint64 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.
|
the JsonNode to initialize |
|
an integer |
Returns : |
the initialized JsonNode. [transfer none] |
Since 0.16
JsonNode * json_node_init_double (JsonNode *node
,gdouble 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.
|
the JsonNode to initialize |
|
a floating point value |
Returns : |
the initialized JsonNode. [transfer none] |
Since 0.16
JsonNode * json_node_init_boolean (JsonNode *node
,gboolean 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.
|
the JsonNode to initialize |
|
a boolean value |
Returns : |
the initialized JsonNode. [transfer none] |
Since 0.16
JsonNode * json_node_init_string (JsonNode *node
,const char *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.
|
the JsonNode to initialize |
|
a string value. [allow-none] |
Returns : |
the initialized JsonNode. [transfer none] |
Since 0.16
JsonNode * json_node_init_null (JsonNode *node
);
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.
Since 0.16
JsonNode * json_node_init_object (JsonNode *node
,JsonObject *object
);
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.
|
the JsonNode to initialize |
|
the JsonObject to initialize node with, or NULL . [allow-none]
|
Returns : |
the initialized JsonNode. [transfer none] |
Since 0.16
JsonNode * json_node_init_array (JsonNode *node
,JsonArray *array
);
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.
|
the JsonNode to initialize |
|
the JsonArray to initialize node with, or NULL . [allow-none]
|
Returns : |
the initialized JsonNode. [transfer none] |
Since 0.16
JsonNode * json_node_new (JsonNodeType type
);
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:
1 |
json_node_init (json_node_alloc (), type); |
|
a JsonNodeType |
Returns : |
the newly created JsonNode. [transfer full] |
JsonNode * json_node_copy (JsonNode *node
);
Copies node
. If the node contains complex data types, their reference
counts are increased, regardless of whether the node is mutable or
immutable.
The copy will be immutable if, and only if, node
is immutable. However,
there should be no need to copy an immutable node.
void json_node_free (JsonNode *node
);
Frees the resources allocated by node
.
|
a JsonNode |
JsonNode * json_node_ref (JsonNode *node
);
Increment the reference count of node
.
|
a JsonNode |
Returns : |
a pointer to node . [transfer full]
|
Since 1.2
void json_node_unref (JsonNode *node
);
Decrement the reference count of node
. If it reaches zero, the node is
freed.
|
a JsonNode. [transfer full] |
Since 1.2
gboolean json_node_is_immutable (JsonNode *node
);
Check whether the given node
has been marked as immutable by calling
json_node_seal()
on it.
|
a JsonNode |
Returns : |
TRUE if the node is immutable |
Since 1.2
void json_node_seal (JsonNode *node
);
Seals the JsonNode, making it immutable to further changes. In order to be
sealed, the node
must have a type and value set. The value will be
recursively sealed — if the node holds an object, that JsonObject will be
sealed, etc.
If the node
is already immutable, this is a no-op.
|
a JsonNode |
Since 1.2
guint json_node_hash (gconstpointer key
);
Calculate a hash value for the given key
(a JsonNode).
The hash is calculated over the node and its value, recursively. If the node is immutable, this is a fast operation; otherwise, it scales proportionally with the size of the node’s value (for example, with the number of members in the JsonObject if this node contains an object).
|
a JSON node to hash. [type JsonNode] |
Returns : |
hash value for key
|
Since 1.2
gboolean json_node_equal (gconstpointer a
,gconstpointer b
);
Check whether a
and b
are equal JsonNodes, meaning they have the same
type and same values (checked recursively). Note that integer values are
compared numerically, ignoring type, so a double value 4.0 is equal to the
integer value 4.
|
a JSON node. [type JsonNode] |
|
another JSON node. [type JsonNode] |
Returns : |
TRUE if a and b are equal; FALSE otherwise |
Since 1.2
void json_node_set_array (JsonNode *node
,JsonArray *array
);
Sets array
inside node
and increases the JsonArray reference count.
It is an error to call this on an immutable node.
|
a JsonNode initialized to JSON_NODE_ARRAY
|
|
a JsonArray |
void json_node_take_array (JsonNode *node
,JsonArray *array
);
Sets array
into node
without increasing the JsonArray reference count.
It is an error to call this on an immutable node.
|
a JsonNode initialized to JSON_NODE_ARRAY
|
|
a JsonArray. [transfer full] |
JsonArray * json_node_get_array (JsonNode *node
);
Retrieves the JsonArray stored inside a JsonNode. If the node does not
hold an array value, NULL
is returned.
JsonArray * json_node_dup_array (JsonNode *node
);
Retrieves the JsonArray stored inside a JsonNode and returns it
with its reference count increased by one. If the node does not hold an
array value, NULL
is returned.
void json_node_set_object (JsonNode *node
,JsonObject *object
);
Sets objects
inside node
. The reference count of object
is increased.
If object
is NULL
, the node’s existing object is cleared.
It is an error to call this on an immutable node.
|
a JsonNode initialized to JSON_NODE_OBJECT
|
|
a JsonObject. [nullable] |
void json_node_take_object (JsonNode *node
,JsonObject *object
);
Sets object
inside node
. The reference count of object
is not increased.
It is an error to call this on an immutable node.
|
a JsonNode initialized to JSON_NODE_OBJECT
|
|
a JsonObject. [transfer full] |
JsonObject * json_node_get_object (JsonNode *node
);
Retrieves the JsonObject stored inside a JsonNode. If the node does not
hold an object value, NULL
is returned.
|
a JsonNode |
Returns : |
the JsonObject. [transfer none][nullable] |
JsonObject * json_node_dup_object (JsonNode *node
);
Retrieves the JsonObject inside node
. The reference count of
the returned object is increased. If the node does not hold an object value,
NULL
is returned.
|
a JsonNode |
Returns : |
the JsonObject. [transfer full][nullable] |
void json_node_set_value (JsonNode *node
,const GValue *value
);
Sets value
inside node
. The passed GValue is copied into the JsonNode.
It is an error to call this on an immutable node.
|
a JsonNode initialized to JSON_NODE_VALUE
|
|
the GValue to set |
void json_node_get_value (JsonNode *node
,GValue *value
);
Retrieves a value from a JsonNode and copies into value
. When done
using it, call g_value_unset()
on the GValue. If the node does not hold a
scalar value, value
is not modified.
|
a JsonNode |
|
return location for an uninitialized value. [out caller-allocates] |
void json_node_set_boolean (JsonNode *node
,gboolean value
);
Sets value
as the boolean content of the node
, replacing any existing
content.
It is an error to call this on an immutable node.
|
a JsonNode of type JSON_NODE_VALUE
|
|
a boolean value |
gboolean json_node_get_boolean (JsonNode *node
);
Gets the boolean value stored inside a JsonNode. If the node holds an
integer or double value which is zero, FALSE
is returned; otherwise TRUE
is returned. If the node holds a JSON_NODE_NULL
value or a value of another
non-boolean type, FALSE
is returned.
|
a JsonNode of type JSON_NODE_VALUE
|
Returns : |
a boolean value. |
void json_node_set_double (JsonNode *node
,gdouble value
);
Sets value
as the double content of the node
, replacing any existing
content.
It is an error to call this on an immutable node.
|
a JsonNode of type JSON_NODE_VALUE
|
|
a double value |
gdouble json_node_get_double (JsonNode *node
);
Gets the double value stored inside a JsonNode. If the node holds an integer
value, it is returned as a double. If the node holds a FALSE
boolean value,
`0.0` is returned; otherwise a non-zero double is returned. If the node holds
a JSON_NODE_NULL
value or a value of another non-double type, `0.0` is
returned.
|
a JsonNode of type JSON_NODE_VALUE
|
Returns : |
a double value. |
void json_node_set_int (JsonNode *node
,gint64 value
);
Sets value
as the integer content of the node
, replacing any existing
content.
It is an error to call this on an immutable node.
|
a JsonNode of type JSON_NODE_VALUE
|
|
an integer value |
gint64 json_node_get_int (JsonNode *node
);
Gets the integer value stored inside a JsonNode. If the node holds a double
value, its integer component is returned. If the node holds a FALSE
boolean
value, `0` is returned; otherwise a non-zero integer is returned. If the
node holds a JSON_NODE_NULL
value or a value of another non-integer type,
`0` is returned.
|
a JsonNode of type JSON_NODE_VALUE
|
Returns : |
an integer value. |
void json_node_set_string (JsonNode *node
,const gchar *value
);
Sets value
as the string content of the node
, replacing any existing
content.
It is an error to call this on an immutable node.
|
a JsonNode initialized to JSON_NODE_VALUE
|
|
a string value |
const gchar * json_node_get_string (JsonNode *node
);
Gets the string value stored inside a JsonNode. If the node does not hold a
string value, NULL
is returned.
|
a JsonNode of type JSON_NODE_VALUE
|
Returns : |
a string value. [nullable] |
gchar * json_node_dup_string (JsonNode *node
);
Gets a copy of the string value stored inside a JsonNode. If the node does
not hold a string value, NULL
is returned.
|
a JsonNode of type JSON_NODE_VALUE
|
Returns : |
a newly allocated string
containing a copy of the JsonNode contents. Use g_free() to free the
allocated resources. [transfer full][nullable]
|
void json_node_set_parent (JsonNode *node
,JsonNode *parent
);
Sets the parent JsonNode of node
.
It is an error to call this with an immutable parent
. node
may be
immutable.
Since 0.8
JsonNode * json_node_get_parent (JsonNode *node
);
Retrieves the parent JsonNode of node
.
|
a JsonNode |
Returns : |
the parent node, or NULL if node
is the root node. [transfer none][nullable]
|
const gchar * json_node_type_name (JsonNode *node
);
Retrieves the user readable name of the data type contained by node
.
|
a JsonNode |
Returns : |
a string containing the name of the type. The returned string is owned by the node and should never be modified or freed |
GType json_node_get_value_type (JsonNode *node
);
Returns the GType of the payload of the node.
|
a JsonNode |
Returns : |
a GType for the payload. |
Since 0.4
JsonNodeType json_node_get_node_type (JsonNode *node
);
Retrieves the JsonNodeType of node
|
a JsonNode |
Returns : |
the type of the node |
Since 0.8
gboolean json_node_is_null (JsonNode *node
);
Checks whether node
is a JSON_NODE_NULL
.
A JSON_NODE_NULL
node is not the same as a NULL
JsonNode; a
JSON_NODE_NULL
represents a 'null' value in the JSON tree.
|
a JsonNode |
Returns : |
TRUE if the node is null |
Since 0.8
guint json_string_hash (gconstpointer key
);
Calculate a hash value for the given key
(a UTF-8 JSON string).
Note: Member names are compared byte-wise, without applying any Unicode decomposition or normalisation. This is not explicitly mentioned in the JSON standard (ECMA-404), but is assumed.
|
a JSON string to hash. [type utf8] |
Returns : |
hash value for key
|
Since 1.2
gboolean json_string_equal (gconstpointer a
,gconstpointer b
);
Check whether a
and b
are equal UTF-8 JSON strings.
|
a JSON string. [type utf8] |
|
another JSON string. [type utf8] |
Returns : |
TRUE if a and b are equal; FALSE otherwise |
Since 1.2
gint json_string_compare (gconstpointer a
,gconstpointer b
);
Check whether a
and b
are equal UTF-8 JSON strings and return an ordering
over them in strcmp()
style.
|
a JSON string. [type utf8] |
|
another JSON string. [type utf8] |
Returns : |
an integer less than zero if a < b , equal to zero if a == b , and
greater than zero if a > b
|
Since 1.2