glib/garray.h

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
  20  * file for a list of people on the GLib Team.  See the ChangeLog
  21  * files for a list of changes.  These files are distributed with
  22  * GLib at ftp://ftp.gtk.org/pub/gtk/.
  23  */
  24
  25 #ifndef __G_ARRAY_H__
  26 #define __G_ARRAY_H__
  27
  28 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  29 #error "Only <glib.h> can be included directly."
  30 #endif
  31
  32 #include <glib/gtypes.h>
  33
  34 G_BEGIN_DECLS
  35
  36 typedef struct _GBytes          GBytes;
  37 typedef struct _GArray          GArray;
  38 typedef struct _GByteArray      GByteArray;
  39 typedef struct _GPtrArray       GPtrArray;
  40
  41 struct _GArray
  42 {
  43   gchar *data;
  44   guint len;
  45 };
  46
  47 struct _GByteArray
  48 {
  49   guint8 *data;
  50   guint   len;
  51 };
  52
  53 struct _GPtrArray
  54 {
  55   gpointer *pdata;
  56   guint     len;
  57 };
  58
  59 /* Resizable arrays. remove fills any cleared spot and shortens the
  60  * array, while preserving the order. remove_fast will distort the
  61  * order by moving the last element to the position of the removed.
  62  */
  63
  64 #define g_array_append_val(a,v)   g_array_append_vals (a, &(v), 1)
  65 #define g_array_prepend_val(a,v)  g_array_prepend_vals (a, &(v), 1)
  66 #define g_array_insert_val(a,i,v) g_array_insert_vals (a, i, &(v), 1)
  67 #define g_array_index(a,t,i)      (((t*) (void *) (a)->data) [(i)])
  68
  69 GLIB_AVAILABLE_IN_ALL
  70 GArray* g_array_new               (gboolean          zero_terminated,
  71                                    gboolean          clear_,
  72                                    guint             element_size);
  73 GLIB_AVAILABLE_IN_ALL
  74 GArray* g_array_sized_new         (gboolean          zero_terminated,
  75                                    gboolean          clear_,
  76                                    guint             element_size,
  77                                    guint             reserved_size);
  78 GLIB_AVAILABLE_IN_ALL
  79 gchar*  g_array_free              (GArray           *array,
  80                                    gboolean          free_segment);
  81 GLIB_AVAILABLE_IN_ALL
  82 GArray *g_array_ref               (GArray           *array);
  83 GLIB_AVAILABLE_IN_ALL
  84 void    g_array_unref             (GArray           *array);
  85 GLIB_AVAILABLE_IN_ALL
  86 guint   g_array_get_element_size  (GArray           *array);
  87 GLIB_AVAILABLE_IN_ALL
  88 GArray* g_array_append_vals       (GArray           *array,
  89                                    gconstpointer     data,
  90                                    guint             len);
  91 GLIB_AVAILABLE_IN_ALL
  92 GArray* g_array_prepend_vals      (GArray           *array,
  93                                    gconstpointer     data,
  94                                    guint             len);
  95 GLIB_AVAILABLE_IN_ALL
  96 GArray* g_array_insert_vals       (GArray           *array,
  97                                    guint             index_,
  98                                    gconstpointer     data,
  99                                    guint             len);
 100 GLIB_AVAILABLE_IN_ALL
 101 GArray* g_array_set_size          (GArray           *array,
 102                                    guint             length);
 103 GLIB_AVAILABLE_IN_ALL
 104 GArray* g_array_remove_index      (GArray           *array,
 105                                    guint             index_);
 106 GLIB_AVAILABLE_IN_ALL
 107 GArray* g_array_remove_index_fast (GArray           *array,
 108                                    guint             index_);
 109 GLIB_AVAILABLE_IN_ALL
 110 GArray* g_array_remove_range      (GArray           *array,
 111                                    guint             index_,
 112                                    guint             length);
 113 GLIB_AVAILABLE_IN_ALL
 114 void    g_array_sort              (GArray           *array,
 115                                    GCompareFunc      compare_func);
 116 GLIB_AVAILABLE_IN_ALL
 117 void    g_array_sort_with_data    (GArray           *array,
 118                                    GCompareDataFunc  compare_func,
 119                                    gpointer          user_data);
 120 GLIB_AVAILABLE_IN_ALL
 121 void    g_array_set_clear_func    (GArray           *array,
 122                                    GDestroyNotify    clear_func);
 123
 124 /* Resizable pointer array.  This interface is much less complicated
 125  * than the above.  Add appends a pointer.  Remove fills any cleared
 126  * spot and shortens the array. remove_fast will again distort order.
 127  */
 128 #define    g_ptr_array_index(array,index_) ((array)->pdata)[index_]
 129 GLIB_AVAILABLE_IN_ALL
 130 GPtrArray* g_ptr_array_new                (void);
 131 GLIB_AVAILABLE_IN_ALL
 132 GPtrArray* g_ptr_array_new_with_free_func (GDestroyNotify    element_free_func);
 133 GLIB_AVAILABLE_IN_ALL
 134 GPtrArray* g_ptr_array_sized_new          (guint             reserved_size);
 135 GLIB_AVAILABLE_IN_ALL
 136 GPtrArray* g_ptr_array_new_full           (guint             reserved_size,
 137                                            GDestroyNotify    element_free_func);
 138 GLIB_AVAILABLE_IN_ALL
 139 gpointer*  g_ptr_array_free               (GPtrArray        *array,
 140                                            gboolean          free_seg);
 141 GLIB_AVAILABLE_IN_ALL
 142 GPtrArray* g_ptr_array_ref                (GPtrArray        *array);
 143 GLIB_AVAILABLE_IN_ALL
 144 void       g_ptr_array_unref              (GPtrArray        *array);
 145 GLIB_AVAILABLE_IN_ALL
 146 void       g_ptr_array_set_free_func      (GPtrArray        *array,
 147                                            GDestroyNotify    element_free_func);
 148 GLIB_AVAILABLE_IN_ALL
 149 void       g_ptr_array_set_size           (GPtrArray        *array,
 150                                            gint              length);
 151 GLIB_AVAILABLE_IN_ALL
 152 gpointer   g_ptr_array_remove_index       (GPtrArray        *array,
 153                                            guint             index_);
 154 GLIB_AVAILABLE_IN_ALL
 155 gpointer   g_ptr_array_remove_index_fast  (GPtrArray        *array,
 156                                            guint             index_);
 157 GLIB_AVAILABLE_IN_2_58
 158 gpointer   g_ptr_array_steal_index        (GPtrArray        *array,
 159                                            guint             index_);
 160 GLIB_AVAILABLE_IN_2_58
 161 gpointer   g_ptr_array_steal_index_fast   (GPtrArray        *array,
 162                                            guint             index_);
 163 GLIB_AVAILABLE_IN_ALL
 164 gboolean   g_ptr_array_remove             (GPtrArray        *array,
 165                                            gpointer          data);
 166 GLIB_AVAILABLE_IN_ALL
 167 gboolean   g_ptr_array_remove_fast        (GPtrArray        *array,
 168                                            gpointer          data);
 169 GLIB_AVAILABLE_IN_ALL
 170 GPtrArray *g_ptr_array_remove_range       (GPtrArray        *array,
 171                                            guint             index_,
 172                                            guint             length);
 173 GLIB_AVAILABLE_IN_ALL
 174 void       g_ptr_array_add                (GPtrArray        *array,
 175                                            gpointer          data);
 176 GLIB_AVAILABLE_IN_2_40
 177 void       g_ptr_array_insert             (GPtrArray        *array,
 178                                            gint              index_,
 179                                            gpointer          data);
 180 GLIB_AVAILABLE_IN_ALL
 181 void       g_ptr_array_sort               (GPtrArray        *array,
 182                                            GCompareFunc      compare_func);
 183 GLIB_AVAILABLE_IN_ALL
 184 void       g_ptr_array_sort_with_data     (GPtrArray        *array,
 185                                            GCompareDataFunc  compare_func,
 186                                            gpointer          user_data);
 187 GLIB_AVAILABLE_IN_ALL
 188 void       g_ptr_array_foreach            (GPtrArray        *array,
 189                                            GFunc             func,
 190                                            gpointer          user_data);
 191 GLIB_AVAILABLE_IN_2_54
 192 gboolean   g_ptr_array_find               (GPtrArray        *haystack,
 193                                            gconstpointer     needle,
 194                                            guint            *index_);
 195 GLIB_AVAILABLE_IN_2_54
 196 gboolean   g_ptr_array_find_with_equal_func (GPtrArray     *haystack,
 197                                              gconstpointer  needle,
 198                                              GEqualFunc     equal_func,
 199                                              guint         *index_);
 200
 201
 202 /* Byte arrays, an array of guint8.  Implemented as a GArray,
 203  * but type-safe.
 204  */
 205
 206 GLIB_AVAILABLE_IN_ALL
 207 GByteArray* g_byte_array_new               (void);
 208 GLIB_AVAILABLE_IN_ALL
 209 GByteArray* g_byte_array_new_take          (guint8           *data,
 210                                             gsize             len);
 211 GLIB_AVAILABLE_IN_ALL
 212 GByteArray* g_byte_array_sized_new         (guint             reserved_size);
 213 GLIB_AVAILABLE_IN_ALL
 214 guint8*     g_byte_array_free              (GByteArray       *array,
 215                                             gboolean          free_segment);
 216 GLIB_AVAILABLE_IN_ALL
 217 GBytes*     g_byte_array_free_to_bytes     (GByteArray       *array);
 218 GLIB_AVAILABLE_IN_ALL
 219 GByteArray *g_byte_array_ref               (GByteArray       *array);
 220 GLIB_AVAILABLE_IN_ALL
 221 void        g_byte_array_unref             (GByteArray       *array);
 222 GLIB_AVAILABLE_IN_ALL
 223 GByteArray* g_byte_array_append            (GByteArray       *array,
 224                                             const guint8     *data,
 225                                             guint             len);
 226 GLIB_AVAILABLE_IN_ALL
 227 GByteArray* g_byte_array_prepend           (GByteArray       *array,
 228                                             const guint8     *data,
 229                                             guint             len);
 230 GLIB_AVAILABLE_IN_ALL
 231 GByteArray* g_byte_array_set_size          (GByteArray       *array,
 232                                             guint             length);
 233 GLIB_AVAILABLE_IN_ALL
 234 GByteArray* g_byte_array_remove_index      (GByteArray       *array,
 235                                             guint             index_);
 236 GLIB_AVAILABLE_IN_ALL
 237 GByteArray* g_byte_array_remove_index_fast (GByteArray       *array,
 238                                             guint             index_);
 239 GLIB_AVAILABLE_IN_ALL
 240 GByteArray* g_byte_array_remove_range      (GByteArray       *array,
 241                                             guint             index_,
 242                                             guint             length);
 243 GLIB_AVAILABLE_IN_ALL
 244 void        g_byte_array_sort              (GByteArray       *array,
 245                                             GCompareFunc      compare_func);
 246 GLIB_AVAILABLE_IN_ALL
 247 void        g_byte_array_sort_with_data    (GByteArray       *array,
 248                                             GCompareDataFunc  compare_func,
 249                                             gpointer          user_data);
 250
 251 G_END_DECLS
 252
 253 #endif /* __G_ARRAY_H__ */