glib/glib.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 Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 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  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19 #ifndef __G_LIB_H__
  20 #define __G_LIB_H__
  21
  22 #include <glibconfig.h>
  23
  24 #ifdef USE_DMALLOC
  25 #include "dmalloc.h"
  26 #endif
  27
  28
  29 /* glib provides definitions for the extrema of many
  30  *  of the standard types. These are:
  31  * G_MINFLOAT
  32  * G_MAXFLOAT
  33  * G_MINDOUBLE
  34  * G_MAXDOUBLE
  35  * G_MINSHORT
  36  * G_MAXSHORT
  37  * G_MININT
  38  * G_MAXINT
  39  * G_MINLONG
  40  * G_MAXLONG
  41  */
  42
  43 #ifdef HAVE_FLOAT_H
  44
  45 #include <float.h>
  46
  47 #define G_MINFLOAT   FLT_MIN
  48 #define G_MAXFLOAT   FLT_MAX
  49 #define G_MINDOUBLE  DBL_MIN
  50 #define G_MAXDOUBLE  DBL_MAX
  51
  52 #elif HAVE_VALUES_H
  53
  54 #include <values.h>
  55
  56 #define G_MINFLOAT  MINFLOAT
  57 #define G_MAXFLOAT  MAXFLOAT
  58 #define G_MINDOUBLE MINDOUBLE
  59 #define G_MAXDOUBLE MAXDOUBLE
  60
  61 #endif /* HAVE_VALUES_H */
  62
  63
  64 #ifdef HAVE_LIMITS_H
  65
  66 #include <limits.h>
  67
  68 #define G_MINSHORT  SHRT_MIN
  69 #define G_MAXSHORT  SHRT_MAX
  70 #define G_MININT    INT_MIN
  71 #define G_MAXINT    INT_MAX
  72 #define G_MINLONG   LONG_MIN
  73 #define G_MAXLONG   LONG_MAX
  74
  75 #elif HAVE_VALUES_H
  76
  77 #ifdef HAVE_FLOAT_H
  78 #include <values.h>
  79 #endif /* HAVE_FLOAT_H */
  80
  81 #define G_MINSHORT  MINSHORT
  82 #define G_MAXSHORT  MAXSHORT
  83 #define G_MININT    MININT
  84 #define G_MAXINT    MAXINT
  85 #define G_MINLONG   MINLONG
  86 #define G_MAXLONG   MAXLONG
  87
  88 #endif /* HAVE_VALUES_H */
  89
  90
  91 /* Provide definitions for some commonly used macros.
  92  *  Some of them are only provided if they haven't already
  93  *  been defined. It is assumed that if they are already
  94  *  defined then the current definition is correct.
  95  */
  96 #ifndef NULL
  97 #define NULL    ((void*) 0)
  98 #endif
  99
 100 #ifndef FALSE
 101 #define FALSE   (0)
 102 #endif
 103
 104 #ifndef TRUE
 105 #define TRUE    (!FALSE)
 106 #endif
 107
 108 #undef  MAX
 109 #define MAX(a, b)  (((a) > (b)) ? (a) : (b))
 110
 111 #undef  MIN
 112 #define MIN(a, b)  (((a) < (b)) ? (a) : (b))
 113
 114 #undef  ABS
 115 #define ABS(a)     (((a) < 0) ? -(a) : (a))
 116
 117 #undef  CLAMP
 118 #define CLAMP(x, low, high)  (((x) > (high)) ? (high) : (((x) < (low)) ? (low) : (x)))
 119
 120
 121 /* Provide simple enum value macro wrappers that ease automated enum value
 122  * stringification code.
 123  */
 124 #if     !defined (G_CODE_GENERATION)
 125 #define G_ENUM( EnumerationName )               EnumerationName
 126 #define G_FLAGS( EnumerationName )              EnumerationName
 127 #define G_NV( VALUE_NAME , value_nick, VALUE)   VALUE_NAME = (VALUE)
 128 #define G_SV( VALUE_NAME, value_nick )          VALUE_NAME
 129 #else   /* G_CODE_GENERATION */
 130 #define G_ENUM( EnumerationName )               G_ENUM_E + EnumerationName +
 131 #define G_FLAGS( EnumerationName )              G_ENUM_F + EnumerationName +
 132 #define G_NV( VALUE_NAME , value_nick, VALUE)   G_ENUM_V + VALUE_NAME + value_nick +
 133 #define G_SV( VALUE_NAME, value_nick )          G_ENUM_V + VALUE_NAME + value_nick +
 134 #endif  /* G_CODE_GENERATION */
 135
 136
 137 /* Provide simple macro statement wrappers (adapted from Perl):
 138  *  G_STMT_START { statements; } G_STMT_END;
 139  *  can be used as a single statement, as in
 140  *  if (x) G_STMT_START { ... } G_STMT_END; else ...
 141  *
 142  *  For gcc we will wrap the statements within `({' and `})' braces.
 143  *  For SunOS they will be wrapped within `if (1)' and `else (void) 0',
 144  *  and otherwise within `do' and `while (0)'.
 145  */
 146 #if !(defined (G_STMT_START) && defined (G_STMT_END))
 147 #  if defined (__GNUC__) && !defined (__STRICT_ANSI__) && !defined (__cplusplus)
 148 #    define G_STMT_START        (void)(
 149 #    define G_STMT_END          )
 150 #  else
 151 #    if (defined (sun) || defined (__sun__))
 152 #      define G_STMT_START      if (1)
 153 #      define G_STMT_END        else (void)0
 154 #    else
 155 #      define G_STMT_START      do
 156 #      define G_STMT_END        while (0)
 157 #    endif
 158 #  endif
 159 #endif
 160
 161 /* Provide macros to feature the GCC function attribute.
 162  */
 163 #if     __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4)
 164 #define G_GNUC_PRINTF( format_idx, arg_idx )    \
 165   __attribute__((format (printf, format_idx, arg_idx)))
 166 #define G_GNUC_SCANF( format_idx, arg_idx )     \
 167   __attribute__((format (scanf, format_idx, arg_idx)))
 168 #define G_GNUC_FORMAT( arg_idx )                \
 169   __attribute__((format_arg (arg_idx)))
 170 #define G_GNUC_NORETURN                         \
 171   __attribute__((noreturn))
 172 #define G_GNUC_CONST                            \
 173   __attribute__((const))
 174 #else   /* !__GNUC__ */
 175 #define G_GNUC_PRINTF( format_idx, arg_idx )
 176 #define G_GNUC_SCANF( format_idx, arg_idx )
 177 #define G_GNUC_FORMAT( arg_idx )
 178 #define G_GNUC_NORETURN
 179 #define G_GNUC_CONST
 180 #endif  /* !__GNUC__ */
 181
 182 /* Hacker macro to place breakpoints for x86 machines.
 183  * Actual use is strongly deprecated of course ;)
 184  */
 185 #if     defined (__i386__)
 186 #define G_BREAKPOINT()          G_STMT_START{ __asm__ ("int $03"); }G_STMT_END
 187 #else   /* !__i386__ */
 188 #define G_BREAKPOINT()
 189 #endif  /* __i386__ */
 190
 191 /* Wrap the __PRETTY_FUNCTION__ and __FUNCTION__ variables with macros,
 192  * so we can refer to them as strings unconditionally.
 193  */
 194 #ifdef  __GNUC__
 195 #define G_GNUC_FUNCTION         (__FUNCTION__)
 196 #define G_GNUC_PRETTY_FUNCTION  (__PRETTY_FUNCTION__)
 197 #else   /* !__GNUC__ */
 198 #define G_GNUC_FUNCTION         ("")
 199 #define G_GNUC_PRETTY_FUNCTION  ("")
 200 #endif  /* !__GNUC__ */
 201
 202
 203 #ifndef ATEXIT
 204 #  ifdef HAVE_ATEXIT
 205 #    define ATEXIT(proc)   (atexit (proc))
 206 #  elif defined (HAVE_ON_EXIT)
 207 #    define ATEXIT(proc)   (on_exit ((void (*)(int, void *))(proc), NULL))
 208 #  endif
 209 #endif /* ATEXIT */
 210
 211
 212 /* Provide macros for easily allocating memory. The macros
 213  *  will cast the allocated memory to the specified type
 214  *  in order to avoid compiler warnings. (Makes the code neater).
 215  */
 216
 217 #ifdef __DMALLOC_H__
 218
 219 #define g_new(type,count)        ALLOC(type,count)
 220 #define g_new0(type,count)       CALLOC(type,count)
 221
 222 #else /* __DMALLOC_H__ */
 223
 224 #define g_new(type, count)        \
 225     ((type *) g_malloc ((unsigned) sizeof (type) * (count)))
 226 #define g_new0(type, count)       \
 227     ((type *) g_malloc0 ((unsigned) sizeof (type) * (count)))
 228 #endif /* __DMALLOC_H__ */
 229
 230 #define g_mem_chunk_create(type, pre_alloc, alloc_type) ( \
 231   g_mem_chunk_new (#type " mem chunks (" #pre_alloc ")", \
 232                    sizeof (type), \
 233                    sizeof (type) * (pre_alloc), \
 234                    (alloc_type)) \
 235 )
 236 #define g_chunk_new(type, chunk)        ( \
 237   (type *) g_mem_chunk_alloc (chunk) \
 238 )
 239 #define g_chunk_new0(type, chunk)       ( \
 240   (type *) memset (g_mem_chunk_alloc (chunk), 0, sizeof (type)) \
 241 )
 242 #define g_chunk_free(mem, mem_chunk)    G_STMT_START { \
 243   g_mem_chunk_free ((mem_chunk), (mem)); \
 244 } G_STMT_END
 245
 246 #define g_string(x) #x
 247
 248
 249 /* Provide macros for error handling. The "assert" macros will
 250  *  exit on failure. The "return" macros will exit the current
 251  *  function. Two different definitions are given for the macros
 252  *  in order to support gcc's __PRETTY_FUNCTION__ capability.
 253  */
 254
 255 #ifdef G_DISABLE_ASSERT
 256
 257 #define g_assert(expr)
 258 #define g_assert_not_reached()
 259
 260 #else /* !G_DISABLE_ASSERT */
 261
 262 #ifdef __GNUC__
 263
 264 #define g_assert(expr)                  G_STMT_START{\
 265      if (!(expr))                                    \
 266        g_error ("file %s: line %d (%s): \"%s\"",     \
 267                 __FILE__,                            \
 268                 __LINE__,                            \
 269                 __PRETTY_FUNCTION__,                 \
 270                 #expr);                 }G_STMT_END
 271
 272 #define g_assert_not_reached()          G_STMT_START{                 \
 273      g_error ("file %s: line %d (%s): \"should not be reached\"",     \
 274               __FILE__,                                               \
 275               __LINE__,                                               \
 276               __PRETTY_FUNCTION__);     }G_STMT_END
 277
 278 #else /* !__GNUC__ */
 279
 280 #define g_assert(expr)                  G_STMT_START{\
 281      if (!(expr))                                    \
 282        g_error ("file %s: line %d: \"%s\"",          \
 283                 __FILE__,                            \
 284                 __LINE__,                            \
 285                 #expr);                 }G_STMT_END
 286
 287 #define g_assert_not_reached()          G_STMT_START{                 \
 288      g_error ("file %s: line %d: \"should not be reached\"",          \
 289               __FILE__,                                               \
 290               __LINE__);                }G_STMT_END
 291
 292 #endif /* __GNUC__ */
 293
 294 #endif /* G_DISABLE_ASSERT */
 295
 296 #ifdef G_DISABLE_CHECKS
 297
 298 #define g_return_if_fail(expr)
 299 #define g_return_val_if_fail(expr,val)
 300
 301 #else /* !G_DISABLE_CHECKS */
 302
 303 #ifdef __GNUC__
 304
 305 #define g_return_if_fail(expr)          G_STMT_START{                  \
 306      if (!(expr))                                                      \
 307        {                                                               \
 308          g_warning ("file %s: line %d (%s): assertion \"%s\" failed.", \
 309                     __FILE__,                                          \
 310                     __LINE__,                                          \
 311                     __PRETTY_FUNCTION__,                               \
 312                     #expr);                                            \
 313          return;                                                       \
 314        };                               }G_STMT_END
 315
 316 #define g_return_val_if_fail(expr,val)  G_STMT_START{                  \
 317      if (!(expr))                                                      \
 318        {                                                               \
 319          g_warning ("file %s: line %d (%s): assertion \"%s\" failed.", \
 320                     __FILE__,                                          \
 321                     __LINE__,                                          \
 322                     __PRETTY_FUNCTION__,                               \
 323                     #expr);                                            \
 324          return val;                                                   \
 325        };                               }G_STMT_END
 326
 327 #else /* !__GNUC__ */
 328
 329 #define g_return_if_fail(expr)          G_STMT_START{             \
 330      if (!(expr))                                                 \
 331        {                                                          \
 332          g_warning ("file %s: line %d: assertion. \"%s\" failed", \
 333                     __FILE__,                                     \
 334                     __LINE__,                                     \
 335                     #expr);                                       \
 336          return;                                                  \
 337        };                               }G_STMT_END
 338
 339 #define g_return_val_if_fail(expr, val) G_STMT_START{             \
 340      if (!(expr))                                                 \
 341        {                                                          \
 342          g_warning ("file %s: line %d: assertion \"%s\" failed.", \
 343                     __FILE__,                                     \
 344                     __LINE__,                                     \
 345                     #expr);                                       \
 346          return val;                                              \
 347        };                               }G_STMT_END
 348
 349 #endif /* !__GNUC__ */
 350
 351 #endif /* G_DISABLE_CHECKS */
 352
 353
 354 #ifdef __cplusplus
 355 extern "C" {
 356 #pragma }
 357 #endif /* __cplusplus */
 358
 359 /* Provide type definitions for commonly used types.
 360  *  These are useful because a "gint8" can be adjusted
 361  *  to be 1 byte (8 bits) on all platforms. Similarly and
 362  *  more importantly, "gint32" can be adjusted to be
 363  *  4 bytes (32 bits) on all platforms.
 364  */
 365
 366 typedef char   gchar;
 367 typedef short  gshort;
 368 typedef long   glong;
 369 typedef int    gint;
 370 typedef gint   gboolean;
 371
 372 typedef unsigned char   guchar;
 373 typedef unsigned short  gushort;
 374 typedef unsigned long   gulong;
 375 typedef unsigned int    guint;
 376
 377 typedef float   gfloat;
 378 typedef double  gdouble;
 379
 380 /* HAVE_LONG_DOUBLE doesn't work correctly on all platforms.
 381  * Since gldouble isn't used anywhere, just disable it for now */
 382
 383 #if 0
 384 #ifdef HAVE_LONG_DOUBLE
 385 typedef long double gldouble;
 386 #else /* HAVE_LONG_DOUBLE */
 387 typedef double gldouble;
 388 #endif /* HAVE_LONG_DOUBLE */
 389 #endif /* 0 */
 390
 391 typedef void* gpointer;
 392 typedef const void *gconstpointer;
 393
 394 #if (SIZEOF_CHAR == 1)
 395 typedef signed char     gint8;
 396 typedef unsigned char   guint8;
 397 #endif /* SIZEOF_CHAR */
 398
 399
 400 #if (SIZEOF_SHORT == 2)
 401 typedef signed short    gint16;
 402 typedef unsigned short  guint16;
 403 #endif /* SIZEOF_SHORT */
 404
 405
 406 #if (SIZEOF_INT == 4)
 407 typedef signed int      gint32;
 408 typedef unsigned int    guint32;
 409 #elif (SIZEOF_LONG == 4)
 410 typedef signed long     gint32;
 411 typedef unsigned long   guint32;
 412 #endif /* SIZEOF_INT */
 413
 414 #if (SIZEOF_LONG == 8)
 415 #define HAVE_GINT64 1
 416 typedef signed long gint64;
 417 typedef unsigned long guint64;
 418 #elif (SIZEOF_LONG_LONG == 8)
 419 #define HAVE_GINT64 1
 420 typedef signed long long gint64;
 421 typedef unsigned long long guint64;
 422 #else
 423 /* No gint64 */
 424 #undef HAVE_GINT64
 425 #warning "No gint64 available"
 426 #endif
 427
 428
 429 /* Define macros for storing integers inside pointers */
 430
 431 #if (SIZEOF_INT == SIZEOF_VOID_P)
 432
 433 #define GPOINTER_TO_INT(p) ((gint)(p))
 434 #define GPOINTER_TO_UINT(p) ((guint)(p))
 435
 436 #define GINT_TO_POINTER(i) ((gpointer)(i))
 437 #define GUINT_TO_POINTER(u) ((gpointer)(u))
 438
 439 #elif (SIZEOF_LONG == SIZEOF_VOID_P)
 440
 441 #define GPOINTER_TO_INT(p) ((gint)(glong)(p))
 442 #define GPOINTER_TO_UINT(p) ((guint)(gulong)(p))
 443
 444 #define GINT_TO_POINTER(i) ((gpointer)(glong)(i))
 445 #define GUINT_TO_POINTER(u) ((gpointer)(gulong)(u))
 446
 447 #else
 448 /* This should never happen */
 449 #error "Unhandled SIZEOF_VOID_P"
 450 #endif
 451
 452 typedef gint32  gssize;
 453 typedef guint32 gsize;
 454 typedef guint32 GQuark;
 455 typedef gint32  GTime;
 456
 457 typedef struct _GList           GList;
 458 typedef struct _GSList          GSList;
 459 typedef struct _GHashTable      GHashTable;
 460 typedef struct _GCache          GCache;
 461 typedef struct _GTree           GTree;
 462 typedef struct _GTimer          GTimer;
 463 typedef struct _GMemChunk       GMemChunk;
 464 typedef struct _GListAllocator  GListAllocator;
 465 typedef struct _GStringChunk    GStringChunk;
 466 typedef struct _GString         GString;
 467 typedef struct _GArray          GArray;
 468 typedef struct _GPtrArray       GPtrArray;
 469 typedef struct _GByteArray      GByteArray;
 470 typedef struct _GDebugKey       GDebugKey;
 471 typedef struct _GScannerConfig  GScannerConfig;
 472 typedef struct _GScanner        GScanner;
 473 typedef union  _GValue          GValue;
 474 typedef struct _GCompletion     GCompletion;
 475 typedef struct _GRelation       GRelation;
 476 typedef struct _GTuples         GTuples;
 477 typedef struct _GNode           GNode;
 478
 479
 480 typedef void            (*GFunc)                (gpointer  data,
 481                                                  gpointer  user_data);
 482 typedef void            (*GHFunc)               (gpointer  key,
 483                                                  gpointer  value,
 484                                                  gpointer  user_data);
 485 typedef gpointer        (*GCacheNewFunc)        (gpointer  key);
 486 typedef gpointer        (*GCacheDupFunc)        (gpointer  value);
 487 typedef void            (*GCacheDestroyFunc)    (gpointer  value);
 488 typedef gint            (*GTraverseFunc)        (gpointer  key,
 489                                                  gpointer  value,
 490                                                  gpointer  data);
 491 typedef gboolean        (*GNodeTraverseFunc)    (GNode    *node,
 492                                                  gpointer  data);
 493 typedef void            (*GNodeForeachFunc)     (GNode    *node,
 494                                                  gpointer  data);
 495 typedef gint            (*GSearchFunc)          (gpointer  key,
 496                                                  gpointer  data);
 497 typedef void            (*GErrorFunc)           (gchar    *str);
 498 typedef void            (*GWarningFunc)         (gchar    *str);
 499 typedef void            (*GPrintFunc)           (gchar    *str);
 500 typedef void            (*GScannerMsgFunc)      (GScanner *scanner,
 501                                                  gchar    *message,
 502                                                  gint      error);
 503 typedef void            (*GDestroyNotify)       (gpointer  data);
 504
 505 typedef guint           (*GHashFunc)            (gconstpointer    key);
 506 typedef gint            (*GCompareFunc)         (gconstpointer    a,
 507                                                  gconstpointer    b);
 508 typedef gchar*          (*GCompletionFunc)      (gpointer);
 509
 510 struct _GList
 511 {
 512   gpointer data;
 513   GList *next;
 514   GList *prev;
 515 };
 516
 517 struct _GSList
 518 {
 519   gpointer data;
 520   GSList *next;
 521 };
 522
 523 struct _GString
 524 {
 525   gchar *str;
 526   gint len;
 527 };
 528
 529 struct _GArray
 530 {
 531   gchar *data;
 532   guint len;
 533 };
 534
 535 struct _GByteArray
 536 {
 537   guint8 *data;
 538   guint   len;
 539 };
 540
 541 struct _GPtrArray
 542 {
 543   gpointer *pdata;
 544   guint     len;
 545 };
 546
 547 struct _GTuples
 548 {
 549   guint len;
 550 };
 551
 552 struct _GDebugKey
 553 {
 554   gchar *key;
 555   guint  value;
 556 };
 557
 558 struct _GCache { gint dummy; };
 559 struct _GTree { gint dummy; };
 560 struct _GTimer { gint dummy; };
 561 struct _GMemChunk { gint dummy; };
 562 struct _GListAllocator { gint dummy; };
 563 struct _GStringChunk { gint dummy; };
 564
 565 typedef enum
 566 {
 567   G_IN_ORDER,
 568   G_PRE_ORDER,
 569   G_POST_ORDER,
 570   G_LEVEL_ORDER
 571 } GTraverseType;
 572
 573 typedef enum
 574 {
 575   G_TRAVERSE_LEAFS      = 1 << 0,
 576   G_TRAVERSE_NON_LEAFS  = 1 << 1,
 577   G_TRAVERSE_ALL        = G_TRAVERSE_LEAFS | G_TRAVERSE_NON_LEAFS,
 578   G_TRAVERSE_MASK       = 0x03
 579 } GTraverseFlags;
 580
 581 /* Doubly linked lists
 582  */
 583 GList* g_list_alloc             (void);
 584 void   g_list_free              (GList          *list);
 585 void   g_list_free_1            (GList          *list);
 586 GList* g_list_append            (GList          *list,
 587                                  gpointer        data);
 588 GList* g_list_prepend           (GList          *list,
 589                                  gpointer        data);
 590 GList* g_list_insert            (GList          *list,
 591                                  gpointer        data,
 592                                  gint            position);
 593 GList* g_list_insert_sorted     (GList          *list,
 594                                  gpointer        data,
 595                                  GCompareFunc    func);
 596 GList* g_list_concat            (GList          *list1,
 597                                  GList          *list2);
 598 GList* g_list_remove            (GList          *list,
 599                                  gpointer        data);
 600 GList* g_list_remove_link       (GList          *list,
 601                                  GList          *link);
 602 GList* g_list_reverse           (GList          *list);
 603 GList* g_list_nth               (GList          *list,
 604                                  guint           n);
 605 GList* g_list_find              (GList          *list,
 606                                  gpointer        data);
 607 GList* g_list_find_custom       (GList          *list,
 608                                  gpointer        data,
 609                                  GCompareFunc    func);
 610 gint   g_list_position          (GList          *list,
 611                                  GList          *link);
 612 gint   g_list_index             (GList          *list,
 613                                  gpointer        data);
 614 GList* g_list_last              (GList          *list);
 615 GList* g_list_first             (GList          *list);
 616 guint  g_list_length            (GList          *list);
 617 void   g_list_foreach           (GList          *list,
 618                                  GFunc           func,
 619                                  gpointer        user_data);
 620 gpointer g_list_nth_data        (GList          *list,
 621                                  guint           n);
 622
 623 #define g_list_previous(list)   ((list) ? (((GList *)(list))->prev) : NULL)
 624 #define g_list_next(list)       ((list) ? (((GList *)(list))->next) : NULL)
 625
 626 /* Singly linked lists
 627  */
 628 GSList* g_slist_alloc           (void);
 629 void    g_slist_free            (GSList         *list);
 630 void    g_slist_free_1          (GSList         *list);
 631 GSList* g_slist_append          (GSList         *list,
 632                                  gpointer        data);
 633 GSList* g_slist_prepend         (GSList         *list,
 634                                  gpointer        data);
 635 GSList* g_slist_insert          (GSList         *list,
 636                                  gpointer        data,
 637                                  gint            position);
 638 GSList* g_slist_insert_sorted   (GSList         *list,
 639                                  gpointer        data,
 640                                  GCompareFunc    func);
 641 GSList* g_slist_concat          (GSList         *list1,
 642                                  GSList         *list2);
 643 GSList* g_slist_remove          (GSList         *list,
 644                                  gpointer        data);
 645 GSList* g_slist_remove_link     (GSList         *list,
 646                                  GSList         *link);
 647 GSList* g_slist_reverse         (GSList         *list);
 648 GSList* g_slist_nth             (GSList         *list,
 649                                  guint           n);
 650 GSList* g_slist_find            (GSList         *list,
 651                                  gpointer        data);
 652 GSList* g_slist_find_custom     (GSList         *list,
 653                                  gpointer        data,
 654                                  GCompareFunc    func);
 655 gint    g_slist_position        (GSList         *list,
 656                                  GSList         *link);
 657 gint    g_slist_index           (GSList         *list,
 658                                  gpointer        data);
 659 GSList* g_slist_last            (GSList         *list);
 660 guint   g_slist_length          (GSList         *list);
 661 void    g_slist_foreach         (GSList         *list,
 662                                  GFunc           func,
 663                                  gpointer        user_data);
 664 gpointer g_slist_nth_data       (GSList         *list,
 665                                  guint           n);
 666
 667 #define g_slist_next(slist)     ((slist) ? (((GSList *)(slist))->next) : NULL)
 668
 669 /* List Allocators
 670  */
 671 GListAllocator* g_list_allocator_new  (void);
 672 void            g_list_allocator_free (GListAllocator* allocator);
 673 GListAllocator* g_slist_set_allocator (GListAllocator* allocator);
 674 GListAllocator* g_list_set_allocator  (GListAllocator* allocator);
 675
 676
 677 /* Hash tables
 678  */
 679 GHashTable* g_hash_table_new            (GHashFunc       hash_func,
 680                                          GCompareFunc    key_compare_func);
 681 void        g_hash_table_destroy        (GHashTable     *hash_table);
 682 void        g_hash_table_insert         (GHashTable     *hash_table,
 683                                          gpointer        key,
 684                                          gpointer        value);
 685 void        g_hash_table_remove         (GHashTable     *hash_table,
 686                                          gconstpointer   key);
 687 gpointer    g_hash_table_lookup         (GHashTable     *hash_table,
 688                                          gconstpointer   key);
 689 gboolean    g_hash_table_lookup_extended(GHashTable     *hash_table,
 690                                          gconstpointer   lookup_key,
 691                                          gpointer       *orig_key,
 692                                          gpointer       *value);
 693 void        g_hash_table_freeze         (GHashTable     *hash_table);
 694 void        g_hash_table_thaw           (GHashTable     *hash_table);
 695 void        g_hash_table_foreach        (GHashTable     *hash_table,
 696                                          GHFunc          func,
 697                                          gpointer        user_data);
 698 gint        g_hash_table_size           (GHashTable     *hash_table);
 699
 700
 701 /* Caches
 702  */
 703 GCache*  g_cache_new           (GCacheNewFunc      value_new_func,
 704                                 GCacheDestroyFunc  value_destroy_func,
 705                                 GCacheDupFunc      key_dup_func,
 706                                 GCacheDestroyFunc  key_destroy_func,
 707                                 GHashFunc          hash_key_func,
 708                                 GHashFunc          hash_value_func,
 709                                 GCompareFunc       key_compare_func);
 710 void     g_cache_destroy       (GCache            *cache);
 711 gpointer g_cache_insert        (GCache            *cache,
 712                                 gpointer           key);
 713 void     g_cache_remove        (GCache            *cache,
 714                                 gpointer           value);
 715 void     g_cache_key_foreach   (GCache            *cache,
 716                                 GHFunc             func,
 717                                 gpointer           user_data);
 718 void     g_cache_value_foreach (GCache            *cache,
 719                                 GHFunc             func,
 720                                 gpointer           user_data);
 721
 722
 723 /* Balanced binary trees
 724  */
 725 GTree*   g_tree_new      (GCompareFunc   key_compare_func);
 726 void     g_tree_destroy  (GTree         *tree);
 727 void     g_tree_insert   (GTree         *tree,
 728                           gpointer       key,
 729                           gpointer       value);
 730 void     g_tree_remove   (GTree         *tree,
 731                           gpointer       key);
 732 gpointer g_tree_lookup   (GTree         *tree,
 733                           gpointer       key);
 734 void     g_tree_traverse (GTree         *tree,
 735                           GTraverseFunc  traverse_func,
 736                           GTraverseType  traverse_type,
 737                           gpointer       data);
 738 gpointer g_tree_search   (GTree         *tree,
 739                           GSearchFunc    search_func,
 740                           gpointer       data);
 741 gint     g_tree_height   (GTree         *tree);
 742 gint     g_tree_nnodes   (GTree         *tree);
 743
 744
 745
 746 /* N-way tree implementation
 747  */
 748 struct _GNode
 749 {
 750   gpointer data;
 751   GNode *next;
 752   GNode *prev;
 753   GNode *parent;
 754   GNode *children;
 755 };
 756
 757 #define  G_NODE_IS_ROOT(node)   (((GNode*) (node))->parent == NULL && \
 758                                  ((GNode*) (node))->prev == NULL && \
 759                                  ((GNode*) (node))->next == NULL)
 760 #define  G_NODE_IS_LEAF(node)   (((GNode*) (node))->children == NULL)
 761
 762 GNode*   g_node_new             (gpointer          data);
 763 void     g_node_destroy         (GNode            *root);
 764 void     g_node_unlink          (GNode            *node);
 765 void     g_node_insert          (GNode            *parent,
 766                                  gint              position,
 767                                  GNode            *node);
 768 void     g_node_insert_before   (GNode            *parent,
 769                                  GNode            *sibling,
 770                                  GNode            *node);
 771 void     g_node_prepend         (GNode            *parent,
 772                                  GNode            *node);
 773 guint    g_node_n_nodes         (GNode            *root,
 774                                  GTraverseFlags    flags);
 775 GNode*   g_node_get_root        (GNode            *node);
 776 gboolean g_node_is_ancestor     (GNode            *node,
 777                                  GNode            *descendant);
 778 guint    g_node_depth           (GNode            *node);
 779 GNode*   g_node_find            (GNode            *root,
 780                                  GTraverseType     order,
 781                                  GTraverseFlags    flags,
 782                                  gpointer          data);
 783
 784 /* convenience macros */
 785 #define g_node_append(parent, node)     G_STMT_START { \
 786   g_node_insert_before ((parent), NULL, (node)); \
 787 } G_STMT_END
 788 #define g_node_insert_data(parent, position, data) G_STMT_START { \
 789   g_node_insert ((parent), (position), g_node_new ((data))); \
 790 } G_STMT_END
 791 #define g_node_insert_data_before(parent, sibling, data) G_STMT_START { \
 792   g_node_insert_before ((parent), (sibling), g_node_new ((data))); \
 793 } G_STMT_END
 794 #define g_node_prepend_data(parent, data)                G_STMT_START { \
 795   g_node_prepend ((parent), g_node_new ((data))); \
 796 } G_STMT_END
 797 #define g_node_append_data(parent, data) G_STMT_START { \
 798   g_node_insert_before ((parent), NULL, g_node_new ((data))); \
 799 } G_STMT_END
 800
 801 /* traversal function, assumes that `node' is root
 802  * (only traverses `node' and its subtree).
 803  * this function is just a high level interface to
 804  * low level traversal functions, optimized for speed.
 805  */
 806 void     g_node_traverse        (GNode            *root,
 807                                  GTraverseType     order,
 808                                  GTraverseFlags    flags,
 809                                  gint              max_depth,
 810                                  GNodeTraverseFunc func,
 811                                  gpointer          data);
 812
 813 /* return the maximum tree height starting with `node', this is an expensive
 814  * operation, since we need to visit all nodes. this could be shortened by
 815  * adding `guint height' to struct _GNode, but then again, this is not very
 816  * often needed, and would make g_node_insert() more time consuming.
 817  */
 818 guint    g_node_max_height       (GNode *root);
 819
 820 void     g_node_children_foreach (GNode           *node,
 821                                   GTraverseFlags   flags,
 822                                   GNodeForeachFunc func,
 823                                   gpointer         data);
 824 void     g_node_reverse_children (GNode           *node);
 825 guint    g_node_n_children       (GNode           *node);
 826 GNode*   g_node_nth_child        (GNode           *node,
 827                                   guint            n);
 828 GNode*   g_node_last_child       (GNode           *node);
 829 GNode*   g_node_find_child       (GNode           *node,
 830                                   GTraverseFlags   flags,
 831                                   gpointer         data);
 832 gint     g_node_child_position   (GNode           *node,
 833                                   GNode           *child);
 834 gint     g_node_child_index      (GNode           *node,
 835                                   gpointer         data);
 836
 837 GNode*   g_node_first_sibling    (GNode           *node);
 838 GNode*   g_node_last_sibling     (GNode           *node);
 839
 840 #define  g_node_prev_sibling(node)      ((node) ? \
 841                                          ((GNode*) (node))->prev : NULL)
 842 #define  g_node_next_sibling(node)      ((node) ? \
 843                                          ((GNode*) (node))->next : NULL)
 844 #define  g_node_first_child(node)       ((node) ? \
 845                                          ((GNode*) (node))->children : NULL)
 846
 847
 848
 849 /* Memory
 850  */
 851
 852 #ifdef USE_DMALLOC
 853
 854 #define g_malloc(size)       (gpointer) MALLOC(size)
 855 #define g_malloc0(size)      (gpointer) CALLOC(char,size)
 856 #define g_realloc(mem,size)  (gpointer) REALLOC(mem,char,size)
 857 #define g_free(mem)          FREE(mem)
 858
 859 #else /* USE_DMALLOC */
 860
 861 gpointer g_malloc      (gulong    size);
 862 gpointer g_malloc0     (gulong    size);
 863 gpointer g_realloc     (gpointer  mem,
 864                         gulong    size);
 865 void     g_free        (gpointer  mem);
 866
 867 #endif /* USE_DMALLOC */
 868
 869 void     g_mem_profile (void);
 870 void     g_mem_check   (gpointer  mem);
 871
 872
 873 /* "g_mem_chunk_new" creates a new memory chunk.
 874  * Memory chunks are used to allocate pieces of memory which are
 875  *  always the same size. Lists are a good example of such a data type.
 876  * The memory chunk allocates and frees blocks of memory as needed.
 877  *  Just be sure to call "g_mem_chunk_free" and not "g_free" on data
 878  *  allocated in a mem chunk. ("g_free" will most likely cause a seg
 879  *  fault...somewhere).
 880  *
 881  * Oh yeah, GMemChunk is an opaque data type. (You don't really
 882  *  want to know what's going on inside do you?)
 883  */
 884
 885 /* ALLOC_ONLY MemChunk's can only allocate memory. The free operation
 886  *  is interpreted as a no op. ALLOC_ONLY MemChunk's save 4 bytes per
 887  *  atom. (They are also useful for lists which use MemChunk to allocate
 888  *  memory but are also part of the MemChunk implementation).
 889  * ALLOC_AND_FREE MemChunk's can allocate and free memory.
 890  */
 891
 892 #define G_ALLOC_ONLY      1
 893 #define G_ALLOC_AND_FREE  2
 894
 895 GMemChunk* g_mem_chunk_new     (gchar     *name,
 896                                 gint       atom_size,
 897                                 gulong     area_size,
 898                                 gint       type);
 899 void       g_mem_chunk_destroy (GMemChunk *mem_chunk);
 900 gpointer   g_mem_chunk_alloc   (GMemChunk *mem_chunk);
 901 void       g_mem_chunk_free    (GMemChunk *mem_chunk,
 902                                 gpointer   mem);
 903 void       g_mem_chunk_clean   (GMemChunk *mem_chunk);
 904 void       g_mem_chunk_reset   (GMemChunk *mem_chunk);
 905 void       g_mem_chunk_print   (GMemChunk *mem_chunk);
 906 void       g_mem_chunk_info    (void);
 907
 908 /* Ah yes...we have a "g_blow_chunks" function.
 909  * "g_blow_chunks" simply compresses all the chunks. This operation
 910  *  consists of freeing every memory area that should be freed (but
 911  *  which we haven't gotten around to doing yet). And, no,
 912  *  "g_blow_chunks" doesn't follow the naming scheme, but it is a
 913  *  much better name than "g_mem_chunk_clean_all" or something
 914  *  similar.
 915  */
 916 void g_blow_chunks (void);
 917
 918
 919 /* Timer
 920  */
 921 GTimer* g_timer_new     (void);
 922 void    g_timer_destroy (GTimer  *timer);
 923 void    g_timer_start   (GTimer  *timer);
 924 void    g_timer_stop    (GTimer  *timer);
 925 void    g_timer_reset   (GTimer  *timer);
 926 gdouble g_timer_elapsed (GTimer  *timer,
 927                          gulong  *microseconds);
 928
 929
 930 /* Output
 931  */
 932 void g_error   (const gchar *format, ...) G_GNUC_PRINTF (1, 2);
 933 void g_warning (const gchar *format, ...) G_GNUC_PRINTF (1, 2);
 934 void g_message (const gchar *format, ...) G_GNUC_PRINTF (1, 2);
 935 void g_print   (const gchar *format, ...) G_GNUC_PRINTF (1, 2);
 936
 937
 938 /* String utility functions
 939  */
 940 #define G_STR_DELIMITERS     "_-|> <."
 941 void    g_strdelimit            (gchar       *string,
 942                                  const gchar *delimiters,
 943                                  gchar        new_delimiter);
 944 gchar*  g_strdup                (const gchar *str);
 945 gchar*  g_strconcat             (const gchar *string1,
 946                                  ...); /* NULL terminated */
 947 gdouble g_strtod                (const gchar *nptr,
 948                                  gchar      **endptr);
 949 gchar*  g_strerror              (gint         errnum);
 950 gchar*  g_strsignal             (gint         signum);
 951 gint    g_strcasecmp            (const gchar *s1,
 952                                  const gchar *s2);
 953 void    g_strdown               (gchar       *string);
 954 void    g_strup                 (gchar       *string);
 955 void    g_strreverse            (gchar       *string);
 956
 957
 958 /* Retrive static info
 959  */
 960 gchar*  g_get_user_name         (void);
 961 gchar*  g_get_real_name         (void);
 962 gchar*  g_get_home_dir          (void);
 963 gchar*  g_get_tmp_dir           (void);
 964 gchar*  g_get_prgname           (void);
 965 void    g_set_prgname           (const gchar *prgname);
 966
 967
 968 /* Miscellaneous utility functions
 969  */
 970 guint   g_parse_debug_string    (const gchar *string,
 971                                  GDebugKey   *keys,
 972                                  guint        nkeys);
 973 gint    g_snprintf              (gchar       *string,
 974                                  gulong       n,
 975                                  gchar const *format,
 976                                  ...) G_GNUC_PRINTF (3, 4);
 977 gchar*  g_basename              (const gchar *file_name);
 978
 979 /* strings are newly allocated with g_malloc() */
 980 gchar*  g_dirname               (const gchar *file_name);
 981 gchar*  g_get_current_dir       (void);
 982
 983
 984 /* We make the assumption that if memmove isn't available, then
 985  * bcopy will do the job. This isn't safe everywhere. (bcopy can't
 986  * necessarily handle overlapping copies) */
 987 #ifdef HAVE_MEMMOVE
 988 #define g_memmove memmove
 989 #else
 990 #define g_memmove(a,b,c)        bcopy((b), (a), (c))
 991 #endif
 992
 993 /* Errors
 994  */
 995 GErrorFunc   g_set_error_handler   (GErrorFunc   func);
 996 GWarningFunc g_set_warning_handler (GWarningFunc func);
 997 GPrintFunc   g_set_message_handler (GPrintFunc func);
 998 GPrintFunc   g_set_print_handler   (GPrintFunc func);
 999
