Gjsify LogoGjsify Logo

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 [methodJson.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 [structJson.Object] or the [structJson.Array] using [methodJson.Node.get_object] or [methodJson.Node.get_array] respectively, and then retrieve the nodes they contain.

A JsonNode may be marked as immutable using [methodJson.Node.seal]. This marks the node and all its descendents as read-only, and means that subsequent calls to setter functions (such as [methodJson.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 [methodJson.Node.unref]), then either unreferenced exactly once more or freed (using [methodJson.Node.free]) to destroy them. The [methodJson.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 [methodJson.Node.copy] and [methodJson.Node.unref] internally.

record

Hierarchy

  • Node

Index

Constructors

  • Creates a new node holding the given type.

    This is a convenience function for [ctorJson.Node.alloc] and [methodJson.Node.init], and it's the equivalent of:

       json_node_init (json_node_alloc (), type);
    

    Parameters

    Returns Json.Node

Properties

name: string

Methods

  • 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.

    Returns Json.Node

  • Retrieves the JSON array inside node.

    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.

    Returns Json.Array

  • Retrieves the object inside node.

    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.

    Returns Json.Object

  • dupString(): string
  • Gets a copy of the string value stored inside a node.

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

    Returns string

  • Check whether a 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.

    Parameters

    Returns boolean

  • free(): void
  • 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.

    Returns Json.Array

  • getBoolean(): boolean
  • 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.

    Returns boolean

  • getDouble(): number
  • 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.

    Returns number

  • getInt(): number
  • 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.

    Returns number

  • 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.

    Returns Json.Object

  • getString(): string
  • Gets the string value stored inside a node.

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

    Returns string

  • getValue(): any
  • 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.

    Returns any

  • getValueType(): GType<unknown>
  • Returns the GType of the payload of the node.

    For JSON_NODE_NULL nodes, the returned type is G_TYPE_INVALID.

    Returns GType<unknown>

  • hash(): number
  • Calculate a hash value for the given key.

    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).

    Returns number

  • 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.

    Parameters

    • type: Json.NodeType

      the type of JSON node to initialize node to

    Returns Json.Node

  • 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.

    Parameters

    • array: Json.Array

      the JSON array to initialize node with, or NULL

    Returns Json.Node

  • 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.

    Parameters

    • value: boolean

      a boolean value

    Returns Json.Node

  • 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.

    Parameters

    • value: number

      a floating point value

    Returns Json.Node

  • 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.

    Parameters

    • value: number

      an integer

    Returns Json.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.

    Returns Json.Node

  • 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.

    Parameters

    • object: Json.Object

      the JSON object to initialize node with, or NULL

    Returns Json.Node

  • 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.

    Parameters

    • value: string

      a string value

    Returns Json.Node

  • isImmutable(): boolean
  • Check whether the given node has been marked as immutable by calling [methodJson.Node.seal] on it.

    Returns boolean

  • isNull(): boolean
  • Checks whether node is a JSON_NODE_NULL.

    A JSON_NODE_NULL node is not the same as a NULL node; a JSON_NODE_NULL represents a literal null value in the JSON tree.

    Returns boolean

  • seal(): void
  • Seals the given node, 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 JSON object will be sealed, etc.

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

    Returns void

  • Sets array inside node.

    The reference count of 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.

    Parameters

    Returns void

  • setBoolean(value: boolean): void
  • Sets value as the boolean content of the node, replacing any existing content.

    It is an error to call this on an immutable node, or on a node which is not a value node.

    Parameters

    • value: boolean

      a boolean value

    Returns void

  • setDouble(value: number): void
  • Sets value as the double content of the node, replacing any existing content.

    It is an error to call this on an immutable node, or on a node which is not a value node.

    Parameters

    • value: number

      a double value

    Returns void

  • setInt(value: number): void
  • Sets value as the integer content of the node, replacing any existing content.

    It is an error to call this on an immutable node, or on a node which is not a value node.

    Parameters

    • value: number

      an integer value

    Returns void

  • 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, or on a node which is not an object node.

    Parameters

    Returns void

  • Sets the parent node for the given node.

    It is an error to call this with an immutable parent.

    The node may be immutable.

    Parameters

    Returns void

  • setString(value: string): void
  • Sets value as the string content of the node, replacing any existing content.

    It is an error to call this on an immutable node, or on a node which is not a value node.

    Parameters

    • value: string

      a string value

    Returns void

  • setValue(value: any): void
  • Sets a scalar value inside the given node.

    The contents of the given GValue are copied into the JsonNode.

    The following GValue types have a direct mapping to JSON types:

    • G_TYPE_INT64
    • G_TYPE_DOUBLE
    • G_TYPE_BOOLEAN
    • G_TYPE_STRING

    JSON-GLib will also automatically promote the following GValue types:

    • G_TYPE_INT to G_TYPE_INT64
    • G_TYPE_FLOAT to G_TYPE_DOUBLE

    It is an error to call this on an immutable node, or on a node which is not a value node.

    Parameters

    • value: any

      the value to set

    Returns void

  • Sets array inside node.

    The reference count of array is not 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.

    Parameters

    Returns void

  • Sets object inside node.

    The reference count of object is not increased.

    It is an error to call this on an immutable node, or on a node which is not an object node.

    Parameters

    Returns void

  • typeName(): string
  • Retrieves the user readable name of the data type contained by node.

    Note: The name is only meant for debugging purposes, and there is no guarantee the name will stay the same across different versions.

    Returns string

  • unref(): void
  • Decrements the reference count of node.

    If the reference count reaches zero, the node is freed.

    Returns void

  • Allocates a new, uninitialized node.

    Use [methodJson.Node.init] and its variants to initialize the returned value.

    Returns Json.Node

  • Creates a new node holding the given type.

    This is a convenience function for [ctorJson.Node.alloc] and [methodJson.Node.init], and it's the equivalent of:

       json_node_init (json_node_alloc (), type);
    

    Parameters

    Returns Json.Node

Legend

  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Type alias with type parameter
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method