json_glib/auto/

node.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir
// from gtk-girs (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{ffi,Array,NodeType,Object};
use glib::{translate::*};

glib::wrapper! {
    /// 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
    /// [`value()`][Self::value()] function, and then use the `GValue` API to extract
    /// the data; if the node contains a complex type you can retrieve the
    /// [`Object`][crate::Object] or the [`Array`][crate::Array] using [`object()`][Self::object()]
    /// or [`array()`][Self::array()] respectively, and then retrieve the nodes
    /// they contain.
    ///
    /// A `JsonNode` may be marked as immutable using [`seal()`][Self::seal()]. This
    /// marks the node and all its descendents as read-only, and means that
    /// subsequent calls to setter functions (such as [`set_array()`][Self::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 `Json::Node::unref()`), then either unreferenced exactly
    /// once more or freed (using `Json::Node::free()`) to destroy them.
    /// The `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
    /// `Json::Node::copy()` and `Json::Node::unref()` internally.
    #[derive(Debug, PartialOrd, Ord)]
    pub struct Node(Shared<ffi::JsonNode>);

    match fn {
        ref => |ptr| ffi::json_node_ref(ptr),
        unref => |ptr| ffi::json_node_unref(ptr),
        type_ => || ffi::json_node_get_type(),
    }
}

impl Node {
    /// Allocates a new, uninitialized node.
    ///
    /// Use [`init()`][Self::init()] and its variants to initialize the returned value.
    ///
    /// # Returns
    ///
    /// the newly allocated node
    #[doc(alias = "json_node_alloc")]
    pub fn alloc() -> Node {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::json_node_alloc())
        }
    }

    /// Creates a new node holding the given @type_.
    ///
    /// This is a convenience function for `Json::Node::alloc()` and
    /// [`init()`][Self::init()], and it's the equivalent of:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    ///    json_node_init (json_node_alloc (), type);
    /// ```
    /// ## `type_`
    /// the type of the node to create
    ///
    /// # Returns
    ///
    /// the newly created node
    #[doc(alias = "json_node_new")]
    pub fn new(type_: NodeType) -> Node {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::json_node_new(type_.into_glib()))
        }
    }

    #[doc(alias = "json_node_copy")]
