Json.Node¶

Fields¶

None

Methods¶

class	`alloc` ()
class	`new` (type)
	`copy` ()
	`dup_array` ()
	`dup_object` ()
	`dup_string` ()
	`equal` (b)
	`free` ()
	`get_array` ()
	`get_boolean` ()
	`get_double` ()
	`get_int` ()
	`get_node_type` ()
	`get_object` ()
	`get_parent` ()
	`get_string` ()
	`get_value` ()
	`get_value_type` ()
	`hash` ()
	`init` (type)
	`init_array` (array)
	`init_boolean` (value)
	`init_double` (value)
	`init_int` (value)
	`init_null` ()
	`init_object` (object)
	`init_string` (value)
	`is_immutable` ()
	`is_null` ()
	`ref` ()
	`seal` ()
	`set_array` (array)
	`set_boolean` (value)
	`set_double` (value)
	`set_int` (value)
	`set_object` (object)
	`set_parent` (parent)
	`set_string` (value)
	`set_value` (value)
	`take_array` (array)
	`take_object` (object)
	`type_name` ()
	`unref` ()

Details¶

class Json.Node¶

A generic container of JSON data types.

JsonNode 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 [method`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 [struct`Json`.Object] or the [struct`Json`.Array] using [method`Json`.Node.get_object] or [method`Json`.Node.get_array] respectively, and then retrieve the nodes they contain.

A JsonNode may be marked as immutable using [method`Json`.Node.seal]. This marks the node and all its descendents as read-only, and means that subsequent calls to setter functions (such as [method`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 nodes may be passed to functions which retain a reference to them without needing to take a copy.

A JsonNode supports two types of memory management: malloc/free semantics, and reference counting semantics. The two may be mixed to a limited extent: nodes may be allocated (which gives them a reference count of 1), referenced one or more times, unreferenced exactly that number of times (using [method`Json`.Node.unref]), then either unreferenced exactly once more or freed (using [method`Json`.Node.free]) to destroy them. The [method`Json`.Node.free] function must not be used when a node might have a reference count not equal to 1. To this end, JSON-GLib uses [method`Json`.Node.copy] and [method`Json`.Node.unref] internally.

classmethod alloc()¶

Returns:: the newly allocated node
Return type:: Json.Node

Allocates a new, uninitialized node.

Use [method`Json`.Node.init] and its variants to initialize the returned value.

New in version 0.16.

classmethod new(type)¶

Parameters:: type (Json.NodeType) – the type of the node to create
Returns:: the newly created node
Return type:: Json.Node

Creates a new node holding the given type.

This is a convenience function for [ctor`Json`.Node.alloc] and [method`Json`.Node.init], and it’s the equivalent of:

``c: json_node_init (json_node_alloc (), type);

``

copy()¶

Returns:: the copied of the given node
Return type:: Json.Node

Copies self.

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, self is immutable. However, there should be no need to copy an immutable node.

dup_array()¶

Returns:: the JSON array with its reference count increased.
Return type:: Json.Array or None

Retrieves the JSON array inside self.

The reference count of the returned array is increased.

It is a programmer error to call this on a node which doesn’t hold an array value. Use JSON_NODE_HOLDS_ARRAY first.

dup_object()¶

Returns:: the JSON object
Return type:: Json.Object or None

Retrieves the object inside self.

The reference count of the returned object is increased.

It is a programmer error to call this on a node which doesn’t hold an object value. Use JSON_NODE_HOLDS_OBJECT first.

dup_string()¶

Returns:: a copy of the string inside the node
Return type:: str or None

Gets a copy of the string value stored inside a node.

If the node does not hold a string value, NULL is returned.

equal(b)¶

Parameters:: b (Json.Node) – another JSON node
Returns:: TRUE if self and b are equal; FALSE otherwise
Return type:: bool

Check whether self and b are equal node, 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.

New in version 1.2.

free()¶: Frees the resources allocated by the node.

get_array()¶

Returns:: the JSON array
Return type:: Json.Array or None

Retrieves the JSON array stored inside a node.

It is a programmer error to call this on a node which doesn’t hold an array value. Use JSON_NODE_HOLDS_ARRAY first.

get_boolean()¶

Returns:: a boolean value.
Return type:: bool

Gets the boolean value stored inside a node.

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.

get_double()¶

Returns:: a double value.
Return type:: float

Gets the double value stored inside a node.

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.

get_int()¶

Returns:: an integer value.
Return type:: int

Gets the integer value stored inside a node.

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.

get_node_type()¶

Returns:: the type of the node
Return type:: Json.NodeType

Retrieves the type of a self.

New in version 0.8.

get_object()¶

Returns:: the JSON object
Return type:: Json.Object or None

Retrieves the object stored inside a node.

It is a programmer error to call this on a node which doesn’t hold an object value. Use JSON_NODE_HOLDS_OBJECT first.

get_parent()¶

Returns:: the parent node, or NULL if self is the root node
Return type:: Json.Node or None

Retrieves the parent node of the given self.

get_string()¶

Returns:: a string value.
Return type:: str or None

Gets the string value stored inside a node.

If the node does not hold a string value, NULL is returned.

get_value()¶

Returns:: return location for an uninitialized value
Return type:: value: GObject.Value

Retrieves a value from a node and copies into value.

When done using it, call g_value_unset() on the GValue to free the associated resources.

It is a programmer error to call this on a node which doesn’t hold a scalar value. Use JSON_NODE_HOLDS_VALUE first.

get_value_type()¶

Returns:: the type for the payload
Return type:: GObject.GType

Returns the GType of the payload of the node.

For JSON_NODE_NULL nodes, the returned type is G_TYPE_INVALID.

New in version 0.4.

hash()¶

Returns:: hash value for self
Return type:: int

Calculate a hash value for the given self.

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 JSON object if this node contains an object).

New in version 1.2.

init(type)¶

Parameters:: type (Json.NodeType) – the type of JSON node to initialize self to
Returns:: the initialized node
Return type:: Json.Node

Initializes a self to a specific type.