Json.Array¶

Fields¶

None

Methods¶

class	`new` ()
class	`sized_new` (n_elements)
	`add_array_element` (value)
	`add_boolean_element` (value)
	`add_double_element` (value)
	`add_element` (node)
	`add_int_element` (value)
	`add_null_element` ()
	`add_object_element` (value)
	`add_string_element` (value)
	`dup_element` (index_)
	`equal` (b)
	`foreach_element` (func, *data)
	`get_array_element` (index_)
	`get_boolean_element` (index_)
	`get_double_element` (index_)
	`get_element` (index_)
	`get_elements` ()
	`get_int_element` (index_)
	`get_length` ()
	`get_null_element` (index_)
	`get_object_element` (index_)
	`get_string_element` (index_)
	`hash` ()
	`is_immutable` ()
	`ref` ()
	`remove_element` (index_)
	`seal` ()
	`unref` ()

Details¶

class Json.Array¶

JsonArray is the representation of the array type inside JSON.

A JsonArray contains [struct`Json`.Node] elements, which may contain fundamental types, other arrays or objects.

Since arrays can be arbitrarily big, copying them can be expensive; for this reason, they are reference counted. You can control the lifetime of a JsonArray using [method`Json`.Array.ref] and [method`Json`.Array.unref].

To append an element, use [method`Json`.Array.add_element].

To extract an element at a given index, use [method`Json`.Array.get_element].

To retrieve the entire array in list form, use [method`Json`.Array.get_elements].

To retrieve the length of the array, use [method`Json`.Array.get_length].

classmethod new()¶

Returns:: the newly created array
Return type:: Json.Array

Creates a new array.

classmethod sized_new(n_elements)¶

Parameters:: n_elements (int) – number of slots to pre-allocate
Returns:: the newly created array
Return type:: Json.Array

Creates a new array with n_elements slots already allocated.

add_array_element(value)¶

Parameters:: value (Json.Array or None) – the array to add

Conveniently adds an array element into an array.

If value is NULL, a null element will be added instead.

See also: [method`Json`.Array.add_element], [method`Json`.Node.take_array]

New in version 0.8.

add_boolean_element(value)¶

Parameters:: value (bool) – the boolean value to add

Conveniently adds the given boolean value into an array.

See also: [method`Json`.Array.add_element], [method`Json`.Node.set_boolean]

New in version 0.8.

add_double_element(value)¶

Parameters:: value (float) – the floating point value to add

Conveniently adds the given floating point value into an array.

See also: [method`Json`.Array.add_element], [method`Json`.Node.set_double]

New in version 0.8.

add_element(node)¶

Parameters:: node (Json.Node) – the element to add

Appends the given node inside an array.

add_int_element(value)¶

Parameters:: value (int) – the integer value to add

Conveniently adds the given integer value into an array.

See also: [method`Json`.Array.add_element], [method`Json`.Node.set_int]

New in version 0.8.

add_null_element()¶

Conveniently adds a null element into an array

See also: [method`Json`.Array.add_element], JSON_NODE_NULL

New in version 0.8.

add_object_element(value)¶

Parameters:: value (Json.Object or None) – the object to add

Conveniently adds an object into an array.

If value is NULL, a null element will be added instead.

See also: [method`Json`.Array.add_element], [method`Json`.Node.take_object]

New in version 0.8.

add_string_element(value)¶

Parameters:: value (str) – the string value to add

Conveniently adds the given string value into an array.

See also: [method`Json`.Array.add_element], [method`Json`.Node.set_string]

New in version 0.8.

dup_element(index_)¶

Parameters:: index (int) – the index of the element to retrieve
Returns:: a copy of the element at the given position
Return type:: Json.Node

Retrieves a copy of the element at the given position in the array.

New in version 0.6.

equal(b)¶

Parameters:: b (Json.Array) – another JSON array
Returns:: TRUE if the arrays are equal, and FALSE otherwise
Return type:: bool

Check whether two arrays are equal.