#[must_use]
    pub fn copy(&self) -> Node {
        unsafe {
            from_glib_full(ffi::json_node_copy(self.to_glib_none().0))
        }
    }

    /// 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.
    ///
    /// # Returns
    ///
    /// the JSON array with its reference
    ///   count increased.
    #[doc(alias = "json_node_dup_array")]
    pub fn dup_array(&self) -> Option<Array> {
        unsafe {
            from_glib_full(ffi::json_node_dup_array(self.to_glib_none().0))
        }
    }

    /// 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.
    ///
    /// # Returns
    ///
    /// the JSON object
    #[doc(alias = "json_node_dup_object")]
    pub fn dup_object(&self) -> Option<Object> {
        unsafe {
            from_glib_full(ffi::json_node_dup_object(self.to_glib_none().0))
        }
    }

    /// Gets a copy of the string value stored inside a node.
    ///
    /// If the node does not hold a string value, `NULL` is returned.
    ///
    /// # Returns
    ///
    /// a copy of the string
    ///   inside the node
    #[doc(alias = "json_node_dup_string")]
    pub fn dup_string(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_full(ffi::json_node_dup_string(self.to_glib_none().0))
        }
    }

    #[cfg(feature = "v1_2")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_2")))]
    #[doc(alias = "json_node_equal")]
     fn equal(&self, b: &Node) -> bool {
        unsafe {
            from_glib(ffi::json_node_equal(ToGlibPtr::<*mut ffi::JsonNode>::to_glib_none(self).0 as glib::ffi::gconstpointer, ToGlibPtr::<*mut ffi::JsonNode>::to_glib_none(b).0 as glib::ffi::gconstpointer))
        }
    }

    /// 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
    ///
    /// the JSON array
    #[doc(alias = "json_node_get_array")]
    #[doc(alias = "get_array")]
    pub fn array(&self) -> Option<Array> {
        unsafe {
            from_glib_none(ffi::json_node_get_array(self.to_glib_none().0))
        }
    }

    /// 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
    ///
    /// a boolean value.
    #[doc(alias = "json_node_get_boolean")]
    #[doc(alias = "get_boolean")]
    pub fn is_boolean(&self) -> bool {
        unsafe {
            from_glib(ffi::json_node_get_boolean(self.to_glib_none().0))
        }
    }

    /// 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
    ///
    /// a double value.
    #[doc(alias = "json_node_get_double")]
    #[doc(alias = "get_double")]
    pub fn double(&self) -> f64 {
        unsafe {
            ffi::json_node_get_double(self.to_glib_none().0)
        }
    }

    /// 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
    ///
    /// an integer value.
    #[doc(alias = "json_node_get_int")]
    #[doc(alias = "get_int")]
    pub fn int(&self) -> i64 {
        unsafe {
            ffi::json_node_get_int(self.to_glib_none().0)
        }
    }

    /// Retrieves the type of a @self.
    ///
    /// # Returns
    ///
    /// the type of the node
    #[doc(alias = "json_node_get_node_type")]
    #[doc(alias = "get_node_type")]
    pub fn node_type(&self) -> NodeType {
        unsafe {
            from_glib(ffi::json_node_get_node_type(self.to_glib_none().0))
        }
    }

    /// 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
    ///
    /// the JSON object
    #[doc(alias = "json_node_get_object")]
    #[doc(alias = "get_object")]
    pub fn object(&self) -> Option<Object> {
        unsafe {
            from_glib_none(ffi::json_node_get_object(self.to_glib_none().0))
        }
    }

    /// Retrieves the parent node of the given @self.
    ///
    /// # Returns
    ///
    /// the parent node, or `NULL` if @self
    ///   is the root node
    #[doc(alias = "json_node_get_parent")]
    #[doc(alias = "get_parent")]
#[must_use]
    pub fn parent(&self) -> Option<Node> {
        unsafe {
            from_glib_none(ffi::json_node_get_parent(self.to_glib_none().0))
        }
    }

    /// Gets the string value stored inside a node.
    ///
    /// If the node does not hold a string value, `NULL` is returned.
    ///
    /// # Returns
    ///
    /// a string value.
    #[doc(alias = "json_node_get_string")]
    #[doc(alias = "get_string")]
    pub fn string(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::json_node_get_string(self.to_glib_none().0))
        }
    }

    /// 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
    ///
    ///
    /// ## `value`
    /// return location for an uninitialized value
    #[doc(alias = "json_node_get_value")]
    #[doc(alias = "get_value")]
    pub fn value(&self) -> glib::Value {
        unsafe {
            let mut value = glib::Value::uninitialized();
            ffi::json_node_get_value(self.to_glib_none().0, value.to_glib_none_mut().0);
            value
        }
    }

    /// Returns the `GType` of the payload of the node.
    ///
    /// For `JSON_NODE_NULL` nodes, the returned type is `G_TYPE_INVALID`.
    ///
    /// # Returns
    ///
    /// the type for the payload
    #[doc(alias = "json_node_get_value_type")]
    #[doc(alias = "get_value_type")]
    pub fn value_type(&self) -> glib::types::Type {
        unsafe {
            from_glib(ffi::json_node_get_value_type(self.to_glib_none().0))
        }
    }

    #[cfg(feature = "v1_2")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_2")))]
    #[doc(alias = "json_node_hash")]
     fn hash(&self) -> u32 {
        unsafe {
            ffi::json_node_hash(ToGlibPtr::<*mut ffi::JsonNode>::to_glib_none(self).0 as glib::ffi::gconstpointer)
        }
    }

    /// Initializes a @self 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.
    /// ## `type_`
    /// the type of JSON node to initialize @self to
    ///
    /// # Returns
    ///
    /// the initialized node
    #[doc(alias = "json_node_init")]
