glib/docs.c

   1 /*
   2  * Copyright © 2011 Red Hat, Inc
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-or-later
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  *
  19  * Author: Matthias Clasen
  20  */
  21
  22
  23 /* This file collects documentation for macros, typedefs and
  24  * the like, which have no good home in any of the 'real' source
  25  * files.
  26  */
  27
  28 /* Basic types {{{1 */
  29
  30 /**
  31  * SECTION:types
  32  * @title: Basic Types
  33  * @short_description: standard GLib types, defined for ease-of-use
  34  *     and portability
  35  *
  36  * GLib defines a number of commonly used types, which can be divided
  37  * into several groups:
  38  * - New types which are not part of standard C (but are defined in
  39  *   various C standard library header files) — #gboolean, #gssize.
  40  * - Integer types which are guaranteed to be the same size across
  41  *   all platforms — #gint8, #guint8, #gint16, #guint16, #gint32,
  42  *   #guint32, #gint64, #guint64.
  43  * - Types which are easier to use than their standard C counterparts -
  44  *   #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
  45  * - Types which correspond exactly to standard C types, but are
  46  *   included for completeness — #gchar, #gint, #gshort, #glong,
  47  *   #gfloat, #gdouble.
  48  * - Types which correspond exactly to standard C99 types, but are available
  49  *   to use even if your compiler does not support C99 — #gsize, #goffset,
  50  *   #gintptr, #guintptr.
  51  *
  52  * GLib also defines macros for the limits of some of the standard
  53  * integer and floating point types, as well as macros for suitable
  54  * printf() formats for these types.
  55  *
  56  * Note that depending on the platform and build configuration, the format
  57  * macros might not be compatible with the system provided printf() function,
  58  * because GLib might use a different printf() implementation internally.
  59  * The format macros will always work with GLib API (like g_print()), and with
  60  * any C99 compatible printf() implementation.
  61  */
  62
  63 /**
  64  * gboolean:
  65  *
  66  * A standard boolean type.
  67  * Variables of this type should only contain the value
  68  * %TRUE or %FALSE.
  69  *
  70  * Never directly compare the contents of a #gboolean variable with the values
  71  * %TRUE or %FALSE. Use `if (condition)` to check a #gboolean is "true", instead
  72  * of `if (condition == TRUE)`. Likewise use `if (!condition)` to check a
  73  * #gboolean is "false".
  74  *
  75  * There is no validation when assigning to a #gboolean variable and so it could
  76  * contain any value represented by a #gint. This is why the use of `if
  77  * (condition)` is recommended. All non-zero values in C evaluate to "true".
  78  */
  79
  80 /**
  81  * gpointer:
  82  *
  83  * An untyped pointer.
  84  * #gpointer looks better and is easier to use than void*.
  85  */
  86
  87 /**
  88  * gconstpointer:
  89  *
  90  * An untyped pointer to constant data.
  91  * The data pointed to should not be changed.
  92  *
  93  * This is typically used in function prototypes to indicate
  94  * that the data pointed to will not be altered by the function.
  95  */
  96
  97 /**
  98  * gchar:
  99  *
 100  * Corresponds to the standard C char type.
 101  */
 102
 103 /**
 104  * guchar:
 105  *
 106  * Corresponds to the standard C unsigned char type.
 107  */
 108
 109 /**
 110  * gint:
 111  *
 112  * Corresponds to the standard C int type.
 113  * Values of this type can range from %G_MININT to %G_MAXINT.
 114  */
 115
 116 /**
 117  * G_MININT:
 118  *
 119  * The minimum value which can be held in a #gint.
 120  */
 121
 122 /**
 123  * G_MAXINT:
 124  *
 125  * The maximum value which can be held in a #gint.
 126  */
 127
 128 /**
 129  * guint:
 130  *
 131  * Corresponds to the standard C unsigned int type.
 132  * Values of this type can range from 0 to %G_MAXUINT.
 133  */
 134
 135 /**
 136  * G_MAXUINT:
 137  *
 138  * The maximum value which can be held in a #guint.
 139  */
 140
 141 /**
 142  * gshort:
 143  *
 144  * Corresponds to the standard C short type.
 145  * Values of this type can range from %G_MINSHORT to %G_MAXSHORT.
 146  */
 147
 148 /**
 149  * G_MINSHORT:
 150  *
 151  * The minimum value which can be held in a #gshort.
 152  */
 153
 154 /**
 155  * G_MAXSHORT:
 156  *
 157  * The maximum value which can be held in a #gshort.
 158  */
 159
 160 /**
 161  * gushort:
 162  *
 163  * Corresponds to the standard C unsigned short type.
 164  * Values of this type can range from 0 to %G_MAXUSHORT.
 165  */
 166
 167 /**
 168  * G_MAXUSHORT:
 169  *
 170  * The maximum value which can be held in a #gushort.
 171  */
 172
 173 /**
 174  * glong:
 175  *
 176  * Corresponds to the standard C long type.
 177  * Values of this type can range from %G_MINLONG to %G_MAXLONG.
 178  */
 179
 180 /**
 181  * G_MINLONG:
 182  *
 183  * The minimum value which can be held in a #glong.
 184  */
 185
 186 /**
 187  * G_MAXLONG:
 188  *
 189  * The maximum value which can be held in a #glong.
 190  */
 191
 192 /**
 193  * gulong:
 194  *
 195  * Corresponds to the standard C unsigned long type.
 196  * Values of this type can range from 0 to %G_MAXULONG.
 197  */
 198
 199 /**
 200  * G_MAXULONG:
 201  *
 202  * The maximum value which can be held in a #gulong.
 203  */
 204
 205 /**
 206  * gint8:
 207  *
 208  * A signed integer guaranteed to be 8 bits on all platforms.
 209  * Values of this type can range from %G_MININT8 (= -128) to
 210  * %G_MAXINT8 (= 127).
 211  */
 212
 213 /**
 214  * G_MAXINT8:
 215  *
 216  * The maximum value which can be held in a #gint8.
 217  *
 218  * Since: 2.4
 219  */
 220
 221 /**
 222  * guint8:
 223  *
 224  * An unsigned integer guaranteed to be 8 bits on all platforms.
 225  * Values of this type can range from 0 to %G_MAXUINT8 (= 255).
 226  */
 227
 228 /**
 229  * G_MAXUINT8:
 230  *
 231  * The maximum value which can be held in a #guint8.
 232  *
 233  * Since: 2.4
 234  */
 235
 236 /**
 237  * gint16:
 238  *
 239  * A signed integer guaranteed to be 16 bits on all platforms.
 240  * Values of this type can range from %G_MININT16 (= -32,768) to
 241  * %G_MAXINT16 (= 32,767).
 242  *
 243  * To print or scan values of this type, use
 244  * %G_GINT16_MODIFIER and/or %G_GINT16_FORMAT.
 245  */
 246
 247 /**
 248  * G_MAXINT16:
 249  *
 250  * The maximum value which can be held in a #gint16.
 251  *
 252  * Since: 2.4
 253  */
 254
 255 /**
 256  * G_GINT16_MODIFIER:
 257  *
 258  * The platform dependent length modifier for conversion specifiers
 259  * for scanning and printing values of type #gint16 or #guint16. It
 260  * is a string literal, but doesn't include the percent-sign, such
 261  * that you can add precision and length modifiers between percent-sign
 262  * and conversion specifier and append a conversion specifier.
 263  *
 264  * The following example prints "0x7b";
 265  * |[<!-- language="C" -->
 266  * gint16 value = 123;
 267  * g_print ("%#" G_GINT16_MODIFIER "x", value);
 268  * ]|
 269  *
 270  * Since: 2.4
 271  */
 272
 273 /**
 274  * G_GINT16_FORMAT:
 275  *
 276  * This is the platform dependent conversion specifier for scanning and
 277  * printing values of type #gint16. It is a string literal, but doesn't
 278  * include the percent-sign, such that you can add precision and length
 279  * modifiers between percent-sign and conversion specifier.
 280  *
 281  * |[<!-- language="C" -->
 282  * gint16 in;
 283  * gint32 out;
 284  * sscanf ("42", "%" G_GINT16_FORMAT, &in)
 285  * out = in * 1000;
 286  * g_print ("%" G_GINT32_FORMAT, out);
 287  * ]|
 288  */
 289
 290 /**
 291  * guint16:
 292  *
 293  * An unsigned integer guaranteed to be 16 bits on all platforms.
 294  * Values of this type can range from 0 to %G_MAXUINT16 (= 65,535).
 295  *
 296  * To print or scan values of this type, use
 297  * %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
 298  */
 299
 300 /**
 301  * G_MAXUINT16:
 302  *
 303  * The maximum value which can be held in a #guint16.
 304  *
 305  * Since: 2.4
 306  */
 307
 308 /**
 309  * G_GUINT16_FORMAT:
 310  *
 311  * This is the platform dependent conversion specifier for scanning
 312  * and printing values of type #guint16. See also %G_GINT16_FORMAT
 313  */
 314
 315 /**
 316  * gint32:
 317  *
 318  * A signed integer guaranteed to be 32 bits on all platforms.
 319  * Values of this type can range from %G_MININT32 (= -2,147,483,648)
 320  * to %G_MAXINT32 (= 2,147,483,647).
 321  *
 322  * To print or scan values of this type, use
 323  * %G_GINT32_MODIFIER and/or %G_GINT32_FORMAT.
 324  */
 325
 326 /**
 327  * G_MAXINT32:
 328  *
 329  * The maximum value which can be held in a #gint32.
 330  *
 331  * Since: 2.4
 332  */
 333
 334 /**
 335  * G_GINT32_MODIFIER:
 336  *
 337  * The platform dependent length modifier for conversion specifiers
 338  * for scanning and printing values of type #gint32 or #guint32. It
 339  * is a string literal. See also %G_GINT16_MODIFIER.
 340  *
 341  * Since: 2.4
 342  */
 343
 344 /**
 345  * G_GINT32_FORMAT:
 346  *
 347  * This is the platform dependent conversion specifier for scanning
 348  * and printing values of type #gint32. See also %G_GINT16_FORMAT.
 349  */
 350
 351 /**
 352  * guint32:
 353  *
 354  * An unsigned integer guaranteed to be 32 bits on all platforms.
 355  * Values of this type can range from 0 to %G_MAXUINT32 (= 4,294,967,295).
 356  *
 357  * To print or scan values of this type, use
 358  * %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
 359  */
 360
 361 /**
 362  * G_MAXUINT32:
 363  *
 364  * The maximum value which can be held in a #guint32.
 365  *
 366  * Since: 2.4
 367  */
 368
 369 /**
 370  * G_GUINT32_FORMAT:
 371  *
 372  * This is the platform dependent conversion specifier for scanning
 373  * and printing values of type #guint32. See also %G_GINT16_FORMAT.
 374  */
 375
 376 /**
 377  * gint64:
 378  *
 379  * A signed integer guaranteed to be 64 bits on all platforms.
 380  * Values of this type can range from %G_MININT64
 381  * (= -9,223,372,036,854,775,808) to %G_MAXINT64
 382  * (= 9,223,372,036,854,775,807).
 383  *
 384  * To print or scan values of this type, use
 385  * %G_GINT64_MODIFIER and/or %G_GINT64_FORMAT.
 386  */
 387
 388 /**
 389  * G_MAXINT64:
 390  *
 391  * The maximum value which can be held in a #gint64.
 392  */
 393
 394 /**
 395  * G_GINT64_MODIFIER:
 396  *
 397  * The platform dependent length modifier for conversion specifiers
 398  * for scanning and printing values of type #gint64 or #guint64.
 399  * It is a string literal.
 400  *
 401  * Some platforms do not support printing 64-bit integers, even
 402  * though the types are supported. On such platforms %G_GINT64_MODIFIER
 403  * is not defined.
 404  *
 405  * Since: 2.4
 406  */
 407
 408 /**
 409  * G_GINT64_FORMAT:
 410  *
 411  * This is the platform dependent conversion specifier for scanning
 412  * and printing values of type #gint64. See also %G_GINT16_FORMAT.
 413  *
 414  * Some platforms do not support scanning and printing 64-bit integers,
 415  * even though the types are supported. On such platforms %G_GINT64_FORMAT
 416  * is not defined. Note that scanf() may not support 64-bit integers, even
 417  * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
 418  * is not recommended for parsing anyway; consider using g_ascii_strtoull()
 419  * instead.
 420  */
 421
 422 /**
 423  * guint64:
 424  *
 425  * An unsigned integer guaranteed to be 64-bits on all platforms.
 426  * Values of this type can range from 0 to %G_MAXUINT64
 427  * (= 18,446,744,073,709,551,615).
 428  *
 429  * To print or scan values of this type, use
 430  * %G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT.
 431  */
 432
 433 /**
 434  * G_MAXUINT64:
 435  *
 436  * The maximum value which can be held in a #guint64.
 437  */
 438
 439 /**
 440  * G_GUINT64_FORMAT:
 441  *
 442  * This is the platform dependent conversion specifier for scanning
 443  * and printing values of type #guint64. See also %G_GINT16_FORMAT.
 444  *
 445  * Some platforms do not support scanning and printing 64-bit integers,
 446  * even though the types are supported. On such platforms %G_GUINT64_FORMAT
 447  * is not defined.  Note that scanf() may not support 64-bit integers, even
 448  * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
 449  * is not recommended for parsing anyway; consider using g_ascii_strtoull()
 450  * instead.
 451  */
 452
 453 /**
 454  * G_GINT64_CONSTANT:
 455  * @val: a literal integer value, e.g. 0x1d636b02300a7aa7
 456  *
 457  * This macro is used to insert 64-bit integer literals
 458  * into the source code.
 459  */
 460
 461 /**
 462  * G_GUINT64_CONSTANT:
 463  * @val: a literal integer value, e.g. 0x1d636b02300a7aa7U
 464  *
 465  * This macro is used to insert 64-bit unsigned integer
 466  * literals into the source code.
 467  *
 468  * Since: 2.10
 469  */
 470
 471 /**
 472  * gfloat:
 473  *
 474  * Corresponds to the standard C float type.
 475  * Values of this type can range from -%G_MAXFLOAT to %G_MAXFLOAT.
 476  */
 477
 478 /**
 479  * G_MINFLOAT:
 480  *
 481  * The minimum positive value which can be held in a #gfloat.
 482  *
 483  * If you are interested in the smallest value which can be held
 484  * in a #gfloat, use -%G_MAXFLOAT.
 485  */
 486
 487 /**
 488  * G_MAXFLOAT:
 489  *
 490  * The maximum value which can be held in a #gfloat.
 491  */
 492
 493 /**
 494  * gdouble:
 495  *
 496  * Corresponds to the standard C double type.
 497  * Values of this type can range from -%G_MAXDOUBLE to %G_MAXDOUBLE.
 498  */
 499
 500 /**
 501  * G_MINDOUBLE:
 502  *
 503  * The minimum positive value which can be held in a #gdouble.
 504  *
 505  * If you are interested in the smallest value which can be held
 506  * in a #gdouble, use -%G_MAXDOUBLE.
 507  */
 508
 509 /**
 510  * G_MAXDOUBLE:
 511  *
 512  * The maximum value which can be held in a #gdouble.
 513  */
 514
 515 /**
 516  * gsize:
 517  *
 518  * An unsigned integer type of the result of the sizeof operator,
 519  * corresponding to the size_t type defined in C99.
 520  * This type is wide enough to hold the numeric value of a pointer,
 521  * so it is usually 32 bit wide on a 32-bit platform and 64 bit wide
 522  * on a 64-bit platform. Values of this type can range from 0 to
 523  * %G_MAXSIZE.
 524  *
 525  * To print or scan values of this type, use
 526  * %G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT.
 527  */
 528
 529 /**
 530  * G_MAXSIZE:
 531  *
 532  * The maximum value which can be held in a #gsize.
 533  *
 534  * Since: 2.4
 535  */
 536
 537 /**
 538  * G_GSIZE_MODIFIER:
 539  *
 540  * The platform dependent length modifier for conversion specifiers
 541  * for scanning and printing values of type #gsize. It
 542  * is a string literal.
 543  *
 544  * Since: 2.6
 545  */
 546
 547 /**
 548  * G_GSIZE_FORMAT:
 549  *
 550  * This is the platform dependent conversion specifier for scanning
 551  * and printing values of type #gsize. See also %G_GINT16_FORMAT.
 552  *
 553  * Since: 2.6
 554  */
 555
 556 /**
 557  * gssize:
 558  *
 559  * A signed variant of #gsize, corresponding to the
 560  * ssize_t defined on most platforms.
 561  * Values of this type can range from %G_MINSSIZE
 562  * to %G_MAXSSIZE.
 563  *
 564  * To print or scan values of this type, use
 565  * %G_GSSIZE_MODIFIER and/or %G_GSSIZE_FORMAT.
 566  */
 567
 568 /**
 569  * G_MINSSIZE:
 570  *
 571  * The minimum value which can be held in a #gssize.
 572  *
 573  * Since: 2.14
 574  */
 575
 576 /**
 577  * G_MAXSSIZE:
 578  *
 579  * The maximum value which can be held in a #gssize.
 580  *
 581  * Since: 2.14
 582  */
 583
 584 /**
 585  * G_GSSIZE_FORMAT:
 586  *
 587  * This is the platform dependent conversion specifier for scanning
 588  * and printing values of type #gssize. See also %G_GINT16_FORMAT.
 589  *
 590  * Since: 2.6
 591  */
 592
 593 /**
 594  * G_GSSIZE_MODIFIER:
 595  *
 596  * The platform dependent length modifier for conversion specifiers
 597  * for scanning and printing values of type #gssize. It
 598  * is a string literal.
 599  *
 600  * Since: 2.6
 601  */
 602
 603 /**
 604  * goffset:
 605  *
 606  * A signed integer type that is used for file offsets,
 607  * corresponding to the POSIX type `off_t` as if compiling with
 608  * `_FILE_OFFSET_BITS` set to 64. #goffset is always 64 bits wide, even on
 609  * 32-bit architectures.
 610  * Values of this type can range from %G_MINOFFSET to
 611  * %G_MAXOFFSET.
 612  *
 613  * To print or scan values of this type, use
 614  * %G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT.
 615  *
 616  * Since: 2.14
 617  */
 618
 619 /**
 620  * G_MINOFFSET:
 621  *
 622  * The minimum value which can be held in a #goffset.
 623  */
 624
 625 /**
 626  * G_MAXOFFSET:
 627  *
 628  * The maximum value which can be held in a #goffset.
 629  */
 630
 631 /**
 632  * G_GOFFSET_MODIFIER:
 633  *
 634  * The platform dependent length modifier for conversion specifiers
 635  * for scanning and printing values of type #goffset. It is a string
 636  * literal. See also %G_GINT64_MODIFIER.
 637  *
 638  * Since: 2.20
 639  */
 640
 641 /**
 642  * G_GOFFSET_FORMAT:
 643  *
 644  * This is the platform dependent conversion specifier for scanning
 645  * and printing values of type #goffset. See also %G_GINT64_FORMAT.
 646  *
 647  * Since: 2.20
 648  */
 649
 650 /**
 651  * G_GOFFSET_CONSTANT:
 652  * @val: a literal integer value, e.g. 0x1d636b02300a7aa7
 653  *
 654  * This macro is used to insert #goffset 64-bit integer literals
 655  * into the source code.
 656  *
 657  * See also G_GINT64_CONSTANT().
 658  *
 659  * Since: 2.20
 660  */
 661
 662 /**
 663  * gintptr:
 664  *
 665  * Corresponds to the C99 type intptr_t,
 666  * a signed integer type that can hold any pointer.
 667  *
 668  * To print or scan values of this type, use
 669  * %G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT.
 670  *
 671  * Since: 2.18
 672  */
 673
 674 /**
 675  * G_GINTPTR_MODIFIER:
 676  *
 677  * The platform dependent length modifier for conversion specifiers
 678  * for scanning and printing values of type #gintptr or #guintptr.
 679  * It is a string literal.
 680  *
 681  * Since: 2.22
 682  */
 683
 684 /**
 685  * G_GINTPTR_FORMAT:
 686  *
 687  * This is the platform dependent conversion specifier for scanning
 688  * and printing values of type #gintptr.
 689  *
 690  * Since: 2.22
 691  */
 692
 693 /**
 694  * guintptr:
 695  *
 696  * Corresponds to the C99 type uintptr_t,
 697  * an unsigned integer type that can hold any pointer.
 698  *
 699  * To print or scan values of this type, use
 700  * %G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT.
 701  *
 702  * Since: 2.18
 703  */
 704
 705 /**
 706  * G_GUINTPTR_FORMAT:
 707  *
 708  * This is the platform dependent conversion specifier
 709  * for scanning and printing values of type #guintptr.
 710  *
 711  * Since: 2.22
 712  */
 713
 714 /* Type conversion {{{1 */
 715
 716 /**
 717  * SECTION:type_conversion
 718  * @title: Type Conversion Macros
 719  * @short_description: portably storing integers in pointer variables
 720  *
 721  * Many times GLib, GTK+, and other libraries allow you to pass "user
 722  * data" to a callback, in the form of a void pointer. From time to time
 723  * you want to pass an integer instead of a pointer. You could allocate
 724  * an integer, with something like:
 725  * |[<!-- language="C" -->
 726  *   int *ip = g_new (int, 1);
 727  *   *ip = 42;
 728  * ]|
 729  * But this is inconvenient, and it's annoying to have to free the
 730  * memory at some later time.
 731  *
 732  * Pointers are always at least 32 bits in size (on all platforms GLib
 733  * intends to support). Thus you can store at least 32-bit integer values
 734  * in a pointer value. Naively, you might try this, but it's incorrect:
 735  * |[<!-- language="C" -->
 736  *   gpointer p;
 737  *   int i;
 738  *   p = (void*) 42;
 739  *   i = (int) p;
 740  * ]|
 741  * Again, that example was not correct, don't copy it.
 742  * The problem is that on some systems you need to do this:
 743  * |[<!-- language="C" -->
 744  *   gpointer p;
 745  *   int i;
 746  *   p = (void*) (long) 42;
 747  *   i = (int) (long) p;
 748  * ]|
 749  * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
 750  * to do the right thing on every platform.
 751  *
 752  * Warning: You may not store pointers in integers. This is not
 753  * portable in any way, shape or form. These macros only allow storing
 754  * integers in pointers, and only preserve 32 bits of the integer; values
 755  * outside the range of a 32-bit integer will be mangled.
 756  */
 757
 758 /**
 759  * GINT_TO_POINTER:
 760  * @i: integer to stuff into a pointer
 761  *
 762  * Stuffs an integer into a pointer type.
 763  *
 764  * Remember, you may not store pointers in integers. This is not portable
 765  * in any way, shape or form. These macros only allow storing integers in
 766  * pointers, and only preserve 32 bits of the integer; values outside the
 767  * range of a 32-bit integer will be mangled.
 768  */
 769
 770 /**
 771  * GPOINTER_TO_INT:
 772  * @p: pointer containing an integer
 773  *
 774  * Extracts an integer from a pointer. The integer must have
 775  * been stored in the pointer with GINT_TO_POINTER().
 776  *
 777  * Remember, you may not store pointers in integers. This is not portable
 778  * in any way, shape or form. These macros only allow storing integers in
 779  * pointers, and only preserve 32 bits of the integer; values outside the
 780  * range of a 32-bit integer will be mangled.
 781  */
 782
 783 /**
 784  * GUINT_TO_POINTER:
 785  * @u: unsigned integer to stuff into the pointer
 786  *
 787  * Stuffs an unsigned integer into a pointer type.
 788  */
 789
 790 /**
 791  * GPOINTER_TO_UINT:
 792  * @p: pointer to extract an unsigned integer from
 793  *
 794  * Extracts an unsigned integer from a pointer. The integer must have
 795  * been stored in the pointer with GUINT_TO_POINTER().
 796  */
 797
 798 /**
 799  * GSIZE_TO_POINTER:
 800  * @s: #gsize to stuff into the pointer
 801  *
 802  * Stuffs a #gsize into a pointer type.
 803  */
 804
 805 /**
 806  * GPOINTER_TO_SIZE:
 807  * @p: pointer to extract a #gsize from
 808  *
 809  * Extracts a #gsize from a pointer. The #gsize must have
 810  * been stored in the pointer with GSIZE_TO_POINTER().
 811  */
 812
 813 /* Byte order {{{1 */
 814
 815 /**
 816  * SECTION:byte_order
 817  * @title: Byte Order Macros
 818  * @short_description: a portable way to convert between different byte orders
 819  *
 820  * These macros provide a portable way to determine the host byte order
 821  * and to convert values between different byte orders.
 822  *
 823  * The byte order is the order in which bytes are stored to create larger
 824  * data types such as the #gint and #glong values.
 825  * The host byte order is the byte order used on the current machine.
 826  *
 827  * Some processors store the most significant bytes (i.e. the bytes that
 828  * hold the largest part of the value) first. These are known as big-endian
 829  * processors. Other processors (notably the x86 family) store the most
 830  * significant byte last. These are known as little-endian processors.
 831  *
 832  * Finally, to complicate matters, some other processors store the bytes in
 833  * a rather curious order known as PDP-endian. For a 4-byte word, the 3rd
 834  * most significant byte is stored first, then the 4th, then the 1st and
 835  * finally the 2nd.
 836  *
 837  * Obviously there is a problem when these different processors communicate
 838  * with each other, for example over networks or by using binary file formats.
 839  * This is where these macros come in. They are typically used to convert
 840  * values into a byte order which has been agreed on for use when
 841  * communicating between different processors. The Internet uses what is
 842  * known as 'network byte order' as the standard byte order (which is in
 843  * fact the big-endian byte order).
 844  *
 845  * Note that the byte order conversion macros may evaluate their arguments
 846  * multiple times, thus you should not use them with arguments which have
 847  * side-effects.
 848  */
 849
 850 /**
 851  * G_BYTE_ORDER:
 852  *
 853  * The host byte order.
 854  * This can be either %G_LITTLE_ENDIAN or %G_BIG_ENDIAN (support for
 855  * %G_PDP_ENDIAN may be added in future.)
 856  */
 857
 858 /**
 859  * G_LITTLE_ENDIAN:
 860  *
 861  * Specifies one of the possible types of byte order.
 862  * See %G_BYTE_ORDER.
 863  */
 864
 865 /**
 866  * G_BIG_ENDIAN:
 867  *
 868  * Specifies one of the possible types of byte order.
 869  * See %G_BYTE_ORDER.
 870  */
 871
 872 /**
 873  * G_PDP_ENDIAN:
 874  *
 875  * Specifies one of the possible types of byte order
 876  * (currently unused). See %G_BYTE_ORDER.
 877  */
 878
 879 /**
 880  * g_htonl:
 881  * @val: a 32-bit integer value in host byte order
 882  *
 883  * Converts a 32-bit integer value from host to network byte order.
 884  *
 885  * Returns: @val converted to network byte order
 886  */
 887
 888 /**
 889  * g_htons:
 890  * @val: a 16-bit integer value in host byte order
 891  *
 892  * Converts a 16-bit integer value from host to network byte order.
 893  *
 894  * Returns: @val converted to network byte order
 895  */
 896
 897 /**
 898  * g_ntohl:
 899  * @val: a 32-bit integer value in network byte order
 900  *
 901  * Converts a 32-bit integer value from network to host byte order.
 902  *
 903  * Returns: @val converted to host byte order.
 904  */
 905
 906 /**
 907  * g_ntohs:
 908  * @val: a 16-bit integer value in network byte order
 909  *
 910  * Converts a 16-bit integer value from network to host byte order.
 911  *
 912  * Returns: @val converted to host byte order
 913  */
 914
 915 /**
 916  * GINT_FROM_BE:
 917  * @val: a #gint value in big-endian byte order
 918  *
 919  * Converts a #gint value from big-endian to host byte order.
 920  *
 921  * Returns: @val converted to host byte order
 922  */
 923
 924 /**
 925  * GINT_FROM_LE:
 926  * @val: a #gint value in little-endian byte order
 927  *
 928  * Converts a #gint value from little-endian to host byte order.
 929  *
 930  * Returns: @val converted to host byte order
 931  */
 932
 933 /**
 934  * GINT_TO_BE:
 935  * @val: a #gint value in host byte order
 936  *
 937  * Converts a #gint value from host byte order to big-endian.
 938  *
 939  * Returns: @val converted to big-endian byte order
 940  */
 941
 942 /**
 943  * GINT_TO_LE:
 944  * @val: a #gint value in host byte order
 945  *
 946  * Converts a #gint value from host byte order to little-endian.
 947  *
 948  * Returns: @val converted to little-endian byte order
 949  */
 950
 951 /**
 952  * GUINT_FROM_BE:
 953  * @val: a #guint value in big-endian byte order
 954  *
 955  * Converts a #guint value from big-endian to host byte order.
 956  *
 957  * Returns: @val converted to host byte order
 958  */
 959
 960 /**
 961  * GUINT_FROM_LE:
 962  * @val: a #guint value in little-endian byte order
 963  *
 964  * Converts a #guint value from little-endian to host byte order.
 965  *
 966  * Returns: @val converted to host byte order
 967  */
 968
 969 /**
 970  * GUINT_TO_BE:
 971  * @val: a #guint value in host byte order
 972  *
 973  * Converts a #guint value from host byte order to big-endian.
 974  *
 975  * Returns: @val converted to big-endian byte order
 976  */
 977
 978 /**
 979  * GUINT_TO_LE:
 980  * @val: a #guint value in host byte order
 981  *
 982  * Converts a #guint value from host byte order to little-endian.
 983  *
 984  * Returns: @val converted to little-endian byte order.
 985  */
 986
 987 /**
 988  * GLONG_FROM_BE:
 989  * @val: a #glong value in big-endian byte order
 990  *
 991  * Converts a #glong value from big-endian to the host byte order.
 992  *
 993  * Returns: @val converted to host byte order
 994  */
 995
 996 /**
 997  * GLONG_FROM_LE:
 998  * @val: a #glong value in little-endian byte order
 999  *
1000  * Converts a #glong value from little-endian to host byte order.
1001  *
1002  * Returns: @val converted to host byte order
1003  */
1004
1005 /**
1006  * GLONG_TO_BE:
1007  * @val: a #glong value in host byte order
1008  *
1009  * Converts a #glong value from host byte order to big-endian.
1010  *
1011  * Returns: @val converted to big-endian byte order
1012  */
1013
1014 /**
1015  * GLONG_TO_LE:
1016  * @val: a #glong value in host byte order
1017  *
1018  * Converts a #glong value from host byte order to little-endian.
1019  *
1020  * Returns: @val converted to little-endian
1021  */
1022
1023 /**
1024  * GULONG_FROM_BE:
1025  * @val: a #gulong value in big-endian byte order
1026  *
1027  * Converts a #gulong value from big-endian to host byte order.
1028  *
1029  * Returns: @val converted to host byte order
1030  */
1031
1032 /**
1033  * GULONG_FROM_LE:
1034  * @val: a #gulong value in little-endian byte order
1035  *
1036  * Converts a #gulong value from little-endian to host byte order.
1037  *
1038  * Returns: @val converted to host byte order
1039  */
1040
1041 /**
1042  * GULONG_TO_BE:
1043  * @val: a #gulong value in host byte order
1044  *
1045  * Converts a #gulong value from host byte order to big-endian.
1046  *
1047  * Returns: @val converted to big-endian
1048  */
1049
1050 /**
1051  * GULONG_TO_LE:
1052  * @val: a #gulong value in host byte order
1053  *
1054  * Converts a #gulong value from host byte order to little-endian.
1055  *
1056  * Returns: @val converted to little-endian
1057  */
1058
1059 /**
1060  * GSIZE_FROM_BE:
1061  * @val: a #gsize value in big-endian byte order
1062  *
1063  * Converts a #gsize value from big-endian to the host byte order.
1064  *
1065  * Returns: @val converted to host byte order
1066  */
1067
1068 /**
1069  * GSIZE_FROM_LE:
1070  * @val: a #gsize value in little-endian byte order
1071  *
1072  * Converts a #gsize value from little-endian to host byte order.
1073  *
1074  * Returns: @val converted to host byte order
1075  */
1076
1077 /**
1078  * GSIZE_TO_BE:
1079  * @val: a #gsize value in host byte order
1080  *
1081  * Converts a #gsize value from host byte order to big-endian.
1082  *
1083  * Returns: @val converted to big-endian byte order
1084  */
1085
1086 /**
1087  * GSIZE_TO_LE:
1088  * @val: a #gsize value in host byte order
1089  *
1090  * Converts a #gsize value from host byte order to little-endian.
1091  *
1092  * Returns: @val converted to little-endian
1093  */
1094
1095 /**
1096  * GSSIZE_FROM_BE:
1097  * @val: a #gssize value in big-endian byte order
1098  *
1099  * Converts a #gssize value from big-endian to host byte order.
1100  *
1101  * Returns: @val converted to host byte order
1102  */
1103
1104 /**
1105  * GSSIZE_FROM_LE:
1106  * @val: a #gssize value in little-endian byte order
1107  *
1108  * Converts a #gssize value from little-endian to host byte order.
1109  *
1110  * Returns: @val converted to host byte order
1111  */
1112
1113 /**
1114  * GSSIZE_TO_BE:
1115  * @val: a #gssize value in host byte order
1116  *
1117  * Converts a #gssize value from host byte order to big-endian.
1118  *
1119  * Returns: @val converted to big-endian
1120  */
1121
1122 /**
1123  * GSSIZE_TO_LE:
1124  * @val: a #gssize value in host byte order
1125  *
1126  * Converts a #gssize value from host byte order to little-endian.
1127  *
1128  * Returns: @val converted to little-endian
1129  */
1130
1131 /**
1132  * GINT16_FROM_BE:
1133  * @val: a #gint16 value in big-endian byte order
1134  *
1135  * Converts a #gint16 value from big-endian to host byte order.
1136  *
1137  * Returns: @val converted to host byte order
1138  */
1139
1140 /**
1141  * GINT16_FROM_LE:
1142  * @val: a #gint16 value in little-endian byte order
1143  *
1144  * Converts a #gint16 value from little-endian to host byte order.
1145  *
1146  * Returns: @val converted to host byte order
1147  */
1148
1149 /**
1150  * GINT16_TO_BE:
1151  * @val: a #gint16 value in host byte order
1152  *
1153  * Converts a #gint16 value from host byte order to big-endian.
1154  *
1155  * Returns: @val converted to big-endian
1156  */
1157
1158 /**
1159  * GINT16_TO_LE:
1160  * @val: a #gint16 value in host byte order
1161  *
1162  * Converts a #gint16 value from host byte order to little-endian.
1163  *
1164  * Returns: @val converted to little-endian
1165  */
1166
1167 /**
1168  * GUINT16_FROM_BE:
1169  * @val: a #guint16 value in big-endian byte order
1170  *
1171  * Converts a #guint16 value from big-endian to host byte order.
1172  *
1173  * Returns: @val converted to host byte order
1174  */
1175
1176 /**
1177  * GUINT16_FROM_LE:
1178  * @val: a #guint16 value in little-endian byte order
1179  *
1180  * Converts a #guint16 value from little-endian to host byte order.
1181  *
1182  * Returns: @val converted to host byte order
1183  */
1184
1185 /**
1186  * GUINT16_TO_BE:
1187  * @val: a #guint16 value in host byte order
1188  *
1189  * Converts a #guint16 value from host byte order to big-endian.
1190  *
1191  * Returns: @val converted to big-endian
1192  */
1193
1194 /**
1195  * GUINT16_TO_LE:
1196  * @val: a #guint16 value in host byte order
1197  *
1198  * Converts a #guint16 value from host byte order to little-endian.
1199  *
1200  * Returns: @val converted to little-endian
1201  */
1202
1203 /**
1204  * GINT32_FROM_BE:
1205  * @val: a #gint32 value in big-endian byte order
1206  *
1207  * Converts a #gint32 value from big-endian to host byte order.
1208  *
1209  * Returns: @val converted to host byte order
1210  */
1211
1212 /**
1213  * GINT32_FROM_LE:
1214  * @val: a #gint32 value in little-endian byte order
1215  *
1216  * Converts a #gint32 value from little-endian to host byte order.
1217  *
1218  * Returns: @val converted to host byte order
1219  */
1220
1221 /**
1222  * GINT32_TO_BE:
1223  * @val: a #gint32 value in host byte order
1224  *
1225  * Converts a #gint32 value from host byte order to big-endian.
1226  *
1227  * Returns: @val converted to big-endian
1228  */
1229
1230 /**
1231  * GINT32_TO_LE:
1232  * @val: a #gint32 value in host byte order
1233  *
1234  * Converts a #gint32 value from host byte order to little-endian.
1235  *
1236  * Returns: @val converted to little-endian
1237  */
1238
1239 /**
1240  * GUINT32_FROM_BE:
1241  * @val: a #guint32 value in big-endian byte order
1242  *
1243  * Converts a #guint32 value from big-endian to host byte order.
1244  *
1245  * Returns: @val converted to host byte order
1246  */
1247
1248 /**
1249  * GUINT32_FROM_LE:
1250  * @val: a #guint32 value in little-endian byte order
1251  *
1252  * Converts a #guint32 value from little-endian to host byte order.
1253  *
1254  * Returns: @val converted to host byte order
1255  */
1256
1257 /**
1258  * GUINT32_TO_BE:
1259  * @val: a #guint32 value in host byte order
1260  *
1261  * Converts a #guint32 value from host byte order to big-endian.
1262  *
1263  * Returns: @val converted to big-endian
1264  */
1265
1266 /**
1267  * GUINT32_TO_LE:
1268  * @val: a #guint32 value in host byte order
1269  *
1270  * Converts a #guint32 value from host byte order to little-endian.
1271  *
1272  * Returns: @val converted to little-endian
1273  */
1274
1275 /**
1276  * GINT64_FROM_BE:
1277  * @val: a #gint64 value in big-endian byte order
1278  *
1279  * Converts a #gint64 value from big-endian to host byte order.
1280  *
1281  * Returns: @val converted to host byte order
1282  */
1283
1284 /**
1285  * GINT64_FROM_LE:
1286  * @val: a #gint64 value in little-endian byte order
1287  *
1288  * Converts a #gint64 value from little-endian to host byte order.
1289  *
1290  * Returns: @val converted to host byte order
1291  */
1292
1293 /**
1294  * GINT64_TO_BE:
1295  * @val: a #gint64 value in host byte order
1296  *
1297  * Converts a #gint64 value from host byte order to big-endian.
1298  *
1299  * Returns: @val converted to big-endian
1300  */
1301
1302 /**
1303  * GINT64_TO_LE:
1304  * @val: a #gint64 value in host byte order
1305  *
1306  * Converts a #gint64 value from host byte order to little-endian.
1307  *
1308  * Returns: @val converted to little-endian
1309  */
1310
1311 /**
1312  * GUINT64_FROM_BE:
1313  * @val: a #guint64 value in big-endian byte order
1314  *
1315  * Converts a #guint64 value from big-endian to host byte order.
1316  *
1317  * Returns: @val converted to host byte order
1318  */
1319
1320 /**
1321  * GUINT64_FROM_LE:
1322  * @val: a #guint64 value in little-endian byte order
1323  *
1324  * Converts a #guint64 value from little-endian to host byte order.
1325  *
1326  * Returns: @val converted to host byte order
1327  */
1328
1329 /**
1330  * GUINT64_TO_BE:
1331  * @val: a #guint64 value in host byte order
1332  *
1333  * Converts a #guint64 value from host byte order to big-endian.
1334  *
1335  * Returns: @val converted to big-endian
1336  */
1337
1338 /**
1339  * GUINT64_TO_LE:
1340  * @val: a #guint64 value in host byte order
1341  *
1342  * Converts a #guint64 value from host byte order to little-endian.
1343  *
1344  * Returns: @val converted to little-endian
1345  */
1346
1347 /**
1348  * GUINT16_SWAP_BE_PDP:
1349  * @val: a #guint16 value in big-endian or pdp-endian byte order
1350  *
1351  * Converts a #guint16 value between big-endian and pdp-endian byte order.
1352  * The conversion is symmetric so it can be used both ways.
1353  *
1354  * Returns: @val converted to the opposite byte order
1355  */
1356
1357 /**
1358  * GUINT16_SWAP_LE_BE:
1359  * @val: a #guint16 value in little-endian or big-endian byte order
1360  *
1361  * Converts a #guint16 value between little-endian and big-endian byte order.
1362  * The conversion is symmetric so it can be used both ways.
1363  *
1364  * Returns: @val converted to the opposite byte order
1365  */
1366
1367 /**
1368  * GUINT16_SWAP_LE_PDP:
1369  * @val: a #guint16 value in little-endian or pdp-endian byte order
1370  *
1371  * Converts a #guint16 value between little-endian and pdp-endian byte order.
1372  * The conversion is symmetric so it can be used both ways.
1373  *
1374  * Returns: @val converted to the opposite byte order
1375  */
1376
1377 /**
1378  * GUINT32_SWAP_BE_PDP:
1379  * @val: a #guint32 value in big-endian or pdp-endian byte order
1380  *
1381  * Converts a #guint32 value between big-endian and pdp-endian byte order.
1382  * The conversion is symmetric so it can be used both ways.
1383  *
1384  * Returns: @val converted to the opposite byte order
1385  */
1386
1387 /**
1388  * GUINT32_SWAP_LE_BE:
1389  * @val: a #guint32 value in little-endian or big-endian byte order
1390  *
1391  * Converts a #guint32 value between little-endian and big-endian byte order.
1392  * The conversion is symmetric so it can be used both ways.
1393  *
1394  * Returns: @val converted to the opposite byte order
1395  */
1396
1397 /**
1398  * GUINT32_SWAP_LE_PDP:
1399  * @val: a #guint32 value in little-endian or pdp-endian byte order
1400  *
1401  * Converts a #guint32 value between little-endian and pdp-endian byte order.
1402  * The conversion is symmetric so it can be used both ways.
1403  *
1404  * Returns: @val converted to the opposite byte order
1405  */
1406
1407 /**
1408  * GUINT64_SWAP_LE_BE:
1409  * @val: a #guint64 value in little-endian or big-endian byte order
1410  *
1411  * Converts a #guint64 value between little-endian and big-endian byte order.
1412  * The conversion is symmetric so it can be used both ways.
1413  *
1414  * Returns: @val converted to the opposite byte order
1415  */
1416
1417 /* Bounds-checked integer arithmetic {{{1 */
1418 /**
1419  * SECTION:checkedmath
1420  * @title: Bounds-checking integer arithmetic
1421  * @short_description: a set of helpers for performing checked integer arithmetic
1422  *
1423  * GLib offers a set of macros for doing additions and multiplications
1424  * of unsigned integers, with checks for overflows.
1425  *
1426  * The helpers all have three arguments.  A pointer to the destination
1427  * is always the first argument and the operands to the operation are
1428  * the other two.
1429  *
1430  * Following standard GLib convention, the helpers return %TRUE in case
1431  * of success (ie: no overflow).
1432  *
1433  * The helpers may be macros, normal functions or inlines.  They may be
1434  * implemented with inline assembly or compiler intrinsics where
1435  * available.
1436  *
1437  * Since: 2.48
1438  */
1439
1440 /**
1441  * g_uint_checked_add
1442  * @dest: a pointer to the #guint destination
1443  * @a: the #guint left operand
1444  * @b: the #guint right operand
1445  *
1446  * Performs a checked addition of @a and @b, storing the result in
1447  * @dest.
1448  *
1449  * If the operation is successful, %TRUE is returned.  If the operation
1450  * overflows then the state of @dest is undefined and %FALSE is
1451  * returned.
1452  *
1453  * Returns: %TRUE if there was no overflow
1454  * Since: 2.48
1455  */
1456
1457 /**
1458  * g_uint_checked_mul
1459  * @dest: a pointer to the #guint destination
1460  * @a: the #guint left operand
1461  * @b: the #guint right operand
1462  *
1463  * Performs a checked multiplication of @a and @b, storing the result in
1464  * @dest.
1465  *
1466  * If the operation is successful, %TRUE is returned.  If the operation
1467  * overflows then the state of @dest is undefined and %FALSE is
1468  * returned.
1469  *
1470  * Returns: %TRUE if there was no overflow
1471  * Since: 2.48
1472  */
1473
1474 /**
1475  * g_uint64_checked_add
1476  * @dest: a pointer to the #guint64 destination
1477  * @a: the #guint64 left operand
1478  * @b: the #guint64 right operand
1479  *
1480  * Performs a checked addition of @a and @b, storing the result in
1481  * @dest.
1482  *
1483  * If the operation is successful, %TRUE is returned.  If the operation
1484  * overflows then the state of @dest is undefined and %FALSE is
1485  * returned.
1486  *
1487  * Returns: %TRUE if there was no overflow
1488  * Since: 2.48
1489  */
1490
1491 /**
1492  * g_uint64_checked_mul
1493  * @dest: a pointer to the #guint64 destination
1494  * @a: the #guint64 left operand
1495  * @b: the #guint64 right operand
1496  *
1497  * Performs a checked multiplication of @a and @b, storing the result in
1498  * @dest.
1499  *
1500  * If the operation is successful, %TRUE is returned.  If the operation
1501  * overflows then the state of @dest is undefined and %FALSE is
1502  * returned.
1503  *
1504  * Returns: %TRUE if there was no overflow
1505  * Since: 2.48
1506  */
1507
1508 /**
1509  * g_size_checked_add
1510  * @dest: a pointer to the #gsize destination
1511  * @a: the #gsize left operand
1512  * @b: the #gsize right operand
1513  *
1514  * Performs a checked addition of @a and @b, storing the result in
1515  * @dest.
1516  *
1517  * If the operation is successful, %TRUE is returned.  If the operation
1518  * overflows then the state of @dest is undefined and %FALSE is
1519  * returned.
1520  *
1521  * Returns: %TRUE if there was no overflow
1522  * Since: 2.48
1523  */
1524
1525 /**
1526  * g_size_checked_mul
1527  * @dest: a pointer to the #gsize destination
1528  * @a: the #gsize left operand
1529  * @b: the #gsize right operand
1530  *
1531  * Performs a checked multiplication of @a and @b, storing the result in
1532  * @dest.
1533  *
1534  * If the operation is successful, %TRUE is returned.  If the operation
1535  * overflows then the state of @dest is undefined and %FALSE is
1536  * returned.
1537  *
1538  * Returns: %TRUE if there was no overflow
1539  * Since: 2.48
1540  */
1541 /* Numerical Definitions {{{1 */
1542
1543 /**
1544  * SECTION:numerical
1545  * @title: Numerical Definitions
1546  * @short_description: mathematical constants, and floating point decomposition
1547  *
1548  * GLib offers mathematical constants such as %G_PI for the value of pi;
1549  * many platforms have these in the C library, but some don't, the GLib
1550  * versions always exist.
1551  *
1552  * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
1553  * sign, mantissa and exponent of IEEE floats and doubles. These unions are
1554  * defined as appropriate for a given platform. IEEE floats and doubles are
1555  * supported (used for storage) by at least Intel, PPC and Sparc. See
1556  * [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float)
1557  * for more information about IEEE number formats.
1558  */
1559
1560 /**
1561  * G_IEEE754_FLOAT_BIAS:
1562  *
1563  * The bias by which exponents in single-precision floats are offset.
1564  */
1565
1566 /**
1567  * G_IEEE754_DOUBLE_BIAS:
1568  *
1569  * The bias by which exponents in double-precision floats are offset.
1570  */
1571
1572 /**
1573  * GFloatIEEE754:
1574  * @v_float: the double value
1575  *
1576  * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
1577  * mantissa and exponent of IEEE floats and doubles. These unions are defined
1578  * as appropriate for a given platform. IEEE floats and doubles are supported
1579  * (used for storage) by at least Intel, PPC and Sparc.
1580  */
1581
1582 /**
1583  * GDoubleIEEE754:
1584  * @v_double: the double value
1585  *
1586  * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
1587  * mantissa and exponent of IEEE floats and doubles. These unions are defined
1588  * as appropriate for a given platform. IEEE floats and doubles are supported
1589  * (used for storage) by at least Intel, PPC and Sparc.
1590  */
1591
1592 /**
1593  * G_E:
1594  *
1595  * The base of natural logarithms.
1596  */
1597
1598 /**
1599  * G_LN2:
1600  *
1601  * The natural logarithm of 2.
1602  */
1603
1604 /**
1605  * G_LN10:
1606  *
1607  * The natural logarithm of 10.
1608  */
1609
1610 /**
1611  * G_PI:
1612  *
1613  * The value of pi (ratio of circle's circumference to its diameter).
1614  */
1615
1616 /**
1617  * G_PI_2:
1618  *
1619  * Pi divided by 2.
1620  */
1621
1622 /**
1623  * G_PI_4:
1624  *
1625  * Pi divided by 4.
1626  */
1627
1628 /**
1629  * G_SQRT2:
1630  *
1631  * The square root of two.
1632  */
1633
1634 /**
1635  * G_LOG_2_BASE_10:
1636  *
1637  * Multiplying the base 2 exponent by this number yields the base 10 exponent.
1638  */
1639
1640 /* Macros {{{1 */
1641
1642 /**
1643  * SECTION:macros
1644  * @title: Standard Macros
1645  * @short_description: commonly-used macros
1646  *
1647  * These macros provide a few commonly-used features.
1648  */
1649
1650 /**
1651  * G_OS_WIN32:
1652  *
1653  * This macro is defined only on Windows. So you can bracket
1654  * Windows-specific code in "\#ifdef G_OS_WIN32".
1655  */
1656
1657 /**
1658  * G_OS_UNIX:
1659  *
1660  * This macro is defined only on UNIX. So you can bracket
1661  * UNIX-specific code in "\#ifdef G_OS_UNIX".
1662  */
1663
1664 /**
1665  * G_DIR_SEPARATOR:
1666  *
1667  * The directory separator character.
1668  * This is '/' on UNIX machines and '\' under Windows.
1669  */
1670
1671 /**
1672  * G_DIR_SEPARATOR_S:
1673  *
1674  * The directory separator as a string.
1675  * This is "/" on UNIX machines and "\" under Windows.
1676  */
1677
1678 /**
1679  * G_IS_DIR_SEPARATOR:
1680  * @c: a character
1681  *
1682  * Checks whether a character is a directory
1683  * separator. It returns %TRUE for '/' on UNIX
1684  * machines and for '\' or '/' under Windows.
1685  *
1686  * Since: 2.6
1687  */
1688
1689 /**
1690  * G_SEARCHPATH_SEPARATOR:
1691  *
1692  * The search path separator character.
1693  * This is ':' on UNIX machines and ';' under Windows.
1694  */
1695
1696 /**
1697  * G_SEARCHPATH_SEPARATOR_S:
1698  *
1699  * The search path separator as a string.
1700  * This is ":" on UNIX machines and ";" under Windows.
1701  */
1702
1703 /**
1704  * TRUE:
1705  *
1706  * Defines the %TRUE value for the #gboolean type.
1707  */
1708
1709 /**
1710  * FALSE:
1711  *
1712  * Defines the %FALSE value for the #gboolean type.
1713  */
1714
1715 /**
1716  * NULL:
1717  *
1718  * Defines the standard %NULL pointer.
1719  */
1720
1721 /**
1722  * MIN:
1723  * @a: a numeric value
1724  * @b: a numeric value
1725  *
1726  * Calculates the minimum of @a and @b.
1727  *
1728  * Returns: the minimum of @a and @b.
1729  */
1730
1731 /**
1732  * MAX:
1733  * @a: a numeric value
1734  * @b: a numeric value
1735  *
1736  * Calculates the maximum of @a and @b.
1737  *
1738  * Returns: the maximum of @a and @b.
1739  */
1740
1741 /**
1742  * ABS:
1743  * @a: a numeric value
1744  *
1745  * Calculates the absolute value of @a.
1746  * The absolute value is simply the number with any negative sign taken away.
1747  *
1748  * For example,
1749  * - ABS(-10) is 10.
1750  * - ABS(10) is also 10.
1751  *
1752  * Returns: the absolute value of @a.
1753  */
1754
1755 /**
1756  * CLAMP:
1757  * @x: the value to clamp
1758  * @low: the minimum value allowed
1759  * @high: the maximum value allowed
1760  *
1761  * Ensures that @x is between the limits set by @low and @high. If @low is
1762  * greater than @high the result is undefined.
1763  *
1764  * For example,
1765  * - CLAMP(5, 10, 15) is 10.
1766  * - CLAMP(15, 5, 10) is 10.
1767  * - CLAMP(20, 15, 25) is 20.
1768  *
1769  * Returns: the value of @x clamped to the range between @low and @high
1770  */
1771
1772 /**
1773  * G_APPROX_VALUE:
1774  * @a: a numeric value
1775  * @b: a numeric value
1776  * @epsilon: a numeric value that expresses the tolerance between @a and @b
1777  *
1778  * Evaluates to a truth value if the absolute difference between @a and @b is
1779  * smaller than @epsilon, and to a false value otherwise.
1780  *
1781  * For example,
1782  * - `G_APPROX_VALUE (5, 6, 2)` evaluates to true
1783  * - `G_APPROX_VALUE (3.14, 3.15, 0.001)` evaluates to false
1784  * - `G_APPROX_VALUE (n, 0.f, FLT_EPSILON)` evaluates to true if `n` is within
1785  *   the single precision floating point epsilon from zero
1786  *
1787  * Returns: %TRUE if the two values are within the desired range
1788  *
1789  * Since: 2.58
1790  */
1791
1792 /**
1793  * G_STRUCT_MEMBER:
1794  * @member_type: the type of the struct field
1795  * @struct_p: a pointer to a struct
1796  * @struct_offset: the offset of the field from the start of the struct,
1797  *     in bytes
1798  *
1799  * Returns a member of a structure at a given offset, using the given type.
1800  *
1801  * Returns: the struct member
1802  */
1803
1804 /**
1805  * G_STRUCT_MEMBER_P:
1806  * @struct_p: a pointer to a struct
1807  * @struct_offset: the offset from the start of the struct, in bytes
1808  *
1809  * Returns an untyped pointer to a given offset of a struct.
1810  *
1811  * Returns: an untyped pointer to @struct_p plus @struct_offset bytes
1812  */
1813
1814 /**
1815  * G_STRUCT_OFFSET:
1816  * @struct_type: a structure type, e.g. #GtkWidget
1817  * @member: a field in the structure, e.g. @window
1818  *
1819  * Returns the offset, in bytes, of a member of a struct.
1820  *
1821  * Returns: the offset of @member from the start of @struct_type
1822  */
1823
1824 /**
1825  * G_N_ELEMENTS:
1826  * @arr: the array
1827  *
1828  * Determines the number of elements in an array. The array must be
1829  * declared so the compiler knows its size at compile-time; this
1830  * macro will not work on an array allocated on the heap, only static
1831  * arrays or arrays on the stack.
1832  */
1833
1834 /* Miscellaneous Macros {{{1 */
1835
1836 /**
1837  * SECTION:macros_misc
1838  * @title: Miscellaneous Macros
1839  * @short_description: specialized macros which are not used often
1840  *
1841  * These macros provide more specialized features which are not
1842  * needed so often by application programmers.
1843  */
1844
1845 /**
1846  * G_STMT_START:
1847  *
1848  * Used within multi-statement macros so that they can be used in places
1849  * where only one statement is expected by the compiler.
1850  */
1851
1852 /**
1853  * G_STMT_END:
1854  *
1855  * Used within multi-statement macros so that they can be used in places
1856  * where only one statement is expected by the compiler.
1857  */
1858
1859 /**
1860  * G_BEGIN_DECLS:
1861  *
1862  * Used (along with %G_END_DECLS) to bracket header files. If the
1863  * compiler in use is a C++ compiler, adds extern "C"
1864  * around the header.
1865  */
1866
1867 /**
1868  * G_END_DECLS:
1869  *
1870  * Used (along with %G_BEGIN_DECLS) to bracket header files. If the
1871  * compiler in use is a C++ compiler, adds extern "C"
1872  * around the header.
1873  */
1874
1875 /**
1876  * G_VA_COPY:
1877  * @ap1: the va_list variable to place a copy of @ap2 in
1878  * @ap2: a va_list
1879  *
1880  * Portable way to copy va_list variables.
1881  *
1882  * In order to use this function, you must include string.h yourself,
1883  * because this macro may use memmove() and GLib does not include
1884  * string.h for you.
1885  *
1886  * Each invocation of `G_VA_COPY (ap1, ap2)` must be matched with a
1887  * corresponding `va_end (ap1)` call in the same function.
1888  */
1889
1890 /**
1891  * G_STRINGIFY:
1892  * @macro_or_string: a macro or a string
1893  *
1894  * Accepts a macro or a string and converts it into a string after
1895  * preprocessor argument expansion. For example, the following code:
1896  *
1897  * |[<!-- language="C" -->
1898  * #define AGE 27
1899  * const gchar *greeting = G_STRINGIFY (AGE) " today!";
1900  * ]|
1901  *
1902  * is transformed by the preprocessor into (code equivalent to):
1903  *
1904  * |[<!-- language="C" -->
1905  * const gchar *greeting = "27 today!";
1906  * ]|
1907  */
1908
1909 /**
1910  * G_PASTE:
1911  * @identifier1: an identifier
1912  * @identifier2: an identifier
1913  *
1914  * Yields a new preprocessor pasted identifier
1915  * @identifier1identifier2 from its expanded
1916  * arguments @identifier1 and @identifier2. For example,
1917  * the following code:
1918  * |[<!-- language="C" -->
1919  * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller)
1920  * const gchar *name = GET (traveller, name);
1921  * const gchar *quest = GET (traveller, quest);
1922  * GdkColor *favourite = GET (traveller, favourite_colour);
1923  * ]|
1924  *
1925  * is transformed by the preprocessor into:
1926  * |[<!-- language="C" -->
1927  * const gchar *name = traveller_get_name (traveller);
1928  * const gchar *quest = traveller_get_quest (traveller);
1929  * GdkColor *favourite = traveller_get_favourite_colour (traveller);
1930  * ]|
1931  *
1932  * Since: 2.20
1933  */
1934
1935 /**
1936  * G_STATIC_ASSERT:
1937  * @expr: a constant expression
1938  *
1939  * The G_STATIC_ASSERT() macro lets the programmer check
1940  * a condition at compile time, the condition needs to
1941  * be compile time computable. The macro can be used in
1942  * any place where a typedef is valid.
1943  *
1944  * A typedef is generally allowed in exactly the same places that
1945  * a variable declaration is allowed. For this reason, you should
1946  * not use G_STATIC_ASSERT() in the middle of blocks of code.
1947  *
1948  * The macro should only be used once per source code line.
1949  *
1950  * Since: 2.20
1951  */
1952
1953 /**
1954  * G_STATIC_ASSERT_EXPR:
1955  * @expr: a constant expression
1956  *
1957  * The G_STATIC_ASSERT_EXPR() macro lets the programmer check
1958  * a condition at compile time. The condition needs to be
1959  * compile time computable.
1960  *
1961  * Unlike G_STATIC_ASSERT(), this macro evaluates to an expression
1962  * and, as such, can be used in the middle of other expressions.
1963  * Its value should be ignored. This can be accomplished by placing
1964  * it as the first argument of a comma expression.
1965  *
1966  * |[<!-- language="C" -->
1967  * #define ADD_ONE_TO_INT(x) \
1968  *   (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1))
1969  * ]|
1970  *
1971  * Since: 2.30
1972  */
1973
1974 /**
1975  * G_GNUC_EXTENSION:
1976  *
1977  * Expands to __extension__ when gcc is used as the compiler. This simply
1978  * tells gcc not to warn about the following non-standard code when compiling
1979  * with the `-pedantic` option.
1980  */
1981
1982 /**
1983  * G_GNUC_CHECK_VERSION:
1984  * @major: major version to check against
1985  * @minor: minor version to check against
1986  *
1987  * Expands to a check for a compiler with __GNUC__ defined and a version
1988  * greater than or equal to the major and minor numbers provided. For example,
1989  * the following would only match on compilers such as GCC 4.8 or newer.
1990  *
1991  * |[<!-- language="C" -->
1992  * #if G_GNUC_CHECK_VERSION(4, 8)
1993  * #endif
1994  * ]|
1995  *
1996  * Since: 2.42
1997  */
1998
1999 /**
2000  * G_GNUC_BEGIN_IGNORE_DEPRECATIONS:
2001  *
2002  * Tells gcc (if it is a new enough version) to temporarily stop emitting
2003  * warnings when functions marked with %G_GNUC_DEPRECATED or
2004  * %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have
2005  * one deprecated function calling another one, or when you still have
2006  * regression tests for deprecated functions.
2007  *
2008  * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you
2009  * are not compiling with `-Wdeprecated-declarations` then neither macro
2010  * has any effect.)
2011  *
2012  * This macro can be used either inside or outside of a function body,
2013  * but must appear on a line by itself. Both this macro and the corresponding
2014  * %G_GNUC_END_IGNORE_DEPRECATIONS are considered statements, so they
2015  * should not be used around branching or loop conditions; for instance,
2016  * this use is invalid:
2017  *
2018  * |[<!-- language="C" -->
2019  *   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
2020  *   if (check == some_deprecated_function ())
2021  *   G_GNUC_END_IGNORE_DEPRECATIONS
2022  *     {
2023  *       do_something ();
2024  *     }
2025  * ]|
2026  *
2027  * and you should move the deprecated section outside the condition
2028  *
2029  * |[<!-- language="C" -->
2030  *
2031  *   // Solution A
2032  *   some_data_t *res;
2033  *
2034  *   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
2035  *   res = some_deprecated_function ();
2036  *   G_GNUC_END_IGNORE_DEPRECATIONS
2037  *
2038  *   if (check == res)
2039  *     {
2040  *       do_something ();
2041  *     }
2042  *
2043  *   // Solution B
2044  *   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
2045  *   if (check == some_deprecated_function ())
2046  *     {
2047  *       do_something ();
2048  *     }
2049  *   G_GNUC_END_IGNORE_DEPRECATIONS
2050  * ]|
2051  *
2052  * |[<!-- language="C" -->
2053  * static void
2054  * test_deprecated_function (void)
2055  * {
2056  *   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
2057  *   g_assert_cmpint (my_mistake (), ==, 42);
2058  *   G_GNUC_END_IGNORE_DEPRECATIONS
2059  * }
2060  * ]|
2061  *
2062  * Since: 2.32
2063  */
2064
2065 /**
2066  * G_GNUC_END_IGNORE_DEPRECATIONS:
2067  *
2068  * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling
2069  * gcc to begin outputting warnings again (assuming those warnings
2070  * had been enabled to begin with).
2071  *
2072  * This macro can be used either inside or outside of a function body,
2073  * but must appear on a line by itself.
2074  *
2075  * Since: 2.32
2076  */
2077
2078 /**
2079  * G_DEPRECATED:
2080  *
2081  * This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark
2082  * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is
2083  * meant to be portable across different compilers and must be placed
2084  * before the function declaration.
2085  *
2086  * |[<!-- language="C" -->
2087  * G_DEPRECATED
2088  * int my_mistake (void);
2089  * ]|
2090  *
2091  * Since: 2.32
2092  */
2093
2094 /**
2095  * G_DEPRECATED_FOR:
2096  * @f: the name of the function that this function was deprecated for
2097  *
2098  * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark
2099  * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it
2100  * is meant to be portable across different compilers and must be placed
2101  * before the function declaration.
2102  *
2103  * |[<!-- language="C" -->
2104  * G_DEPRECATED_FOR(my_replacement)
2105  * int my_mistake (void);
2106  * ]|
2107  *
2108  * Since: 2.32
2109  */
2110
2111 /**
2112  * G_UNAVAILABLE:
2113  * @maj: the major version that introduced the symbol
2114  * @min: the minor version that introduced the symbol
2115  *
2116  * This macro can be used to mark a function declaration as unavailable.
2117  * It must be placed before the function declaration. Use of a function
2118  * that has been annotated with this macros will produce a compiler warning.
2119  *
2120  * Since: 2.32
2121  */
2122
2123 /**
2124  * GLIB_DISABLE_DEPRECATION_WARNINGS:
2125  *
2126  * A macro that should be defined before including the glib.h header.
2127  * If it is defined, no compiler warnings will be produced for uses
2128  * of deprecated GLib APIs.
2129  */
2130
2131 /**
2132  * G_GNUC_INTERNAL:
2133  *
2134  * This attribute can be used for marking library functions as being used
2135  * internally to the library only, which may allow the compiler to handle
2136  * function calls more efficiently. Note that static functions do not need
2137  * to be marked as internal in this way. See the GNU C documentation for
2138  * details.
2139  *
2140  * When using a compiler that supports the GNU C hidden visibility attribute,
2141  * this macro expands to __attribute__((visibility("hidden"))).
2142  * When using the Sun Studio compiler, it expands to __hidden.
2143  *
2144  * Note that for portability, the attribute should be placed before the
2145  * function declaration. While GCC allows the macro after the declaration,
2146  * Sun Studio does not.
2147  *
2148  * |[<!-- language="C" -->
2149  * G_GNUC_INTERNAL
2150  * void _g_log_fallback_handler (const gchar    *log_domain,
2151  *                               GLogLevelFlags  log_level,
2152  *                               const gchar    *message,
2153  *                               gpointer        unused_data);
2154  * ]|
2155  *
2156  * Since: 2.6
2157  */
2158
2159 /**
2160  * G_LIKELY:
2161  * @expr: the expression
2162  *
2163  * Hints the compiler that the expression is likely to evaluate to
2164  * a true value. The compiler may use this information for optimizations.
2165  *
2166  * |[<!-- language="C" -->
2167  * if (G_LIKELY (random () != 1))
2168  *   g_print ("not one");
2169  * ]|
2170  *
2171  * Returns: the value of @expr
2172  *
2173  * Since: 2.2
2174  */
2175
2176 /**
2177  * G_UNLIKELY:
2178  * @expr: the expression
2179  *
2180  * Hints the compiler that the expression is unlikely to evaluate to
2181  * a true value. The compiler may use this information for optimizations.
2182  *
2183  * |[<!-- language="C" -->
2184  * if (G_UNLIKELY (random () == 1))
2185  *   g_print ("a random one");
2186  * ]|
2187  *
2188  * Returns: the value of @expr
2189  *
2190  * Since: 2.2
2191  */
2192
2193 /**
2194  * G_STRLOC:
2195  *
2196  * Expands to a string identifying the current code position.
2197  */
2198
2199 /**
2200  * G_STRFUNC:
2201  *
2202  * Expands to a string identifying the current function.
2203  *
2204  * Since: 2.4
2205  */
2206
2207 /**
2208  * G_HAVE_GNUC_VISIBILITY:
2209  *
2210  * Defined to 1 if gcc-style visibility handling is supported.
2211  */
2212
2213 /* g_auto(), g_autoptr() and helpers {{{1 */
2214
2215 /**
2216  * g_auto:
2217  * @TypeName: a supported variable type
2218  *
2219  * Helper to declare a variable with automatic cleanup.
2220  *
2221  * The variable is cleaned up in a way appropriate to its type when the
2222  * variable goes out of scope.  The type must support this.
2223  * The way to clean up the type must have been defined using one of the macros
2224  * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC() or G_DEFINE_AUTO_CLEANUP_FREE_FUNC().
2225  *
2226  * This feature is only supported on GCC and clang.  This macro is not
2227  * defined on other compilers and should not be used in programs that
2228  * are intended to be portable to those compilers.
2229  *
2230  * This is meant to be used with stack-allocated structures and
2231  * non-pointer types.  For the (more commonly used) pointer version, see
2232  * g_autoptr().
2233  *
2234  * This macro can be used to avoid having to do explicit cleanups of
2235  * local variables when exiting functions.  It often vastly simplifies
2236  * handling of error conditions, removing the need for various tricks
2237  * such as `goto out` or repeating of cleanup code.  It is also helpful
2238  * for non-error cases.
2239  *
2240  * Consider the following example:
2241  *
2242  * |[
2243  * GVariant *
2244  * my_func(void)
2245  * {
2246  *   g_auto(GQueue) queue = G_QUEUE_INIT;
2247  *   g_auto(GVariantBuilder) builder;
2248  *   g_auto(GStrv) strv;
2249  *
2250  *   g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT);
2251  *   strv = g_strsplit("a:b:c", ":", -1);
2252  *
2253  *   ...
2254  *
2255  *   if (error_condition)
2256  *     return NULL;
2257  *
2258  *   ...
2259  *
2260  *   return g_variant_builder_end (&builder);
2261  * }
2262  * ]|
2263  *
2264  * You must initialize the variable in some way — either by use of an
2265  * initialiser or by ensuring that an `_init` function will be called on
2266  * it unconditionally before it goes out of scope.
2267  *
2268  * Since: 2.44
2269  */
2270
2271 /**
2272  * g_autoptr:
2273  * @TypeName: a supported variable type
2274  *
2275  * Helper to declare a pointer variable with automatic cleanup.
2276  *
2277  * The variable is cleaned up in a way appropriate to its type when the
2278  * variable goes out of scope.  The type must support this.
2279  * The way to clean up the type must have been defined using the macro
2280  * G_DEFINE_AUTOPTR_CLEANUP_FUNC().
2281  *
2282  * This feature is only supported on GCC and clang.  This macro is not
2283  * defined on other compilers and should not be used in programs that
2284  * are intended to be portable to those compilers.
2285  *
2286  * This is meant to be used to declare pointers to types with cleanup
2287  * functions.  The type of the variable is a pointer to @TypeName.  You
2288  * must not add your own `*`.
2289  *
2290  * This macro can be used to avoid having to do explicit cleanups of
2291  * local variables when exiting functions.  It often vastly simplifies
2292  * handling of error conditions, removing the need for various tricks
2293  * such as `goto out` or repeating of cleanup code.  It is also helpful
2294  * for non-error cases.
2295  *
2296  * Consider the following example:
2297  *
2298  * |[
2299  * gboolean
2300  * check_exists(GVariant *dict)
2301  * {
2302  *   g_autoptr(GVariant) dirname, basename = NULL;
2303  *   g_autofree gchar *path = NULL;
2304  *
2305  *   dirname = g_variant_lookup_value (dict, "dirname", G_VARIANT_TYPE_STRING);
2306  *
2307  *   if (dirname == NULL)
2308  *     return FALSE;
2309  *
2310  *   basename = g_variant_lookup_value (dict, "basename", G_VARIANT_TYPE_STRING);
2311  *
2312  *   if (basename == NULL)
2313  *     return FALSE;
2314  *
2315  *   path = g_build_filename (g_variant_get_string (dirname, NULL),
2316  *                            g_variant_get_string (basename, NULL),
2317  *                            NULL);
2318  *
2319  *   return g_access (path, R_OK) == 0;
2320  * }
2321  * ]|
2322  *
2323  * You must initialise the variable in some way — either by use of an
2324  * initialiser or by ensuring that it is assigned to unconditionally
2325  * before it goes out of scope.
2326  *
2327  * See also g_auto(), g_autofree() and g_steal_pointer().
2328  *
2329  * Since: 2.44
2330  */
2331
2332 /**
2333  * g_autofree:
2334  *
2335  * Macro to add an attribute to pointer variable to ensure automatic
2336  * cleanup using g_free().
2337  *
2338  * This macro differs from g_autoptr() in that it is an attribute supplied
2339  * before the type name, rather than wrapping the type definition.  Instead
2340  * of using a type-specific lookup, this macro always calls g_free() directly.
2341  *
2342  * This means it's useful for any type that is returned from
2343  * g_malloc().
2344  *
2345  * Otherwise, this macro has similar constraints as g_autoptr(): only
2346  * supported on GCC and clang, the variable must be initialized, etc.
2347  *
2348  * |[
2349  * gboolean
2350  * operate_on_malloc_buf (void)
2351  * {
2352  *   g_autofree guint8* membuf = NULL;
2353  *
2354  *   membuf = g_malloc (8192);
2355  *
2356  *   // Some computation on membuf
2357  *
2358  *   // membuf will be automatically freed here
2359  *   return TRUE;
2360  * }
2361  * ]|
2362  *
2363  * Since: 2.44
2364  */
2365
2366 /**
2367  * g_autolist:
2368  * @TypeName: a supported variable type
2369  *
2370  * Helper to declare a list variable with automatic deep cleanup.
2371  *
2372  * The list is deeply freed, in a way appropriate to the specified type, when the
2373  * variable goes out of scope.  The type must support this.
2374  *
2375  * This feature is only supported on GCC and clang.  This macro is not
2376  * defined on other compilers and should not be used in programs that
2377  * are intended to be portable to those compilers.
2378  *
2379  * This is meant to be used to declare lists of a type with a cleanup
2380  * function.  The type of the variable is a `GList *`.  You
2381  * must not add your own `*`.
2382  *
2383  * This macro can be used to avoid having to do explicit cleanups of
2384  * local variables when exiting functions.  It often vastly simplifies
2385  * handling of error conditions, removing the need for various tricks
2386  * such as `goto out` or repeating of cleanup code.  It is also helpful
2387  * for non-error cases.
2388  *
2389  * See also g_autoslist(), g_autoptr() and g_steal_pointer().
2390  *
2391  * Since: 2.56
2392  */
2393
2394 /**
2395  * g_autoslist:
2396  * @TypeName: a supported variable type
2397  *
2398  * Helper to declare a singly linked list variable with automatic deep cleanup.
2399  *
2400  * The list is deeply freed, in a way appropriate to the specified type, when the
2401  * variable goes out of scope.  The type must support this.
2402  *
2403  * This feature is only supported on GCC and clang.  This macro is not
2404  * defined on other compilers and should not be used in programs that
2405  * are intended to be portable to those compilers.
2406  *
2407  * This is meant to be used to declare lists of a type with a cleanup
2408  * function.  The type of the variable is a `GSList *`.  You
2409  * must not add your own `*`.
2410  *
2411  * This macro can be used to avoid having to do explicit cleanups of
2412  * local variables when exiting functions.  It often vastly simplifies
2413  * handling of error conditions, removing the need for various tricks
2414  * such as `goto out` or repeating of cleanup code.  It is also helpful
2415  * for non-error cases.
2416  *
2417  * See also g_autolist(), g_autoptr() and g_steal_pointer().
2418  *
2419  * Since: 2.56
2420  */
2421
2422 /**
2423  * g_autoqueue:
2424  * @TypeName: a supported variable type
2425  *
2426  * Helper to declare a double-ended queue variable with automatic deep cleanup.
2427  *
2428  * The queue is deeply freed, in a way appropriate to the specified type, when the
2429  * variable goes out of scope.  The type must support this.
2430  *
2431  * This feature is only supported on GCC and clang.  This macro is not
2432  * defined on other compilers and should not be used in programs that
2433  * are intended to be portable to those compilers.
2434  *
2435  * This is meant to be used to declare queues of a type with a cleanup
2436  * function.  The type of the variable is a `GQueue *`.  You
2437  * must not add your own `*`.
2438  *
2439  * This macro can be used to avoid having to do explicit cleanups of
2440  * local variables when exiting functions.  It often vastly simplifies
2441  * handling of error conditions, removing the need for various tricks
2442  * such as `goto out` or repeating of cleanup code.  It is also helpful
2443  * for non-error cases.
2444  *
2445  * See also g_autolist(), g_autoptr() and g_steal_pointer().
2446  *
2447  * Since: 2.62
2448  */
2449
2450
2451 /**
2452  * G_DEFINE_AUTOPTR_CLEANUP_FUNC:
2453  * @TypeName: a type name to define a g_autoptr() cleanup function for
2454  * @func: the cleanup function
2455  *
2456  * Defines the appropriate cleanup function for a pointer type.
2457  *
2458  * The function will not be called if the variable to be cleaned up
2459  * contains %NULL.
2460  *
2461  * This will typically be the `_free()` or `_unref()` function for the given
2462  * type.
2463  *
2464  * With this definition, it will be possible to use g_autoptr() with
2465  * @TypeName.
2466  *
2467  * |[
2468  * G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref)
2469  * ]|
2470  *
2471  * This macro should be used unconditionally; it is a no-op on compilers
2472  * where cleanup is not supported.
2473  *
2474  * Since: 2.44
2475  */
2476
2477 /**
2478  * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC:
2479  * @TypeName: a type name to define a g_auto() cleanup function for
2480  * @func: the clear function
2481  *
2482  * Defines the appropriate cleanup function for a type.
2483  *
2484  * This will typically be the `_clear()` function for the given type.
2485  *
2486  * With this definition, it will be possible to use g_auto() with
2487  * @TypeName.
2488  *
2489  * |[
2490  * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear)
2491  * ]|
2492  *
2493  * This macro should be used unconditionally; it is a no-op on compilers
2494  * where cleanup is not supported.
2495  *
2496  * Since: 2.44
2497  */
2498
2499 /**
2500  * G_DEFINE_AUTO_CLEANUP_FREE_FUNC:
2501  * @TypeName: a type name to define a g_auto() cleanup function for
2502  * @func: the free function
2503  * @none: the "none" value for the type
2504  *
2505  * Defines the appropriate cleanup function for a type.
2506  *
2507  * With this definition, it will be possible to use g_auto() with
2508  * @TypeName.
2509  *
2510  * This function will be rarely used.  It is used with pointer-based
2511  * typedefs and non-pointer types where the value of the variable
2512  * represents a resource that must be freed.  Two examples are #GStrv
2513  * and file descriptors.
2514  *
2515  * @none specifies the "none" value for the type in question.  It is
2516  * probably something like %NULL or `-1`.  If the variable is found to
2517  * contain this value then the free function will not be called.
2518  *
2519  * |[
2520  * G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL)
2521  * ]|
2522  *
2523  * This macro should be used unconditionally; it is a no-op on compilers
2524  * where cleanup is not supported.
2525  *
2526  * Since: 2.44
2527  */
2528
2529 /* Warnings and Assertions {{{1 */
2530
2531 /**
2532  * SECTION:warnings
2533  * @title: Warnings and Assertions
2534  * @short_description: warnings and assertions to use in runtime code
2535  *
2536  * GLib defines several warning functions and assertions which can be used to
2537  * warn of programmer errors when calling functions, and print error messages
2538  * from command line programs.
2539  *
2540  * The g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
2541  * g_return_val_if_reached() macros are intended as pre-condition assertions, to
2542  * be used at the top of a public function to check that the function’s
2543  * arguments are acceptable. Any failure of such a pre-condition assertion is
2544  * considered a programming error on the part of the caller of the public API,
2545  * and the program is considered to be in an undefined state afterwards. They
2546  * are similar to the libc assert() function, but provide more context on
2547  * failures.
2548  *
2549  * For example:
2550  * |[<!-- language="C" -->
2551  * gboolean
2552  * g_dtls_connection_shutdown (GDtlsConnection  *conn,
2553  *                             gboolean          shutdown_read,
2554  *                             gboolean          shutdown_write,
2555  *                             GCancellable     *cancellable,
2556  *                             GError          **error)
2557  * {
2558  *   // local variable declarations
2559  *
2560  *   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
2561  *   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
2562  *   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
2563  *
2564  *   // function body
2565  *
2566  *   return return_val;
2567  * }
2568  * ]|
2569  *
2570  * g_print(), g_printerr() and g_set_print_handler() are intended to be used for
2571  * output from command line applications, since they output to standard output
2572  * and standard error by default — whereas functions like g_message() and
2573  * g_log() may be redirected to special purpose message windows, files, or the
2574  * system journal.
2575  */
2576
2577 /* Windows Compatibility Functions {{{1 */
2578
2579 /**
2580  * SECTION:windows
2581  * @title: Windows Compatibility Functions
2582  * @short_description: UNIX emulation on Windows
2583  *
2584  * These functions provide some level of UNIX emulation on the
2585  * Windows platform. If your application really needs the POSIX
2586  * APIs, we suggest you try the Cygwin project.
2587  */
2588
2589 /**
2590  * MAXPATHLEN:
2591  *
2592  * Provided for UNIX emulation on Windows; equivalent to UNIX
2593  * macro %MAXPATHLEN, which is the maximum length of a filename
2594  * (including full path).
2595  */
2596
2597 /**
2598  * G_WIN32_DLLMAIN_FOR_DLL_NAME:
2599  * @static: empty or "static"
2600  * @dll_name: the name of the (pointer to the) char array where
2601  *     the DLL name will be stored. If this is used, you must also
2602  *     include `windows.h`. If you need a more complex DLL entry
2603  *     point function, you cannot use this
2604  *
2605  * On Windows, this macro defines a DllMain() function that stores
2606  * the actual DLL name that the code being compiled will be included in.
2607  *
2608  * On non-Windows platforms, expands to nothing.
2609  */
2610
2611 /**
2612  * G_WIN32_HAVE_WIDECHAR_API:
2613  *
2614  * On Windows, this macro defines an expression which evaluates to
2615  * %TRUE if the code is running on a version of Windows where the wide
2616  * character versions of the Win32 API functions, and the wide character
2617  * versions of the C library functions work. (They are always present in
2618  * the DLLs, but don't work on Windows 9x and Me.)
2619  *
2620  * On non-Windows platforms, it is not defined.
2621  *
2622  * Since: 2.6
2623  */
2624
2625
2626 /**
2627  * G_WIN32_IS_NT_BASED:
2628  *
2629  * On Windows, this macro defines an expression which evaluates to
2630  * %TRUE if the code is running on an NT-based Windows operating system.
2631  *
2632  * On non-Windows platforms, it is not defined.
2633  *
2634  * Since: 2.6
2635  */
2636
2637  /* Epilogue {{{1 */
2638 /* vim: set foldmethod=marker: */