Equality is defined as:

the array have the same number of elements
the values of elements in corresponding positions are equal

New in version 1.2.

foreach_element(func, *data)¶

Parameters:

func (Json.ArrayForeach) – the function to be called on each element
data (object or None) – data to be passed to the function

Iterates over all elements of an array, and calls a function on each one of them.

It is safe to change the value of an element of the array while iterating over it, but it is not safe to add or remove elements from the array.

New in version 0.8.

get_array_element(index_)¶

Parameters:: index (int) – the index of the element to retrieve
Returns:: the array
Return type:: Json.Array

Conveniently retrieves the array at the given position inside an array.

See also: [method`Json`.Array.get_element], [method`Json`.Node.get_array]

New in version 0.8.

get_boolean_element(index_)¶

Parameters:: index (int) – the index of the element to retrieve
Returns:: the boolean value
Return type:: bool

Conveniently retrieves the boolean value of the element at the given position inside an array.

See also: [method`Json`.Array.get_element], [method`Json`.Node.get_boolean]

New in version 0.8.

get_double_element(index_)¶

Parameters:: index (int) – the index of the element to retrieve
Returns:: the floating point value
Return type:: float

Conveniently retrieves the floating point value of the element at the given position inside an array.

See also: [method`Json`.Array.get_element], [method`Json`.Node.get_double]

New in version 0.8.

get_element(index_)¶

Parameters:: index (int) – the index of the element to retrieve
Returns:: the element at the given position
Return type:: Json.Node

Retrieves the element at the given position in the array.

get_elements()¶

Returns:: the elements of the array
Return type:: [Json.Node] or None

Retrieves all the elements of an array as a list of nodes.

get_int_element(index_)¶

Parameters:: index (int) – the index of the element to retrieve
Returns:: the integer value
Return type:: int

Conveniently retrieves the integer value of the element at the given position inside an array.

See also: [method`Json`.Array.get_element], [method`Json`.Node.get_int]

New in version 0.8.

get_length()¶

Returns:: the length of the array
Return type:: int

Retrieves the length of the given array

get_null_element(index_)¶

Parameters:: index (int) – the index of the element to retrieve
Returns:: TRUE if the element is null
Return type:: bool

Conveniently checks whether the element at the given position inside the array contains a null value.

See also: [method`Json`.Array.get_element], [method`Json`.Node.is_null]

New in version 0.8.

get_object_element(index_)¶

Parameters:: index (int) – the index of the element to retrieve
Returns:: the object
Return type:: Json.Object

Conveniently retrieves the object at the given position inside an array.

See also: [method`Json`.Array.get_element], [method`Json`.Node.get_object]

New in version 0.8.

get_string_element(index_)¶

Parameters:: index (int) – the index of the element to retrieve
Returns:: the string value
Return type:: str

Conveniently retrieves the string value of the element at the given position inside an array.

See also: [method`Json`.Array.get_element], [method`Json`.Node.get_string]

New in version 0.8.

hash()¶

Returns:: hash value for the key
Return type:: int

Calculates a hash value for the given key.

The hash is calculated over the array and all its elements, recursively.

If the array is immutable, this is a fast operation; otherwise, it scales proportionally with the length of the array.

New in version 1.2.

is_immutable()¶

Returns:: True if the array is immutable
Return type:: bool

Check whether the given array has been marked as immutable by calling [method`Json`.Array.seal] on it.

New in version 1.2.

ref()¶

Returns:: the passed array, with the reference count increased by one
Return type:: Json.Array

Acquires a reference on the given array.

remove_element(index_)¶

Parameters:: index (int) – the position of the element to be removed

Removes the element at the given position inside an array.

This function will release the reference held on the element.

seal()¶

Seals the given array, making it immutable to further changes.

This function will recursively seal all elements in the array too.

If the array is already immutable, this is a no-op.

New in version 1.2.

unref()¶

Releases a reference on the given array.

If the reference count reaches zero, the array is destroyed and all its allocated resources are freed.