glib/docs.c

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