1000 void g_debug          (const gchar *progname);
1001 void g_attach_process (const gchar *progname,
1002                        gint         query);
1003 void g_stack_trace    (const gchar *progname,
1004                        gint         query);
1005
1006
1007
1008 /* String Chunks
1009  */
1010 GStringChunk* g_string_chunk_new           (gint size);
1011 void          g_string_chunk_free          (GStringChunk *chunk);
1012 gchar*        g_string_chunk_insert        (GStringChunk *chunk,
1013                                             const gchar  *string);
1014 gchar*        g_string_chunk_insert_const  (GStringChunk *chunk,
1015                                             const gchar  *string);
1016
1017 /* Strings
1018  */
1019 GString* g_string_new       (const gchar *init);
1020 GString* g_string_sized_new (guint        dfl_size);
1021 void     g_string_free      (GString     *string,
1022                              gint         free_segment);
1023 GString* g_string_assign    (GString     *lval,
1024                              const gchar *rval);
1025 GString* g_string_truncate  (GString     *string,
1026                              gint         len);
1027 GString* g_string_append    (GString     *string,
1028                              const gchar *val);
1029 GString* g_string_append_c  (GString     *string,
1030                              gchar        c);
1031 GString* g_string_prepend   (GString     *string,
1032                              const gchar *val);
1033 GString* g_string_prepend_c (GString     *string,
1034                              gchar        c);
1035 GString* g_string_insert    (GString     *string,
1036                              gint         pos,
1037                              const gchar *val);
1038 GString* g_string_insert_c  (GString     *string,
1039                              gint         pos,
1040                              gchar        c);
1041 GString* g_string_erase     (GString     *string,
1042                              gint         pos,
1043                              gint         len);
1044 GString* g_string_down      (GString     *string);
1045 GString* g_string_up        (GString     *string);
1046 void     g_string_sprintf   (GString     *string,
1047                              const gchar *format,
1048                              ...) G_GNUC_PRINTF (2, 3);
1049 void     g_string_sprintfa  (GString     *string,
1050                              const gchar *format,
1051                              ...) G_GNUC_PRINTF (2, 3);
1052
1053 /* Resizable arrays
1054  */
1055 #define g_array_length(array,type) \
1056      (((array)->len)/sizeof(type))
1057 #define g_array_append_val(array,type,val) \
1058      g_rarray_append (array, (gpointer) &val, sizeof (type))
1059 #define g_array_append_vals(array,type,vals,nvals) \
1060      g_rarray_append (array, (gpointer) vals, sizeof (type) * nvals)
1061 #define g_array_prepend_val(array,type,val) \
1062      g_rarray_prepend (array, (gpointer) &val, sizeof (type))
1063 #define g_array_prepend_vals(array,type,vals,nvals) \
1064      g_rarray_prepend (array, (gpointer) vals, sizeof (type) * nvals)
1065 #define g_array_truncate(array,type,length) \
1066      g_rarray_truncate (array, length, sizeof (type))
1067 #define g_array_index(array,type,index) \
1068      ((type*) array->data)[index]
1069
1070 GArray* g_array_new       (gint      zero_terminated);
1071 void    g_array_free      (GArray   *array,
1072                            gint      free_segment);
1073 GArray* g_rarray_append   (GArray   *array,
1074                            gpointer  data,
1075                            gint      size);
1076 GArray* g_rarray_prepend  (GArray   *array,
1077                            gpointer  data,
1078                            gint      size);
1079 GArray* g_rarray_truncate (GArray   *array,
1080                            gint      length,
1081                            gint      size);
1082
1083 /* Resizable pointer array.  This interface is much less complicated
1084  * than the above.  Add appends appends a pointer.  Remove fills any
1085  * cleared spot and shortens the array.
1086  */
1087
1088 #define     g_ptr_array_index(array,index) (array->pdata)[index]
1089
1090 GPtrArray*  g_ptr_array_new                (void);
1091 void        g_ptr_array_free               (GPtrArray   *array,
1092                                             gboolean     free_seg);
1093 void        g_ptr_array_set_size           (GPtrArray   *array,
1094                                             gint         length);
1095 void        g_ptr_array_remove_index       (GPtrArray   *array,
1096                                             gint         index);
1097 gboolean    g_ptr_array_remove             (GPtrArray   *array,
1098                                             gpointer     data);
1099 void        g_ptr_array_add                (GPtrArray   *array,
1100                                             gpointer     data);
1101
1102 /* Byte arrays, an array of guint8.  Implemented as a GArray,
1103  * but type-safe.
1104  */
1105
1106 GByteArray* g_byte_array_new      (void);
1107 void        g_byte_array_free     (GByteArray *array,
1108                                    gint        free_segment);
1109
1110 GByteArray* g_byte_array_append   (GByteArray   *array,
1111                                    const guint8 *data,
1112                                    guint         len);
1113
1114 GByteArray* g_byte_array_prepend  (GByteArray   *array,
1115                                    const guint8 *data,
1116                                    guint         len);
1117
1118 GByteArray* g_byte_array_truncate (GByteArray *array,
1119                                    gint        length);
1120
1121
1122 /* Hash Functions
1123  */
1124 gint  g_str_equal (gconstpointer   v,
1125                    gconstpointer   v2);
1126 guint g_str_hash  (gconstpointer v);
1127
1128 gint  g_int_equal (gconstpointer v,
1129                    gconstpointer v2);
1130 guint g_int_hash  (gconstpointer v);
1131
1132 /* This "hash" function will just return the key's adress as an
1133  * unsigned integer. Useful for hashing on plain adresses or
1134  * simple integer values.
1135  */
1136 guint g_direct_hash  (gconstpointer v);
1137 gint  g_direct_equal (gconstpointer v,
1138                       gconstpointer v2);
1139
1140
1141 /* Quarks (string<->id association)
1142  */
1143 GQuark    g_quark_try_string            (const gchar    *string);
1144 GQuark    g_quark_from_static_string    (const gchar    *string);
1145 GQuark    g_quark_from_string           (const gchar    *string);
1146 gchar*    g_quark_to_string             (GQuark          quark);
1147
1148 /* Location Associated Data
1149  */
1150 void      g_dataset_destroy             (gconstpointer   dataset_location);
1151 gpointer  g_dataset_id_get_data         (gconstpointer   dataset_location,
1152                                          GQuark          key_id);
1153 void      g_dataset_id_set_data_full    (gconstpointer   dataset_location,
1154                                          GQuark          key_id,
1155                                          gpointer        data,
1156                                          GDestroyNotify  destroy_func);
1157 void      g_dataset_id_set_destroy      (gconstpointer   dataset_location,
1158                                          GQuark          key_id,
1159                                          GDestroyNotify  destroy_func);
1160
1161 #define   g_dataset_id_set_data(l,k,d)  G_STMT_START{g_dataset_id_set_data_full((l),(k),(d),NULL);}G_STMT_END
1162 #define   g_dataset_id_remove_data(l,k) G_STMT_START{g_dataset_id_set_data((l),(k),NULL);}G_STMT_END
1163 #define   g_dataset_get_data(l,k)       (g_dataset_id_get_data((l),g_quark_try_string(k)))
1164 #define   g_dataset_set_data_full(l,k,d,f) G_STMT_START{g_dataset_id_set_data_full((l),g_quark_from_string(k),(d),(f));}G_STMT_END
1165 #define   g_dataset_set_destroy(l,k,f)  G_STMT_START{g_dataset_id_set_destroy((l),g_quark_from_string(k),(f));}G_STMT_END
1166 #define   g_dataset_set_data(l,k,d)     G_STMT_START{g_dataset_set_data_full((l),(k),(d),NULL);}G_STMT_END
1167 #define   g_dataset_remove_data(l,k)    G_STMT_START{g_dataset_set_data((l),(k),NULL);}G_STMT_END
1168
1169
1170 /* GScanner: Flexible lexical scanner for general purpose.
1171  */
1172
1173 /* Character sets */
1174 #define G_CSET_A_2_Z    "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
1175 #define G_CSET_a_2_z    "abcdefghijklmnopqrstuvwxyz"
1176 #define G_CSET_LATINC   "\300\301\302\303\304\305\306"\
1177                         "\307\310\311\312\313\314\315\316\317\320"\
1178                         "\321\322\323\324\325\326"\
1179                         "\330\331\332\333\334\335\336"
1180 #define G_CSET_LATINS   "\337\340\341\342\343\344\345\346"\
1181                         "\347\350\351\352\353\354\355\356\357\360"\
1182                         "\361\362\363\364\365\366"\
1183                         "\370\371\372\373\374\375\376\377"
1184
1185 /* Error types */
1186 typedef enum
1187 {
1188   G_ERR_UNKNOWN,
1189   G_ERR_UNEXP_EOF,
1190   G_ERR_UNEXP_EOF_IN_STRING,
1191   G_ERR_UNEXP_EOF_IN_COMMENT,
1192   G_ERR_NON_DIGIT_IN_CONST,
1193   G_ERR_DIGIT_RADIX,
1194   G_ERR_FLOAT_RADIX,
1195   G_ERR_FLOAT_MALFORMED
1196 } GErrorType;
1197
1198 /* Token types */
1199 typedef enum
1200 {
1201   G_TOKEN_EOF                   =   0,
1202
1203   G_TOKEN_LEFT_PAREN            = '(',
1204   G_TOKEN_RIGHT_PAREN           = ')',
1205   G_TOKEN_LEFT_CURLY            = '{',
1206   G_TOKEN_RIGHT_CURLY           = '}',
1207   G_TOKEN_LEFT_BRACE            = '[',
1208   G_TOKEN_RIGHT_BRACE           = ']',
1209   G_TOKEN_EQUAL_SIGN            = '=',
1210   G_TOKEN_COMMA                 = ',',
1211
1212   G_TOKEN_NONE                  = 256,
1213
1214   G_TOKEN_ERROR,
1215
1216   G_TOKEN_CHAR,
1217   G_TOKEN_BINARY,
1218   G_TOKEN_OCTAL,
1219   G_TOKEN_INT,
1220   G_TOKEN_HEX,
1221   G_TOKEN_FLOAT,
1222   G_TOKEN_STRING,
1223
1224   G_TOKEN_SYMBOL,
1225   G_TOKEN_IDENTIFIER,
1226   G_TOKEN_IDENTIFIER_NULL,
1227
1228   G_TOKEN_COMMENT_SINGLE,
1229   G_TOKEN_COMMENT_MULTI,
1230   G_TOKEN_LAST
1231 } GTokenType;
1232
1233 union   _GValue
1234 {
1235   gpointer      v_symbol;
1236   gchar         *v_identifier;
1237   gulong        v_binary;
1238   gulong        v_octal;
1239   gulong        v_int;
1240   gdouble       v_float;
1241   gulong        v_hex;
1242   gchar         *v_string;
1243   gchar         *v_comment;
1244   guchar        v_char;
1245   guint         v_error;
1246 };
1247
1248 struct  _GScannerConfig
1249 {
1250   /* Character sets
1251    */
1252   gchar         *cset_skip_characters;          /* default: " \t\n" */
1253   gchar         *cset_identifier_first;
1254   gchar         *cset_identifier_nth;
1255   gchar         *cpair_comment_single;          /* default: "#\n" */
1256
1257   /* Should symbol lookup work case sensitive?
1258    */
1259   guint         case_sensitive : 1;
1260
1261   /* Boolean values to be adjusted "on the fly"
1262    * to configure scanning behaviour.
1263    */
1264   guint         skip_comment_multi : 1;         /* C like comment */
1265   guint         skip_comment_single : 1;        /* single line comment */
1266   guint         scan_comment_multi : 1;         /* scan multi line comments? */
1267   guint         scan_identifier : 1;
1268   guint         scan_identifier_1char : 1;
1269   guint         scan_identifier_NULL : 1;
1270   guint         scan_symbols : 1;
1271   guint         scan_binary : 1;
1272   guint         scan_octal : 1;
1273   guint         scan_float : 1;
1274   guint         scan_hex : 1;                   /* `0x0ff0' */
1275   guint         scan_hex_dollar : 1;            /* `$0ff0' */
1276   guint         scan_string_sq : 1;             /* string: 'anything' */
1277   guint         scan_string_dq : 1;             /* string: "\\-escapes!\n" */
1278   guint         numbers_2_int : 1;              /* bin, octal, hex => int */
1279   guint         int_2_float : 1;                /* int => G_TOKEN_FLOAT? */
1280   guint         identifier_2_string : 1;
1281   guint         char_2_token : 1;               /* return G_TOKEN_CHAR? */
1282   guint         symbol_2_token : 1;
1283   guint         scope_0_fallback : 1;           /* try scope 0 on lookups? */
1284 };
1285
1286 struct  _GScanner
1287 {
1288   /* unused fields */
1289   gpointer              user_data;
1290   guint                 max_parse_errors;
1291
1292   /* g_scanner_error() increments this field */
1293   guint                 parse_errors;
1294
1295   /* name of input stream, featured by the default message handler */
1296   const gchar           *input_name;
1297
1298   /* data pointer for derived structures */
1299   gpointer              derived_data;
1300
1301   /* link into the scanner configuration */
1302   GScannerConfig        *config;
1303
1304   /* fields filled in after g_scanner_get_next_token() */
1305   GTokenType            token;
1306   GValue                value;
1307   guint                 line;
1308   guint                 position;
1309
1310   /* fields filled in after g_scanner_peek_next_token() */
1311   GTokenType            next_token;
1312   GValue                next_value;
1313   guint                 next_line;
1314   guint                 next_position;
1315
1316   /* to be considered private */
1317   GHashTable            *symbol_table;
1318   const gchar           *text;
1319   guint                 text_len;
1320   gint                  input_fd;
1321   gint                  peeked_char;
1322   guint                 scope_id;
1323
1324   /* handler function for _warn and _error */
1325   GScannerMsgFunc       msg_handler;
1326 };
1327
1328 GScanner*       g_scanner_new                   (GScannerConfig *config_templ);
1329 void            g_scanner_destroy               (GScanner       *scanner);
1330 void            g_scanner_input_file            (GScanner       *scanner,
1331                                                  gint           input_fd);
1332 void            g_scanner_input_text            (GScanner       *scanner,
1333                                                  const  gchar   *text,
1334                                                  guint          text_len);
1335 GTokenType      g_scanner_get_next_token        (GScanner       *scanner);
1336 GTokenType      g_scanner_peek_next_token       (GScanner       *scanner);
1337 GTokenType      g_scanner_cur_token             (GScanner       *scanner);
1338 GValue          g_scanner_cur_value             (GScanner       *scanner);
1339 guint           g_scanner_cur_line              (GScanner       *scanner);
1340 guint           g_scanner_cur_position          (GScanner       *scanner);
1341 gboolean        g_scanner_eof                   (GScanner       *scanner);
1342 guint           g_scanner_set_scope             (GScanner       *scanner,
1343                                                  guint           scope_id);
1344 void            g_scanner_scope_add_symbol      (GScanner       *scanner,
1345                                                  guint           scope_id,
1346                                                  const gchar    *symbol,
1347                                                  gpointer       value);
1348 void            g_scanner_scope_remove_symbol   (GScanner       *scanner,
1349                                                  guint           scope_id,
1350                                                  const gchar    *symbol);
1351 gpointer        g_scanner_scope_lookup_symbol   (GScanner       *scanner,
1352                                                  guint           scope_id,
1353                                                  const gchar    *symbol);
1354 void            g_scanner_scope_foreach_symbol  (GScanner       *scanner,
1355                                                  guint           scope_id,
1356                                                  GHFunc          func,
1357                                                  gpointer        func_data);
1358 gpointer        g_scanner_lookup_symbol         (GScanner       *scanner,
1359                                                  const gchar    *symbol);
1360 void            g_scanner_freeze_symbol_table   (GScanner       *scanner);
1361 void            g_scanner_thaw_symbol_table     (GScanner       *scanner);
1362 void            g_scanner_unexp_token           (GScanner       *scanner,
1363                                                  GTokenType     expected_token,
1364                                                  const gchar    *identifier_spec,
1365                                                  const gchar    *symbol_spec,
1366                                                  const gchar    *symbol_name,
1367                                                  const gchar    *message,
1368                                                  gint            is_error);
1369 void            g_scanner_error                 (GScanner       *scanner,
1370                                                  const gchar    *format,
1371                                                  ...) G_GNUC_PRINTF (2,3);
1372 void            g_scanner_warn                  (GScanner       *scanner,
1373                                                  const gchar    *format,
1374                                                  ...) G_GNUC_PRINTF (2,3);
1375 gint            g_scanner_stat_mode             (const gchar    *filename);
1376 /* keep downward source compatibility */
1377 #define         g_scanner_add_symbol( scanner, symbol, value )  G_STMT_START { \
1378   g_scanner_scope_add_symbol ((scanner), 0, (symbol), (value)); \
1379 } G_STMT_END
1380 #define         g_scanner_remove_symbol( scanner, symbol )      G_STMT_START { \
1381   g_scanner_scope_remove_symbol ((scanner), 0, (symbol)); \
1382 } G_STMT_END
1383 #define         g_scanner_foreach_symbol( scanner, func, data ) G_STMT_START { \
1384   g_scanner_scope_foreach_symbol ((scanner), 0, (func), (data)); \
1385 } G_STMT_END
1386
1387
1388
1389 /* Completion */
1390
1391 struct _GCompletion
1392 {
1393   GList* items;
1394   GCompletionFunc func;
1395
1396   gchar* prefix;
1397   GList* cache;
1398 };
1399
1400 GCompletion* g_completion_new          (GCompletionFunc func);
1401 void         g_completion_add_items    (GCompletion*    cmp,
1402                                         GList*          items);
1403 void         g_completion_remove_items (GCompletion*    cmp,
1404                                         GList*          items);
1405 void         g_completion_clear_items  (GCompletion*    cmp);
1406 GList*       g_completion_complete     (GCompletion*    cmp,
1407                                         gchar*          prefix,
1408                                         gchar**         new_prefix);
1409 void         g_completion_free         (GCompletion*    cmp);
1410
1411
1412 /* GRelation: Indexed Relations.  Imagine a really simple table in a
1413  * database.  Relations are not ordered.  This data type is meant for
1414  * maintaining a N-way mapping.
1415  *
1416  * g_relation_new() creates a relation with FIELDS fields
1417  *
1418  * g_relation_destroy() frees all resources
1419  * g_tuples_destroy() frees the result of g_relation_select()
1420  *
1421  * g_relation_index() indexes relation FIELD with the provided
1422  *   equality and hash functions.  this must be done before any
1423  *   calls to insert are made.
1424  *
1425  * g_relation_insert() inserts a new tuple.  you are expected to
1426  *   provide the right number of fields.
1427  *
1428  * g_relation_delete() deletes all relations with KEY in FIELD
1429  * g_relation_select() returns ...
1430  * g_relation_count() counts ...
1431  */
1432
1433 GRelation* g_relation_new     (gint         fields);
1434 void       g_relation_destroy (GRelation   *relation);
1435 void       g_relation_index   (GRelation   *relation,
1436                                gint         field,
1437                                GHashFunc    hash_func,
1438                                GCompareFunc key_compare_func);
1439 void       g_relation_insert  (GRelation   *relation,
1440                                ...);
1441 gint       g_relation_delete  (GRelation   *relation,
1442                                gconstpointer  key,
1443                                gint         field);
1444 GTuples*   g_relation_select  (GRelation   *relation,
1445                                gconstpointer  key,
1446                                gint         field);
1447 gint       g_relation_count   (GRelation   *relation,
1448                                gconstpointer  key,
1449                                gint         field);
1450 gboolean   g_relation_exists  (GRelation   *relation,
1451                                ...);
1452 void       g_relation_print   (GRelation   *relation);
1453
1454 void       g_tuples_destroy   (GTuples     *tuples);
1455 gpointer   g_tuples_index     (GTuples     *tuples,
1456                                gint         index,
1457                                gint         field);
1458
1459
1460 /* Glib version.
1461  */
1462 extern const guint glib_major_version;
1463 extern const guint glib_minor_version;
1464 extern const guint glib_micro_version;
1465 extern const guint glib_interface_age;
1466 extern const guint glib_binary_age;
1467
1468 #ifdef __cplusplus
1469 }
1470 #endif /* __cplusplus */
1471
1472
1473 #endif /* __G_LIB_H__ */