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