#[must_use]
    pub fn init(&self, type_: NodeType) -> Node {
        unsafe {
            from_glib_none(ffi::json_node_init(self.to_glib_none().0, type_.into_glib()))
        }
    }

    /// Initializes @self 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.
    /// ## `array`
    /// the JSON array to initialize @self with, or `NULL`
    ///
    /// # Returns
    ///
    /// the initialized node
    #[doc(alias = "json_node_init_array")]
#[must_use]
    pub fn init_array(&self, array: Option<&Array>) -> Node {
        unsafe {
            from_glib_none(ffi::json_node_init_array(self.to_glib_none().0, array.to_glib_none().0))
        }
    }

    /// Initializes @self 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.
    /// ## `value`
    /// a boolean value
    ///
    /// # Returns
    ///
    /// the initialized node
    #[doc(alias = "json_node_init_boolean")]
#[must_use]
    pub fn init_boolean(&self, value: bool) -> Node {
        unsafe {
            from_glib_none(ffi::json_node_init_boolean(self.to_glib_none().0, value.into_glib()))
        }
    }

    /// Initializes @self 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.
    /// ## `value`
    /// a floating point value
    ///
    /// # Returns
    ///
    /// the initialized node
    #[doc(alias = "json_node_init_double")]
#[must_use]
    pub fn init_double(&self, value: f64) -> Node {
        unsafe {
            from_glib_none(ffi::json_node_init_double(self.to_glib_none().0, value))
        }
    }

    /// Initializes @self 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.
    /// ## `value`
    /// an integer
    ///
    /// # Returns
    ///
    /// the initialized node
    #[doc(alias = "json_node_init_int")]
#[must_use]
    pub fn init_int(&self, value: i64) -> Node {
        unsafe {
            from_glib_none(ffi::json_node_init_int(self.to_glib_none().0, value))
        }
    }

    /// Initializes @self 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
    ///
    /// the initialized node
    #[doc(alias = "json_node_init_null")]
#[must_use]
    pub fn init_null(&self) -> Node {
        unsafe {
            from_glib_none(ffi::json_node_init_null(self.to_glib_none().0))
        }
    }

    /// Initializes @self 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.
    /// ## `object`
    /// the JSON object to initialize @self with, or `NULL`
    ///
    /// # Returns
    ///
    /// the initialized node
    #[doc(alias = "json_node_init_object")]
#[must_use]
    pub fn init_object(&self, object: Option<&Object>) -> Node {
        unsafe {
            from_glib_none(ffi::json_node_init_object(self.to_glib_none().0, object.to_glib_none().0))
        }
    }

    /// Initializes @self 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.
    /// ## `value`
    /// a string value
    ///
    /// # Returns
    ///
    /// the initialized node
    #[doc(alias = "json_node_init_string")]
