@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/glib/tree.js

@@ -1,5 +1,10 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * The GTree struct is an opaque data structure representing a
+ * balanced binary tree. It should be
+ * accessed only by using the following functions.
+ */
 export class Tree {
     ptr;
     constructor(...args) {
@@ -28,6 +33,14 @@ export class Tree {
             },
         ], { type: "boxed", borrowed: true, innerType: "GTree" });
     }
+    /**
+     * Removes all keys and values from the #GTree and decreases its
+     * reference count by one. If keys and/or values are dynamically
+     * allocated, you should either free them first or create the #GTree
+     * using g_tree_new_full(). In the latter case the destroy functions
+     * you supplied will be called on all keys and values before destroying
+     * the #GTree.
+     */
     destroy() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_destroy", [
             {
@@ -36,6 +49,18 @@ export class Tree {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Calls the given function for each of the key/value pairs in the #GTree.
+     * The function is passed the key and value of each pair, and the given
+     * `data` parameter. The tree is traversed in sorted order.
+     *
+     * The tree may not be modified while iterating over it (you can't
+     * add/remove items). To remove all items matching a predicate, you need
+     * to add each item to a list in your #GTraverseFunc as you walk over
+     * the tree, then walk the list and remove each item.
+     * @param func - the function to call for each node visited.
+     * @param userData - user data to pass to the function
+     */
     foreach(func, userData) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_foreach", [
             {
@@ -53,6 +78,18 @@ export class Tree {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Calls the given function for each of the nodes in the #GTree.
+     * The function is passed the pointer to the particular node, and the given
+     * `data` parameter. The tree traversal happens in-order.
+     *
+     * The tree may not be modified while iterating over it (you can't
+     * add/remove items). To remove all items matching a predicate, you need
+     * to add each item to a list in your #GTraverseFunc as you walk over
+     * the tree, then walk the list and remove each item.
+     * @param func - the function to call for each node visited.
+     * @param userData - user data to pass to the function
+     */
     foreachNode(func, userData) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_foreach_node", [
             {
@@ -70,6 +107,13 @@ export class Tree {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the height of a #GTree.
+     *
+     * If the #GTree contains no nodes, the height is 0.
+     * If the #GTree contains only one root node the height is 1.
+     * If the root node has children the height is 2, etc.
+     */
     height() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_height", [
             {
@@ -78,6 +122,14 @@ export class Tree {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Inserts a key/value pair into a #GTree.
+     *
+     * Inserts a new key and value into a #GTree as g_tree_insert_node() does,
+     * only this function does not return the inserted or set node.
+     * @param key - the key to insert
+     * @param value - the value corresponding to the key
+     */
     insert(key, value) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_insert", [
             {
@@ -96,6 +148,23 @@ export class Tree {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Inserts a key/value pair into a #GTree.
+     *
+     * If the given key already exists in the #GTree its corresponding value
+     * is set to the new value. If you supplied a `value_destroy_func` when
+     * creating the #GTree, the old value is freed using that function. If
+     * you supplied a `key_destroy_func` when creating the #GTree, the passed
+     * key is freed using that function.
+     *
+     * The tree is automatically 'balanced' as new key/value pairs are added,
+     * so that the distance from the root to every leaf is as small as possible.
+     * The cost of maintaining a balanced tree while inserting new key/value
+     * result in a O(n log(n)) operation where most of the other operations
+     * are O(log(n)).
+     * @param key - the key to insert
+     * @param value - the value corresponding to the key
+     */
     insertNode(key, value) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_insert_node", [
             {
@@ -114,6 +183,12 @@ export class Tree {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Gets the value corresponding to the given key. Since a #GTree is
+     * automatically balanced as key/value pairs are added, key lookup
+     * is O(log n) (where n is the number of key/value pairs in the tree).
+     * @param key - the key to look up
+     */
     lookup(key) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_lookup", [
             {
@@ -127,6 +202,15 @@ export class Tree {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Looks up a key in the #GTree, returning the original key and the
+     * associated value. This is useful if you need to free the memory
+     * allocated for the original key, for example before calling
+     * g_tree_remove().
+     * @param lookupKey - the key to look up
+     * @param origKey - returns the original key
+     * @param value - returns the value associated with the key
+     */
     lookupExtended(lookupKey, origKey, value) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_lookup_extended", [
             {
@@ -156,6 +240,12 @@ export class Tree {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the tree node corresponding to the given key. Since a #GTree is
+     * automatically balanced as key/value pairs are added, key lookup
+     * is O(log n) (where n is the number of key/value pairs in the tree).
+     * @param key - the key to look up
+     */
     lookupNode(key) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_lookup_node", [
             {
@@ -169,6 +259,15 @@ export class Tree {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Gets the lower bound node corresponding to the given key,
+     * or %NULL if the tree is empty or all the nodes in the tree
+     * have keys that are strictly lower than the searched key.
+     *
+     * The lower bound is the first node that has its key greater
+     * than or equal to the searched key.
+     * @param key - the key to calculate the lower bound for
+     */
     lowerBound(key) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_lower_bound", [
             {
@@ -182,6 +281,9 @@ export class Tree {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Gets the number of nodes in a #GTree.
+     */
     nnodes() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_nnodes", [
             {
@@ -190,6 +292,10 @@ export class Tree {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns the first in-order node of the tree, or %NULL
+     * for an empty tree.
+     */
     nodeFirst() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_node_first", [
             {
@@ -198,6 +304,10 @@ export class Tree {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Returns the last in-order node of the tree, or %NULL
+     * for an empty tree.
+     */
     nodeLast() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_node_last", [
             {
@@ -206,6 +316,11 @@ export class Tree {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Increments the reference count of `tree` by one.
+     *
+     * It is safe to call this function from any thread.
+     */
     ref() {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_ref", [
             {
@@ -220,6 +335,19 @@ export class Tree {
         });
         return getObject(ptr, Tree);
     }
+    /**
+     * Removes a key/value pair from a #GTree.
+     *
+     * If the #GTree was created using g_tree_new_full(), the key and value
+     * are freed using the supplied destroy functions, otherwise you have to
+     * make sure that any dynamically allocated values are freed yourself.
+     * If the key does not exist in the #GTree, the function does nothing.
+     *
+     * The cost of maintaining a balanced tree while removing a key/value
+     * result in a O(n log(n)) operation where most of the other operations
+     * are O(log(n)).
+     * @param key - the key to remove
+     */
     remove(key) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_remove", [
             {
@@ -233,6 +361,10 @@ export class Tree {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Removes all nodes from a #GTree and destroys their keys and values,
+     * then resets the #GTree’s root to %NULL.
+     */
     removeAll() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_remove_all", [
             {
@@ -241,6 +373,12 @@ export class Tree {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Inserts a new key and value into a #GTree as g_tree_replace_node() does,
+     * only this function does not return the inserted or set node.
+     * @param key - the key to insert
+     * @param value - the value corresponding to the key
+     */
     replace(key, value) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_replace", [
             {
@@ -259,6 +397,19 @@ export class Tree {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Inserts a new key and value into a #GTree similar to g_tree_insert_node().
+     * The difference is that if the key already exists in the #GTree, it gets
+     * replaced by the new key. If you supplied a `value_destroy_func` when
+     * creating the #GTree, the old value is freed using that function. If you
+     * supplied a `key_destroy_func` when creating the #GTree, the old key is
+     * freed using that function.
+     *
+     * The tree is automatically 'balanced' as new key/value pairs are added,
+     * so that the distance from the root to every leaf is as small as possible.
+     * @param key - the key to insert
+     * @param value - the value corresponding to the key
+     */
     replaceNode(key, value) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_replace_node", [
             {
@@ -277,6 +428,19 @@ export class Tree {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Searches a #GTree using @search_func.
+     *
+     * The `search_func` is called with a pointer to the key of a key/value
+     * pair in the tree, and the passed in @user_data. If `search_func` returns
+     * 0 for a key/value pair, then the corresponding value is returned as
+     * the result of g_tree_search(). If `search_func` returns -1, searching
+     * will proceed among the key/value pairs that have a smaller key; if
+     * `search_func` returns 1, searching will proceed among the key/value
+     * pairs that have a larger key.
+     * @param searchFunc - a function used to search the #GTree
+     * @param userData - the data passed as the second argument to @search_func
+     */
     search(searchFunc, userData) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_search", [
             {
@@ -294,6 +458,19 @@ export class Tree {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Searches a #GTree using @search_func.
+     *
+     * The `search_func` is called with a pointer to the key of a key/value
+     * pair in the tree, and the passed in @user_data. If `search_func` returns
+     * 0 for a key/value pair, then the corresponding node is returned as
+     * the result of g_tree_search(). If `search_func` returns -1, searching
+     * will proceed among the key/value pairs that have a smaller key; if
+     * `search_func` returns 1, searching will proceed among the key/value
+     * pairs that have a larger key.
+     * @param searchFunc - a function used to search the #GTree
+     * @param userData - the data passed as the second argument to @search_func
+     */
     searchNode(searchFunc, userData) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_search_node", [
             {
@@ -311,6 +488,13 @@ export class Tree {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Removes a key and its associated value from a #GTree without calling
+     * the key and value destroy functions.
+     *
+     * If the key does not exist in the #GTree, the function does nothing.
+     * @param key - the key to remove
+     */
     steal(key) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_steal", [
             {
@@ -324,6 +508,12 @@ export class Tree {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Calls the given function for each node in the #GTree.
+     * @param traverseFunc - the function to call for each node visited. If this
+     * @param traverseType - the order in which nodes are visited, one of %G_IN_ORDER,
+     * @param userData - user data to pass to the function
+     */
     traverse(traverseFunc, traverseType, userData) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_traverse", [
             {
@@ -345,6 +535,14 @@ export class Tree {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Decrements the reference count of `tree` by one.
+     * If the reference count drops to 0, all keys and values will
+     * be destroyed (if destroy functions were specified) and all
+     * memory allocated by `tree` will be released.
+     *
+     * It is safe to call this function from any thread.
+     */
     unref() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_unref", [
             {
@@ -353,6 +551,15 @@ export class Tree {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the upper bound node corresponding to the given key,
+     * or %NULL if the tree is empty or all the nodes in the tree
+     * have keys that are lower than or equal to the searched key.
+     *
+     * The upper bound is the first node that has its key strictly greater
+     * than the searched key.
+     * @param key - the key to calculate the upper bound for
+     */
     upperBound(key) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_tree_upper_bound", [
             {