mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-01-03 19:36:16 +01:00
25a7c817d3
Add various (nullable) and (optional) annotations which were missing from a variety of functions. Also port a couple of existing (allow-none) annotations in the same files to use (nullable) and (optional) as appropriate instead. Secondly, add various (not nullable) annotations as needed by the new default in gobject-introspection of marking gpointers as (nullable). See https://bugzilla.gnome.org/show_bug.cgi?id=729660. This includes adding some stub documentation comments for the assertion macro error functions, which weren’t previously documented. The new comments are purely to allow for annotations, and hence are marked as (skip) to prevent the symbols appearing in the GIR file. https://bugzilla.gnome.org/show_bug.cgi?id=719966
323 lines
8.9 KiB
C
323 lines
8.9 KiB
C
/* GLIB - Library of useful routines for C programming
|
|
* Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
|
|
*
|
|
* This library is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
* License as published by the Free Software Foundation; either
|
|
* version 2 of the License, or (at your option) any later version.
|
|
*
|
|
* This library is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* Lesser General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
* License along with this library; if not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
/*
|
|
* Modified by the GLib Team and others 1997-2000. See the AUTHORS
|
|
* file for a list of people on the GLib Team. See the ChangeLog
|
|
* files for a list of changes. These files are distributed with
|
|
* GLib at ftp://ftp.gtk.org/pub/gtk/.
|
|
*/
|
|
|
|
#ifndef __G_NODE_H__
|
|
#define __G_NODE_H__
|
|
|
|
#if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
|
|
#error "Only <glib.h> can be included directly."
|
|
#endif
|
|
|
|
#include <glib/gmem.h>
|
|
|
|
G_BEGIN_DECLS
|
|
|
|
typedef struct _GNode GNode;
|
|
|
|
/* Tree traverse flags */
|
|
typedef enum
|
|
{
|
|
G_TRAVERSE_LEAVES = 1 << 0,
|
|
G_TRAVERSE_NON_LEAVES = 1 << 1,
|
|
G_TRAVERSE_ALL = G_TRAVERSE_LEAVES | G_TRAVERSE_NON_LEAVES,
|
|
G_TRAVERSE_MASK = 0x03,
|
|
G_TRAVERSE_LEAFS = G_TRAVERSE_LEAVES,
|
|
G_TRAVERSE_NON_LEAFS = G_TRAVERSE_NON_LEAVES
|
|
} GTraverseFlags;
|
|
|
|
/* Tree traverse orders */
|
|
typedef enum
|
|
{
|
|
G_IN_ORDER,
|
|
G_PRE_ORDER,
|
|
G_POST_ORDER,
|
|
G_LEVEL_ORDER
|
|
} GTraverseType;
|
|
|
|
typedef gboolean (*GNodeTraverseFunc) (GNode *node,
|
|
gpointer data);
|
|
typedef void (*GNodeForeachFunc) (GNode *node,
|
|
gpointer data);
|
|
|
|
/**
|
|
* GCopyFunc:
|
|
* @src: (not nullable): A pointer to the data which should be copied
|
|
* @data: Additional data
|
|
*
|
|
* A function of this signature is used to copy the node data
|
|
* when doing a deep-copy of a tree.
|
|
*
|
|
* Returns: (not nullable): A pointer to the copy
|
|
*
|
|
* Since: 2.4
|
|
*/
|
|
typedef gpointer (*GCopyFunc) (gconstpointer src,
|
|
gpointer data);
|
|
|
|
/* N-way tree implementation
|
|
*/
|
|
struct _GNode
|
|
{
|
|
gpointer data;
|
|
GNode *next;
|
|
GNode *prev;
|
|
GNode *parent;
|
|
GNode *children;
|
|
};
|
|
|
|
/**
|
|
* G_NODE_IS_ROOT:
|
|
* @node: a #GNode
|
|
*
|
|
* Returns %TRUE if a #GNode is the root of a tree.
|
|
*
|
|
* Returns: %TRUE if the #GNode is the root of a tree
|
|
* (i.e. it has no parent or siblings)
|
|
*/
|
|
#define G_NODE_IS_ROOT(node) (((GNode*) (node))->parent == NULL && \
|
|
((GNode*) (node))->prev == NULL && \
|
|
((GNode*) (node))->next == NULL)
|
|
|
|
/**
|
|
* G_NODE_IS_LEAF:
|
|
* @node: a #GNode
|
|
*
|
|
* Returns %TRUE if a #GNode is a leaf node.
|
|
*
|
|
* Returns: %TRUE if the #GNode is a leaf node
|
|
* (i.e. it has no children)
|
|
*/
|
|
#define G_NODE_IS_LEAF(node) (((GNode*) (node))->children == NULL)
|
|
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_new (gpointer data);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
void g_node_destroy (GNode *root);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
void g_node_unlink (GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_copy_deep (GNode *node,
|
|
GCopyFunc copy_func,
|
|
gpointer data);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_copy (GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_insert (GNode *parent,
|
|
gint position,
|
|
GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_insert_before (GNode *parent,
|
|
GNode *sibling,
|
|
GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_insert_after (GNode *parent,
|
|
GNode *sibling,
|
|
GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_prepend (GNode *parent,
|
|
GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
guint g_node_n_nodes (GNode *root,
|
|
GTraverseFlags flags);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_get_root (GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
gboolean g_node_is_ancestor (GNode *node,
|
|
GNode *descendant);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
guint g_node_depth (GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_find (GNode *root,
|
|
GTraverseType order,
|
|
GTraverseFlags flags,
|
|
gpointer data);
|
|
|
|
/* convenience macros */
|
|
/**
|
|
* g_node_append:
|
|
* @parent: the #GNode to place the new #GNode under
|
|
* @node: the #GNode to insert
|
|
*
|
|
* Inserts a #GNode as the last child of the given parent.
|
|
*
|
|
* Returns: the inserted #GNode
|
|
*/
|
|
#define g_node_append(parent, node) \
|
|
g_node_insert_before ((parent), NULL, (node))
|
|
|
|
/**
|
|
* g_node_insert_data:
|
|
* @parent: the #GNode to place the new #GNode under
|
|
* @position: the position to place the new #GNode at. If position is -1,
|
|
* the new #GNode is inserted as the last child of @parent
|
|
* @data: the data for the new #GNode
|
|
*
|
|
* Inserts a new #GNode at the given position.
|
|
*
|
|
* Returns: the new #GNode
|
|
*/
|
|
#define g_node_insert_data(parent, position, data) \
|
|
g_node_insert ((parent), (position), g_node_new (data))
|
|
|
|
/**
|
|
* g_node_insert_data_after:
|
|
* @parent: the #GNode to place the new #GNode under
|
|
* @sibling: the sibling #GNode to place the new #GNode after
|
|
* @data: the data for the new #GNode
|
|
*
|
|
* Inserts a new #GNode after the given sibling.
|
|
*
|
|
* Returns: the new #GNode
|
|
*/
|
|
|
|
#define g_node_insert_data_after(parent, sibling, data) \
|
|
g_node_insert_after ((parent), (sibling), g_node_new (data))
|
|
/**
|
|
* g_node_insert_data_before:
|
|
* @parent: the #GNode to place the new #GNode under
|
|
* @sibling: the sibling #GNode to place the new #GNode before
|
|
* @data: the data for the new #GNode
|
|
*
|
|
* Inserts a new #GNode before the given sibling.
|
|
*
|
|
* Returns: the new #GNode
|
|
*/
|
|
#define g_node_insert_data_before(parent, sibling, data) \
|
|
g_node_insert_before ((parent), (sibling), g_node_new (data))
|
|
|
|
/**
|
|
* g_node_prepend_data:
|
|
* @parent: the #GNode to place the new #GNode under
|
|
* @data: the data for the new #GNode
|
|
*
|
|
* Inserts a new #GNode as the first child of the given parent.
|
|
*
|
|
* Returns: the new #GNode
|
|
*/
|
|
#define g_node_prepend_data(parent, data) \
|
|
g_node_prepend ((parent), g_node_new (data))
|
|
|
|
/**
|
|
* g_node_append_data:
|
|
* @parent: the #GNode to place the new #GNode under
|
|
* @data: the data for the new #GNode
|
|
*
|
|
* Inserts a new #GNode as the last child of the given parent.
|
|
*
|
|
* Returns: the new #GNode
|
|
*/
|
|
#define g_node_append_data(parent, data) \
|
|
g_node_insert_before ((parent), NULL, g_node_new (data))
|
|
|
|
/* traversal function, assumes that 'node' is root
|
|
* (only traverses 'node' and its subtree).
|
|
* this function is just a high level interface to
|
|
* low level traversal functions, optimized for speed.
|
|
*/
|
|
GLIB_AVAILABLE_IN_ALL
|
|
void g_node_traverse (GNode *root,
|
|
GTraverseType order,
|
|
GTraverseFlags flags,
|
|
gint max_depth,
|
|
GNodeTraverseFunc func,
|
|
gpointer data);
|
|
|
|
/* return the maximum tree height starting with 'node', this is an expensive
|
|
* operation, since we need to visit all nodes. this could be shortened by
|
|
* adding 'guint height' to struct _GNode, but then again, this is not very
|
|
* often needed, and would make g_node_insert() more time consuming.
|
|
*/
|
|
GLIB_AVAILABLE_IN_ALL
|
|
guint g_node_max_height (GNode *root);
|
|
|
|
GLIB_AVAILABLE_IN_ALL
|
|
void g_node_children_foreach (GNode *node,
|
|
GTraverseFlags flags,
|
|
GNodeForeachFunc func,
|
|
gpointer data);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
void g_node_reverse_children (GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
guint g_node_n_children (GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_nth_child (GNode *node,
|
|
guint n);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_last_child (GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_find_child (GNode *node,
|
|
GTraverseFlags flags,
|
|
gpointer data);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
gint g_node_child_position (GNode *node,
|
|
GNode *child);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
gint g_node_child_index (GNode *node,
|
|
gpointer data);
|
|
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_first_sibling (GNode *node);
|
|
GLIB_AVAILABLE_IN_ALL
|
|
GNode* g_node_last_sibling (GNode *node);
|
|
|
|
/**
|
|
* g_node_prev_sibling:
|
|
* @node: a #GNode
|
|
*
|
|
* Gets the previous sibling of a #GNode.
|
|
*
|
|
* Returns: the previous sibling of @node, or %NULL if @node is the first
|
|
* node or %NULL
|
|
*/
|
|
#define g_node_prev_sibling(node) ((node) ? \
|
|
((GNode*) (node))->prev : NULL)
|
|
|
|
/**
|
|
* g_node_next_sibling:
|
|
* @node: a #GNode
|
|
*
|
|
* Gets the next sibling of a #GNode.
|
|
*
|
|
* Returns: the next sibling of @node, or %NULL if @node is the last node
|
|
* or %NULL
|
|
*/
|
|
#define g_node_next_sibling(node) ((node) ? \
|
|
((GNode*) (node))->next : NULL)
|
|
|
|
/**
|
|
* g_node_first_child:
|
|
* @node: a #GNode
|
|
*
|
|
* Gets the first child of a #GNode.
|
|
*
|
|
* Returns: the first child of @node, or %NULL if @node is %NULL
|
|
* or has no children
|
|
*/
|
|
#define g_node_first_child(node) ((node) ? \
|
|
((GNode*) (node))->children : NULL)
|
|
|
|
G_END_DECLS
|
|
|
|
#endif /* __G_NODE_H__ */
|