#[must_use]
    pub fn init_string(&self, value: Option<&str>) -> Node {
        unsafe {
            from_glib_none(ffi::json_node_init_string(self.to_glib_none().0, value.to_glib_none().0))
        }
    }

    /// Check whether the given @self has been marked as immutable by calling
    /// [`seal()`][Self::seal()] on it.
    ///
    /// # Returns
    ///
    /// `TRUE` if the @self is immutable
    #[cfg(feature = "v1_2")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_2")))]
    #[doc(alias = "json_node_is_immutable")]
    pub fn is_immutable(&self) -> bool {
        unsafe {
            from_glib(ffi::json_node_is_immutable(self.to_glib_none().0))
        }
    }

    /// Checks whether @self 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
    ///
    /// `TRUE` if the node is null
    #[doc(alias = "json_node_is_null")]
    pub fn is_null(&self) -> bool {
        unsafe {
            from_glib(ffi::json_node_is_null(self.to_glib_none().0))
        }
    }

    /// Seals the given node, making it immutable to further changes.
    ///
    /// In order to be sealed, the @self 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.
    #[cfg(feature = "v1_2")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_2")))]
    #[doc(alias = "json_node_seal")]
    pub fn seal(&self) {
        unsafe {
            ffi::json_node_seal(self.to_glib_none().0);
        }
    }

    /// Sets @array inside @self.
    ///
    /// 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.
    /// ## `array`
    /// a JSON array
    #[doc(alias = "json_node_set_array")]
    pub fn set_array(&self, array: &Array) {
        unsafe {
            ffi::json_node_set_array(self.to_glib_none().0, array.to_glib_none().0);
        }
    }

    /// Sets @value as the boolean content of the @self, 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.
    /// ## `value`
    /// a boolean value
    #[doc(alias = "json_node_set_boolean")]
    pub fn set_boolean(&self, value: bool) {
        unsafe {
            ffi::json_node_set_boolean(self.to_glib_none().0, value.into_glib());
        }
    }

    /// Sets @value as the double content of the @self, 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.
    /// ## `value`
    /// a double value
    #[doc(alias = "json_node_set_double")]
    pub fn set_double(&self, value: f64) {
        unsafe {
            ffi::json_node_set_double(self.to_glib_none().0, value);
        }
    }

    /// Sets @value as the integer content of the @self, 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.
    /// ## `value`
    /// an integer value
    #[doc(alias = "json_node_set_int")]
    pub fn set_int(&self, value: i64) {
        unsafe {
            ffi::json_node_set_int(self.to_glib_none().0, value);
        }
    }

    /// Sets @objects inside @self.
    ///
    /// 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.
    /// ## `object`
    /// a JSON object
    #[doc(alias = "json_node_set_object")]
    pub fn set_object(&self, object: Option<&Object>) {
        unsafe {
            ffi::json_node_set_object(self.to_glib_none().0, object.to_glib_none().0);
        }
    }

    /// Sets the parent node for the given `node`.
    ///
    /// It is an error to call this with an immutable @parent.
    ///
    /// The @self may be immutable.
    /// ## `parent`
    /// the parent node
    #[doc(alias = "json_node_set_parent")]
    pub fn set_parent(&self, parent: Option<&Node>) {
        unsafe {
            ffi::json_node_set_parent(self.to_glib_none().0, parent.to_glib_none().0);
        }
    }

    /// Sets @value as the string content of the @self, 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.
    /// ## `value`
    /// a string value
    #[doc(alias = "json_node_set_string")]
    pub fn set_string(&self, value: &str) {
        unsafe {
            ffi::json_node_set_string(self.to_glib_none().0, value.to_glib_none().0);
        }
    }

    /// 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.
    /// ## `value`
    /// the value to set
    #[doc(alias = "json_node_set_value")]
    pub fn set_value(&self, value: &glib::Value) {
        unsafe {
            ffi::json_node_set_value(self.to_glib_none().0, value.to_glib_none().0);
        }
    }

    /// Sets @array inside @self.
    ///
    /// 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.
    /// ## `array`
    /// a JSON array
    #[doc(alias = "json_node_take_array")]
    pub fn take_array(&self, array: Array) {
        unsafe {
            ffi::json_node_take_array(self.to_glib_none().0, array.into_glib_ptr());
        }
    }

    /// Sets @object inside @self.
    ///
    /// 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.
    /// ## `object`
    /// a JSON object
    #[doc(alias = "json_node_take_object")]
    pub fn take_object(&self, object: Object) {
        unsafe {
            ffi::json_node_take_object(self.to_glib_none().0, object.into_glib_ptr());
        }
    }

    /// Retrieves the user readable name of the data type contained by @self.
    ///
    /// **Note**: The name is only meant for debugging purposes, and there is no
    /// guarantee the name will stay the same across different versions.
    ///
    /// # Returns
    ///
    /// a string containing the name of the type
    #[doc(alias = "json_node_type_name")]
    pub fn type_name(&self) -> glib::GString {
        unsafe {
            from_glib_none(ffi::json_node_type_name(self.to_glib_none().0))
        }
    }
}

#[cfg(feature = "v1_2")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_2")))]
impl PartialEq for Node {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.equal(other)
    }
}
#[cfg(feature = "v1_2")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_2")))]

impl Eq for Node {}

#[cfg(feature = "v1_2")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_2")))]
impl std::hash::Hash for Node {
    #[inline]
    fn hash<H>(&self, state: &mut H) where H: std::hash::Hasher {
        std::hash::Hash::hash(&self.hash(), state)
    }
}