glib/gtree.h

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-or-later
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 /*
  21  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
  22  * file for a list of people on the GLib Team.  See the ChangeLog
  23  * files for a list of changes.  These files are distributed with
  24  * GLib at ftp://ftp.gtk.org/pub/gtk/.
  25  */
  26
  27 #ifndef __G_TREE_H__
  28 #define __G_TREE_H__
  29
  30 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  31 #error "Only <glib.h> can be included directly."
  32 #endif
  33
  34 #include <glib/gnode.h>
  35
  36 G_BEGIN_DECLS
  37
  38 #undef G_TREE_DEBUG
  39
  40 typedef struct _GTree  GTree;
  41
  42 /**
  43  * GTreeNode:
  44  *
  45  * An opaque type which identifies a specific node in a #GTree.
  46  *
  47  * Since: 2.68
  48  */
  49 typedef struct _GTreeNode GTreeNode;
  50
  51 typedef gboolean (*GTraverseFunc) (gpointer  key,
  52                                    gpointer  value,
  53                                    gpointer  user_data);
  54
  55 /**
  56  * GTraverseNodeFunc:
  57  * @node: a #GTreeNode
  58  * @user_data: user data passed to g_tree_foreach_node()
  59  *
  60  * Specifies the type of function passed to g_tree_foreach_node(). It is
  61  * passed each node, together with the @user_data parameter passed to
  62  * g_tree_foreach_node(). If the function returns %TRUE, the traversal is
  63  * stopped.
  64  *
  65  * Returns: %TRUE to stop the traversal
  66  * Since: 2.68
  67  */
  68 typedef gboolean (*GTraverseNodeFunc) (GTreeNode *node,
  69                                        gpointer   user_data);
  70
  71 /* Balanced binary trees
  72  */
  73 GLIB_AVAILABLE_IN_ALL
  74 GTree*   g_tree_new             (GCompareFunc      key_compare_func);
  75 GLIB_AVAILABLE_IN_ALL
  76 GTree*   g_tree_new_with_data   (GCompareDataFunc  key_compare_func,
  77                                  gpointer          key_compare_data);
  78 GLIB_AVAILABLE_IN_ALL
  79 GTree*   g_tree_new_full        (GCompareDataFunc  key_compare_func,
  80                                  gpointer          key_compare_data,
  81                                  GDestroyNotify    key_destroy_func,
  82                                  GDestroyNotify    value_destroy_func);
  83 GLIB_AVAILABLE_IN_2_68
  84 GTreeNode *g_tree_node_first (GTree *tree);
  85 GLIB_AVAILABLE_IN_2_68
  86 GTreeNode *g_tree_node_last (GTree *tree);
  87 GLIB_AVAILABLE_IN_2_68
  88 GTreeNode *g_tree_node_previous (GTreeNode *node);
  89 GLIB_AVAILABLE_IN_2_68
  90 GTreeNode *g_tree_node_next (GTreeNode *node);
  91 GLIB_AVAILABLE_IN_ALL
  92 GTree*   g_tree_ref             (GTree            *tree);
  93 GLIB_AVAILABLE_IN_ALL
  94 void     g_tree_unref           (GTree            *tree);
  95 GLIB_AVAILABLE_IN_ALL
  96 void     g_tree_destroy         (GTree            *tree);
  97 GLIB_AVAILABLE_IN_2_68
  98 GTreeNode *g_tree_insert_node (GTree *tree,
  99                                gpointer key,
 100                                gpointer value);
 101 GLIB_AVAILABLE_IN_ALL
 102 void     g_tree_insert          (GTree            *tree,
 103                                  gpointer          key,
 104                                  gpointer          value);
 105 GLIB_AVAILABLE_IN_2_68
 106 GTreeNode *g_tree_replace_node (GTree *tree,
 107                                 gpointer key,
 108                                 gpointer value);
 109 GLIB_AVAILABLE_IN_ALL
 110 void     g_tree_replace         (GTree            *tree,
 111                                  gpointer          key,
 112                                  gpointer          value);
 113 GLIB_AVAILABLE_IN_ALL
 114 gboolean g_tree_remove          (GTree            *tree,
 115                                  gconstpointer     key);
 116
 117 GLIB_AVAILABLE_IN_2_70
 118 void     g_tree_remove_all      (GTree            *tree);
 119
 120 GLIB_AVAILABLE_IN_ALL
 121 gboolean g_tree_steal           (GTree            *tree,
 122                                  gconstpointer     key);
 123 GLIB_AVAILABLE_IN_2_68
 124 gpointer g_tree_node_key (GTreeNode *node);
 125 GLIB_AVAILABLE_IN_2_68
 126 gpointer g_tree_node_value (GTreeNode *node);
 127 GLIB_AVAILABLE_IN_2_68
 128 GTreeNode *g_tree_lookup_node (GTree *tree,
 129                                gconstpointer key);
 130 GLIB_AVAILABLE_IN_ALL
 131 gpointer g_tree_lookup          (GTree            *tree,
 132                                  gconstpointer     key);
 133 GLIB_AVAILABLE_IN_ALL
 134 gboolean g_tree_lookup_extended (GTree            *tree,
 135                                  gconstpointer     lookup_key,
 136                                  gpointer         *orig_key,
 137                                  gpointer         *value);
 138 GLIB_AVAILABLE_IN_ALL
 139 void     g_tree_foreach         (GTree            *tree,
 140                                  GTraverseFunc     func,
 141                                  gpointer          user_data);
 142 GLIB_AVAILABLE_IN_2_68
 143 void g_tree_foreach_node (GTree *tree,
 144                           GTraverseNodeFunc func,
 145                           gpointer user_data);
 146
 147 GLIB_DEPRECATED
 148 void     g_tree_traverse        (GTree            *tree,
 149                                  GTraverseFunc     traverse_func,
 150                                  GTraverseType     traverse_type,
 151                                  gpointer          user_data);
 152
 153 GLIB_AVAILABLE_IN_2_68
 154 GTreeNode *g_tree_search_node (GTree *tree,
 155                                GCompareFunc search_func,
 156                                gconstpointer user_data);
 157 GLIB_AVAILABLE_IN_ALL
 158 gpointer g_tree_search          (GTree            *tree,
 159                                  GCompareFunc      search_func,
 160                                  gconstpointer     user_data);
 161 GLIB_AVAILABLE_IN_2_68
 162 GTreeNode *g_tree_lower_bound (GTree *tree,
 163                                gconstpointer key);
 164 GLIB_AVAILABLE_IN_2_68
 165 GTreeNode *g_tree_upper_bound (GTree *tree,
 166                                gconstpointer key);
 167 GLIB_AVAILABLE_IN_ALL
 168 gint     g_tree_height          (GTree            *tree);
 169 GLIB_AVAILABLE_IN_ALL
 170 gint     g_tree_nnodes          (GTree            *tree);
 171
 172 #ifdef G_TREE_DEBUG
 173 /*< private >*/
 174 #ifndef __GTK_DOC_IGNORE__
 175 void g_tree_dump (GTree *tree);
 176 #endif  /* !__GTK_DOC_IGNORE__ */
 177 #endif  /* G_TREE_DEBUG */
 178
 179 G_END_DECLS
 180
 181 #endif /* __G_TREE_H__ */