From 6a22d58f6bf00aa7eceec38a2ca2ff5fb3f37a75 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 23 Nov 2023 16:17:04 +0000 Subject: [PATCH] docs: Move the types SECTION Move it to a mega separate file. This has been a journey. Signed-off-by: Philip Withnall Helps: #3037 --- docs/reference/glib/glib.toml.in | 1 + docs/reference/glib/meson.build | 1 + docs/reference/glib/types.md | 882 +++++++++++++++++++++++++ glib/docs.c | 1036 ------------------------------ 4 files changed, 884 insertions(+), 1036 deletions(-) create mode 100644 docs/reference/glib/types.md diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in index 4c0a1fd74..2dc64b5cf 100644 --- a/docs/reference/glib/glib.toml.in +++ b/docs/reference/glib/glib.toml.in @@ -53,6 +53,7 @@ content_files = [ "string-utils.md", + "types.md", "macros.md", "conversion-macros.md", "auto-cleanup.md", diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build index b1f9ea18c..6a9830570 100644 --- a/docs/reference/glib/meson.build +++ b/docs/reference/glib/meson.build @@ -177,6 +177,7 @@ expand_content_files = [ 'shell.md', 'spawn.md', 'string-utils.md', + 'types.md', 'unicode.md', 'unix.md', 'uuid.md', diff --git a/docs/reference/glib/types.md b/docs/reference/glib/types.md new file mode 100644 index 000000000..aab0bd078 --- /dev/null +++ b/docs/reference/glib/types.md @@ -0,0 +1,882 @@ +Title: Basic Types +SPDX-License-Identifier: LGPL-2.1-or-later +SPDX-FileCopyrightText: 1999 Owen Taylor +SPDX-FileCopyrightText: 2000 Red Hat, Inc. +SPDX-FileCopyrightText: 2000 Sebastian Wilhelmi +SPDX-FileCopyrightText: 2008 Matthias Clasen +SPDX-FileCopyrightText: 2008, 2010 Behdad Esfahbod +SPDX-FileCopyrightText: 2009 Christian Persch +SPDX-FileCopyrightText: 2014, 2022 Collabora, Ltd. +SPDX-FileCopyrightText: 2017, 2018 Endless Mobile, Inc. +SPDX-FileCopyrightText: 2018 Christoph Reiter +SPDX-FileCopyrightText: 2019 Alistair Thomas + +# Basic Types + +GLib defines a number of commonly used types, which can be divided +into several groups: + + - New types which are not part of standard C (but are defined in + various C standard library header files) — [`gboolean`](#gboolean), + [`gssize`](#gssize). + - Integer types which are guaranteed to be the same size across + all platforms — [`gint8`](#gint8), [`guint8`](#guint8), [`gint16`](#gint16), + [`guint16`](#guint16), [`gint32`](#gint32), [`guint32`](#guint32), + [`gint64`](#gint64), [`guint64`](#guint64). + - Types which are easier to use than their standard C counterparts — + [`gpointer`](#gpointer), [`gconstpointer`](#gconstpointer), + [`guchar`](#guchar), [`guint`](#guint), [`gushort`](#gushort), + [`gulong`](#gulong). + - Types which correspond exactly to standard C types, but are + included for completeness — [`gchar`](#gchar), [`gint`](#gint), + [`gshort`](#gshort), [`glong`](#glong), [`gfloat`](#gfloat), + [`gdouble`](#gdouble). + - Types which correspond exactly to standard C99 types, but are available + to use even if your compiler does not support C99 — [`gsize`](#gsize), + [`goffset`](#goffset), [`gintptr`](#gintptr), [`guintptr`](#guintptr). + +GLib also defines macros for the limits of some of the standard +integer and floating point types, as well as macros for suitable +[`printf()`](man:printf(3)) formats for these types. + +Note that depending on the platform and build configuration, the format +macros might not be compatible with the system provided +[`printf()`](man:printf(3)) function, because GLib might use a different +`printf()` implementation internally. The format macros will always work with +GLib API (like [func@GLib.print]), and with any C99 compatible `printf()` +implementation. + +## Basic Types + +### `gboolean` + +A standard boolean type. Variables of this type should only contain the value +`TRUE` or `FALSE`. + +Never directly compare the contents of a `gboolean` variable with the values +`TRUE` or `FALSE`. Use `if (condition)` to check a `gboolean` is ‘true’, instead +of `if (condition == TRUE)`. Likewise use `if (!condition)` to check a +`gboolean` is ‘false’. + +There is no validation when assigning to a `gboolean` variable and so it could +contain any value represented by a `gint`. This is why the use of `if +(condition)` is recommended. All non-zero values in C evaluate to ‘true’. + +### `gpointer` + +An untyped pointer, exactly equivalent to `void *`. + +The standard C `void *` type should usually be preferred in +new code, but `gpointer` can be used in contexts where a type name +must be a single word, such as in the [method@GObject.Type.name] of +[const@GObject.TYPE_POINTER] or when generating a family of function names for +multiple types using macros. + +### `gconstpointer` + +An untyped pointer to constant data, exactly equivalent to `const void *`. + +The data pointed to should not be changed. + +This is typically used in function prototypes to indicate +that the data pointed to will not be altered by the function. + +The standard C `const void *` type should usually be preferred in +new code, but `gconstpointer` can be used in contexts where a type name +must be a single word. + +### `gchar` + +Equivalent to the standard C `char` type. + +This type only exists for symmetry with `guchar`. +The standard C `char` type should be preferred in new code. + +### `guchar` + +Equivalent to the standard C `unsigned char` type. + +The standard C `unsigned char` type should usually be preferred in +new code, but `guchar` can be used in contexts where a type name +must be a single word, such as in the [method@GObject.Type.name] of +[const@GObject.TYPE_UCHAR] or when generating a family of function names for +multiple types using macros. + +## Naturally Sized Integers + +### `gint` + +Equivalent to the standard C `int` type. + +Values of this type can range from `INT_MIN` to `INT_MAX`, +or equivalently from `G_MININT` to `G_MAXINT`. + +This type only exists for symmetry with [`guint`](#guint). +The standard C `int` type should be preferred in new code. + +`G_MININT` +: The minimum value which can be held in a `gint`. + + This is the same as standard C `INT_MIN`, which is available since C99 + and should be preferred in new code. + +`G_MAXINT` +: The maximum value which can be held in a `gint`. + + This is the same as standard C `INT_MAX`, which is available since C99 + and should be preferred in new code. + +### `guint` + +Equivalent to the standard C `unsigned int` type. + +Values of this type can range from `0` to `UINT_MAX`, +or equivalently `0` to `G_MAXUINT`. + +The standard C `unsigned int` type should usually be preferred in +new code, but `guint` can be used in contexts where a type name +must be a single word, such as in the [method@GObject.Type.name] of +[const@GObject.TYPE_UINT] or when generating a family of function names for +multiple types using macros. + +`G_MAXUINT` +: The maximum value which can be held in a `guint`. + + This is the same as standard C `UINT_MAX`, which is available since C99 + and should be preferred in new code. + +### `gshort` + +Equivalent to the standard C `short` type. + +Values of this type can range from `SHRT_MIN` to `SHRT_MAX`, +or equivalently `G_MINSHORT` to `G_MAXSHORT`. + +This type only exists for symmetry with `gushort`. +The standard C `short` type should be preferred in new code. + +`G_MINSHORT` +: The minimum value which can be held in a `gshort`. + + This is the same as standard C `SHRT_MIN`, which is available since C99 + and should be preferred in new code. + +`G_MAXSHORT` +: The maximum value which can be held in a `gshort`. + + This is the same as standard C `SHRT_MAX`, which is available since C99 + and should be preferred in new code. + +### `gushort` + +Equivalent to the standard C `unsigned short` type. + +Values of this type can range from `0` to `USHRT_MAX`, +or equivalently from `0` to `G_MAXUSHORT`. + +The standard C `unsigned short` type should usually be preferred in +new code, but `gushort` can be used in contexts where a type name +must be a single word, such as when generating a family of function +names for multiple types using macros. + + +`G_MAXUSHORT` +: The maximum value which can be held in a `gushort`. + + This is the same as standard C `USHRT_MAX`, which is available since C99 + and should be preferred in new code. + +### `glong` + +Equivalent to the standard C `long` type. + +Values of this type can range from `LONG_MIN` to `LONG_MAX`, +or equivalently `G_MINLONG` to `G_MAXLONG`. + +This type only exists for symmetry with `gulong`. +The standard C `long` type should be preferred in new code. + +`G_MINLONG` +: The minimum value which can be held in a `glong`. + + This is the same as standard C `LONG_MIN`, which is available since C99 + and should be preferred in new code. + +`G_MAXLONG` +: The maximum value which can be held in a `glong`. + + This is the same as standard C `ULONG_MAX`, which is available since C99 + and should be preferred in new code. + +### `gulong` + +Equivalent to the standard C `unsigned long` type. + +Values of this type can range from `0` to `G_MAXULONG`. + +The standard C `unsigned long` type should usually be preferred in +new code, but `gulong` can be used in contexts where a type name +must be a single word, such as in the [method@GObject.Type.name] of +[const@GObject.TYPE_ULONG] or when generating a family of function names for +multiple types using macros. + +`G_MAXULONG` +: The maximum value which can be held in a `gulong`. + + This is the same as standard C `ULONG_MAX`, which is available since C99 + and should be preferred in new code. + +## Fixed Width Integers + +### `gint8` + +A signed integer guaranteed to be 8 bits on all platforms, +similar to the standard C `int8_t`. + +The `int8_t` type should be preferred in new code, unless +consistency with pre-existing APIs requires use of `gint8` +(see [`gsize`](#gsize) for more details). + +Values of this type can range from `G_MININT8` (= -128) to +`G_MAXINT8` (= 127). + +`G_MININT8` +: The minimum value which can be held in a `gint8`. + + Since: 2.4 + +`G_MAXINT8` +: The maximum value which can be held in a `gint8`. + + This is the same as standard C `INT8_MAX`, which should be + preferred in new code. + + Since: 2.4 + +### `guint8` + +An unsigned integer guaranteed to be 8 bits on all platforms, +similar to the standard C `uint8_t`. + +The `uint8_t` type should be preferred in new code, unless +consistency with pre-existing APIs requires use of `guint8` +(see [`gsize`](#gsize) for more details). + +Values of this type can range from `0` to `G_MAXUINT8` (= 255). + +`G_MAXUINT8` +: The maximum value which can be held in a `guint8`. + + This is the same as standard C `UINT8_MAX`, which should be + preferred in new code. + + Since: 2.4 + +### `gint16` + +A signed integer guaranteed to be 16 bits on all platforms, +similar to the standard C `int16_t`. + +The `int16_t` type should be preferred in new code, unless +consistency with pre-existing APIs requires use of `gint16` +(see [`gsize`](#gsize) for more details). + +Values of this type can range from `G_MININT16` (= -32,768) to +`G_MAXINT16` (= 32,767). + +To print or scan values of this type, use +`G_GINT16_MODIFIER` and/or `G_GINT16_FORMAT`. + +`G_MININT16` +: The minimum value which can be held in a `gint16`. + + Since: 2.4 + +`G_MAXINT16` +: The maximum value which can be held in a `gint16`. + + This is the same as standard C `INT16_MAX`, which should be + preferred in new code. + + Since: 2.4 + +`G_GINT16_MODIFIER` +: The platform dependent length modifier for conversion specifiers + for scanning and printing values of type `gint16` or `guint16`. It + is a string literal, but doesn’t include the percent-sign, such + that you can add precision and length modifiers between percent-sign + and conversion specifier and append a conversion specifier. + + The following example prints `0x7b`; + ```c + gint16 value = 123; + g_print ("%#" G_GINT16_MODIFIER "x", value); + ``` + + This is not necessarily the correct modifier for printing and scanning + `int16_t` values, even though the in-memory representation is the same. + Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`. + + Since: 2.4 + +`G_GINT16_FORMAT` +: This is the platform dependent conversion specifier for scanning and + printing values of type `gint16`. It is a string literal, but doesn’t + include the percent-sign, such that you can add precision and length + modifiers between percent-sign and conversion specifier. + + ```c + gint16 in; + gint32 out; + sscanf ("42", "%" G_GINT16_FORMAT, &in) + out = in * 1000; + g_print ("%" G_GINT32_FORMAT, out); + ``` + + This is not necessarily the correct format for printing and scanning + `int16_t` values, even though the in-memory representation is the same. + Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`. + +### `guint16` + +An unsigned integer guaranteed to be 16 bits on all platforms, +similar to the standard C `uint16_t`. + +The `uint16_t` type should be preferred in new code, unless +consistency with pre-existing APIs requires use of `guint16` +(see [`gsize`](#gsize) for more details). + +Values of this type can range from `0` to `G_MAXUINT16` (= 65,535). + +To print or scan values of this type, use +`G_GINT16_MODIFIER` and/or `G_GUINT16_FORMAT`. + +`G_MAXUINT16` +: The maximum value which can be held in a `guint16`. + + This is the same as standard C `UINT16_MAX`, which should be + preferred in new code. + + Since: 2.4 + +`G_GUINT16_FORMAT` +: This is the platform dependent conversion specifier for scanning + and printing values of type `guint16`. See also `G_GINT16_FORMAT` + + This is not necessarily the correct modifier for printing and scanning + `uint16_t` values, even though the in-memory representation is the same. + Standard C macros like `PRIu16` and `SCNu16` should be used for `uint16_t`. + +### `gint32` + +A signed integer guaranteed to be 32 bits on all platforms. + +The `int32_t` type should be preferred in new code, unless +consistency with pre-existing APIs requires use of `gint16` +(see [`gsize`](#gsize) for more details). + +Values of this type can range from `G_MININT32` (= -2,147,483,648) +to `G_MAXINT32` (= 2,147,483,647). + +To print or scan values of this type, use +`G_GINT32_MODIFIER` and/or `G_GINT32_FORMAT`. + +Note that on platforms with more than one 32-bit standard integer type, +`gint32` and `int32_t` are not necessarily implemented by the same +32-bit integer type. +For example, on an ILP32 platform where `int` and `long` are both 32-bit, +it might be the case that one of these types is `int` and the other +is `long`. +See [`gsize`](#gsize) for more details of what this implies. + +`G_MININT32` +: The minimum value which can be held in a `gint32`. + + Since: 2.4 + +`G_MAXINT32` +: The maximum value which can be held in a `gint32`. + + This is the same as standard C `INT32_MAX`, which should be + preferred in new code. + + Since: 2.4 + +`G_GINT32_MODIFIER` +: The platform dependent length modifier for conversion specifiers + for scanning and printing values of type `gint32` or `guint32`. It + is a string literal. See also `G_GINT16_MODIFIER`. + + This is not necessarily the correct modifier for printing and scanning + `int32_t` values, even though the in-memory representation is the same. + Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`. + + Since: 2.4 + +`G_GINT32_FORMAT` +: This is the platform dependent conversion specifier for scanning + and printing values of type `gint32`. See also `G_GINT16_FORMAT`. + + This is not necessarily the correct modifier for printing and scanning + `int32_t` values, even though the in-memory representation is the same. + Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`. + +### `guint32` + +An unsigned integer guaranteed to be 32 bits on all platforms, +similar to the standard C `uint32_t`. + +The `uint32_t` type should be preferred in new code, unless +consistency with pre-existing APIs requires use of `guint32` +(see [`gsize`](#gsize) for more details). + +Values of this type can range from `0` to `G_MAXUINT32` (= 4,294,967,295). + +To print or scan values of this type, use +`G_GINT32_MODIFIER` and/or `G_GUINT32_FORMAT`. + +Note that on platforms with more than one 32-bit standard integer type, +`guint32` and `uint32_t` are not necessarily implemented by the same +32-bit integer type. +See [`gsize`](#gsize) for more details of what this implies. + +`G_MAXUINT32` +: The maximum value which can be held in a `guint32`. + + This is the same as standard C `UINT32_MAX`, which should be + preferred in new code. + + Since: 2.4 + +`G_GUINT32_FORMAT` +: This is the platform dependent conversion specifier for scanning + and printing values of type `guint32`. See also `G_GINT16_FORMAT`. + + This is not necessarily the correct modifier for printing and scanning + `uint32_t` values, even though the in-memory representation is the same. + Standard C macros like `PRIu32` and `SCNu32` should be used for `uint32_t`. + +### `gint64` + +A signed integer guaranteed to be 64 bits on all platforms, +similar to the standard C `int64_t`. + +The `int64_t` type should be preferred in new code, unless +consistency with pre-existing APIs requires use of `gint64` +(see [`gsize`](#gsize) for more details). + +Values of this type can range from `G_MININT64` +(= -9,223,372,036,854,775,808) to `G_MAXINT64` +(= 9,223,372,036,854,775,807). + +To print or scan values of this type, use +`G_GINT64_MODIFIER` and/or `G_GINT64_FORMAT`. + +Note that on platforms with more than one 64-bit standard integer type, +`gint64` and `int64_t` are not necessarily implemented by the same +64-bit integer type. +For example, on a platform where both `long` and `long long` are 64-bit, +it might be the case that one of those types is used for `gint64` +and the other is used for `int64_t`. +See [`gsize`](#gsize) for more details of what this implies. + +`G_MININT64` +: The minimum value which can be held in a `gint64`. + +`G_MAXINT64` +: The maximum value which can be held in a `gint64`. + +`G_GINT64_MODIFIER` +: The platform dependent length modifier for conversion specifiers + for scanning and printing values of type `gint64` or `guint64`. + It is a string literal. + + Some platforms do not support printing 64-bit integers, even + though the types are supported. On such platforms `G_GINT64_MODIFIER` + is not defined. + + This is not necessarily the correct modifier for printing and scanning + `int64_t` values, even though the in-memory representation is the same. + Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`. + + Since: 2.4 + +`G_GINT64_FORMAT` +: This is the platform dependent conversion specifier for scanning + and printing values of type `gint64`. See also `G_GINT16_FORMAT`. + + Some platforms do not support scanning and printing 64-bit integers, + even though the types are supported. On such platforms `G_GINT64_FORMAT` + is not defined. Note that [`scanf()`](man:scanf(3)) may not support 64-bit + integers, even if `G_GINT64_FORMAT` is defined. Due to its weak error + handling, `scanf()` is not recommended for parsing anyway; consider using + [func@GLib.ascii_strtoull] instead. + + This is not necessarily the correct format for printing and scanning + `int64_t` values, even though the in-memory representation is the same. + Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`. + +`G_GINT64_CONSTANT(val)` +: This macro is used to insert 64-bit integer literals + into the source code. + + It is similar to the standard C `INT64_C` macro, + which should be preferred in new code. + +### `guint64` + +An unsigned integer guaranteed to be 64-bits on all platforms, +similar to the standard C `uint64_t` type. + +The `uint64_t` type should be preferred in new code, unless +consistency with pre-existing APIs requires use of `guint64` +(see [`gsize`](#gsize) for more details). + +Values of this type can range from `0` to `G_MAXUINT64` +(= 18,446,744,073,709,551,615). + +To print or scan values of this type, use +`G_GINT64_MODIFIER` and/or `G_GUINT64_FORMAT`. + +Note that on platforms with more than one 64-bit standard integer type, +`guint64` and `uint64_t` are not necessarily implemented by the same +64-bit integer type. +See [`gsize`](#gsize) for more details of what this implies. + +`G_MAXUINT64` +: The maximum value which can be held in a `guint64`. + + This is the same as standard C `UINT64_MAX`, which should be + preferred in new code. + +`G_GUINT64_FORMAT` +: This is the platform dependent conversion specifier for scanning + and printing values of type `guint64`. See also `G_GINT16_FORMAT`. + + Some platforms do not support scanning and printing 64-bit integers, + even though the types are supported. On such platforms `G_GUINT64_FORMAT` + is not defined. Note that [`scanf()`](man:scanf(3)) may not support 64-bit + integers, even if `G_GINT64_FORMAT` is defined. Due to its weak error + handling, `scanf()` is not recommended for parsing anyway; consider using + [func@GLib.ascii_strtoull] instead. + + This is not necessarily the correct modifier for printing and scanning + `uint64_t` values, even though the in-memory representation is the same. + Standard C macros like `PRIu64` and `SCNu64` should be used for `uint64_t`. + +`G_GUINT64_CONSTANT(val)` +: This macro is used to insert 64-bit unsigned integer + literals into the source code. + + It is similar to the standard C `UINT64_C` macro, + which should be preferred in new code. + + Since: 2.10 + +## Floating Point + +### `gfloat` + +Equivalent to the standard C `float` type. + +Values of this type can range from `-FLT_MAX` to `FLT_MAX`, +or equivalently from `-G_MAXFLOAT` to `G_MAXFLOAT`. + +`G_MINFLOAT` +: The minimum positive value which can be held in a `gfloat`. + + If you are interested in the smallest value which can be held + in a `gfloat`, use `-G_MAXFLOAT`. + + This is the same as standard C `FLT_MIN`, which is available since C99 + and should be preferred in new code. + +`G_MAXFLOAT` +: The maximum value which can be held in a `gfloat`. + + This is the same as standard C `FLT_MAX`, which is available since C99 + and should be preferred in new code. + +### `gdouble` + +Equivalent to the standard C `double` type. + +Values of this type can range from `-DBL_MAX` to `DBL_MAX`, +or equivalently from `-G_MAXDOUBLE` to `G_MAXDOUBLE`. + +`G_MINDOUBLE` +: The minimum positive value which can be held in a `gdouble`. + + If you are interested in the smallest value which can be held + in a `gdouble`, use `-G_MAXDOUBLE`. + + This is the same as standard C `DBL_MIN`, which is available since C99 + and should be preferred in new code. + +`G_MAXDOUBLE` +: The maximum value which can be held in a `gdouble`. + + This is the same as standard C `DBL_MAX`, which is available since C99 + and should be preferred in new code. + +## Architecture Sized Integers + +### `gsize` + +An unsigned integer type of the result of the `sizeof` operator, +corresponding to the `size_t` type defined in C99. + +The standard `size_t` type should be preferred in new code, unless +consistency with pre-existing APIs requires `gsize` +(see below for more details). + +`gsize` is usually 32 bit wide on a 32-bit platform and 64 bit wide +on a 64-bit platform. Values of this type can range from `0` to +`G_MAXSIZE`. + +This type is wide enough to hold the size of the largest possible +memory allocation, but is not guaranteed to be wide enough to hold +the numeric value of a pointer: on platforms that use tagged pointers, +such as [CHERI](https://cheri-cpu.org/), pointers can be numerically +larger than the size of the address space. +If the numeric value of a pointer needs to be stored in an integer +without information loss, use the standard C types `intptr_t` or +`uintptr_t`, or the similar GLib types [`gintptr`](#gintptr) or +[`guintptr`](#guintptr). + +To print or scan values of this type, use +`G_GSIZE_MODIFIER` and/or `G_GSIZE_FORMAT`. + +Note that on platforms where more than one standard integer type is +the same size, `size_t` and `gsize` are always the same size but are +not necessarily implemented by the same standard integer type. +For example, on an ILP32 platform where `int`, `long` and pointers +are all 32-bit, `size_t` might be `unsigned long` while `gsize` +might be `unsigned int`. +This can result in compiler warnings or unexpected C++ name-mangling +if the two types are used inconsistently. + +As a result, changing a type from `gsize` to `size_t` in existing APIs +might be an incompatible API or ABI change, especially if C++ +is involved. The safe option is to leave existing APIs using the same type +that they have historically used, and only use the standard C types in +new APIs. + +Similar considerations apply to all the fixed-size types +([`gint8`](#gint8), [`guint8`](#guint8), [`gint16`](#gint16), +[`guint16`](#guint16), [`gint32`](#gint32), [`guint32`](#guint32), +[`gint64`](#gint64), [`guint64`](#guint64) and [`goffset`](#goffset)), as well +as [`gintptr`](#gintptr) and [`guintptr`](#guintptr). +Types that are 32 bits or larger are particularly likely to be +affected by this. + +`G_MAXSIZE` +: The maximum value which can be held in a `gsize`. + + This is the same as standard C `SIZE_MAX` (available since C99), + which should be preferred in new code. + + Since: 2.4 + +`G_GSIZE_MODIFIER` +: The platform dependent length modifier for conversion specifiers + for scanning and printing values of type `gsize`. It + is a string literal. + + Note that this is not necessarily the correct modifier to scan or + print a `size_t`, even though the in-memory representation is the + same. The Standard C `"z"` modifier should be used for `size_t`, + assuming a C99-compliant `printf` implementation is available. + + Since: 2.6 + +`G_GSIZE_FORMAT` +: This is the platform dependent conversion specifier for scanning + and printing values of type `gsize`. See also `G_GINT16_FORMAT`. + + Note that this is not necessarily the correct format to scan or + print a `size_t`, even though the in-memory representation is the + same. The standard C `"zu"` format should be used for `size_t`, + assuming a C99-compliant `printf` implementation is available. + + Since: 2.6 + +### `gssize` + +A signed variant of [`gsize`](#gsize), corresponding to the +`ssize_t` defined in POSIX or the similar `SSIZE_T` in Windows. + +In new platform-specific code, consider using `ssize_t` or `SSIZE_T` +directly. + +Values of this type can range from `G_MINSSIZE` to `G_MAXSSIZE`. + +Note that on platforms where `ssize_t` is implemented, `ssize_t` and +`gssize` might be implemented by different standard integer types +of the same size. Similarly, on Windows, `SSIZE_T` and `gssize` +might be implemented by different standard integer types of the same +size. See [`gsize`](#gsize) for more details. + +This type is also not guaranteed to be the same as standard C +`ptrdiff_t`, although they are the same on many platforms. + +To print or scan values of this type, use +`G_GSSIZE_MODIFIER` and/or `G_GSSIZE_FORMAT`. + +`G_MINSSIZE` +: The minimum value which can be held in a `gssize`. + + Since: 2.14 + +`G_MAXSSIZE` +: The maximum value which can be held in a `gssize`. + + Since: 2.14 + +`G_GSSIZE_FORMAT` +: This is the platform dependent conversion specifier for scanning + and printing values of type `gssize`. See also `G_GINT16_FORMAT`. + + Note that this is not necessarily the correct format to scan or print + a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory + representation is the same. + On POSIX platforms, the `"zd"` format should be used for `ssize_t`. + + Since: 2.6 + +`G_GSSIZE_MODIFIER` +: The platform dependent length modifier for conversion specifiers + for scanning and printing values of type `gssize`. It + is a string literal. + + Note that this is not necessarily the correct modifier to scan or print + a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory + representation is the same. + On POSIX platforms, the `"z"` modifier should be used for `ssize_t`. + + Since: 2.6 + +### `goffset` + +A signed integer type that is used for file offsets, +corresponding to the POSIX type `off_t` as if compiling with +`_FILE_OFFSET_BITS` set to 64. `goffset` is always 64 bits wide, even on +32-bit architectures, and even if `off_t` is only 32 bits. +Values of this type can range from `G_MINOFFSET` to +`G_MAXOFFSET`. + +To print or scan values of this type, use +`G_GOFFSET_MODIFIER` and/or `G_GOFFSET_FORMAT`. + +On platforms with more than one 64-bit standard integer type, +even if `off_t` is also 64 bits in size, `goffset` and `off_t` are not +necessarily implemented by the same 64-bit integer type. +See [`gsize`](#gsize) for more details of what this implies. + +Since: 2.14 + +`G_MINOFFSET` +: The minimum value which can be held in a `goffset`. + +`G_MAXOFFSET` +: The maximum value which can be held in a `goffset`. + +`G_GOFFSET_MODIFIER` +: The platform dependent length modifier for conversion specifiers + for scanning and printing values of type `goffset`. It is a string + literal. See also `G_GINT64_MODIFIER`. + + This modifier should only be used with `goffset` values, and not + with `off_t`, which is not necessarily the same type or even the same size. + + Since: 2.20 + +`G_GOFFSET_FORMAT` +: This is the platform dependent conversion specifier for scanning + and printing values of type `goffset`. See also `G_GINT64_FORMAT`. + + This format should only be used with `goffset` values, and not + with `off_t`, which is not necessarily the same type or even the same size. + + Since: 2.20 + +`G_GOFFSET_CONSTANT(val)` +: This macro is used to insert `goffset` 64-bit integer literals + into the source code. + + See also `G_GINT64_CONSTANT()`. + + Since: 2.20 + +### `gintptr` + +Corresponds to the C99 type `intptr_t`, +a signed integer type that can hold any pointer. + +The standard `intptr_t` type should be preferred in new code, unless +consistency with pre-existing APIs requires `gintptr`. +Note that `intptr_t` and `gintptr` might be implemented by different +standard integer types of the same size. See [`gsize`](#gsize) for more details. + +`gintptr` is not guaranteed to be the same type or the same size as +[`gssize`](#gssize), even though they are the same on many CPU architectures. + +To print or scan values of this type, use +`G_GINTPTR_MODIFIER` and/or `G_GINTPTR_FORMAT`. + +Since: 2.18 + +`G_GINTPTR_MODIFIER` +: The platform dependent length modifier for conversion specifiers + for scanning and printing values of type `gintptr` or `guintptr`. + It is a string literal. + + Note that this is not necessarily the correct modifier to scan or + print an `intptr_t`, even though the in-memory representation is the + same. + Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for + `intptr_t`. + + Since: 2.22 + +`G_GINTPTR_FORMAT` +: This is the platform dependent conversion specifier for scanning + and printing values of type `gintptr`. + + Note that this is not necessarily the correct format to scan or + print an `intptr_t`, even though the in-memory representation is the + same. + Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for + `intptr_t`. + + Since: 2.22 + +### `guintptr` + +Corresponds to the C99 type `uintptr_t`, +an unsigned integer type that can hold any pointer. + +The standard `uintptr_t` type should be preferred in new code, unless +consistency with pre-existing APIs requires `guintptr`. +Note that `uintptr_t` and `guintptr` might be implemented by different +standard integer types of the same size. See [`gsize`](#gsize) for more details. + +`guintptr` is not guaranteed to be the same type or the same size as +[`gsize`](#gsize), even though they are the same on many CPU architectures. + +To print or scan values of this type, use +`G_GINTPTR_MODIFIER` and/or `G_GUINTPTR_FORMAT`. + +Since: 2.18 + +`G_GUINTPTR_FORMAT` +: This is the platform dependent conversion specifier + for scanning and printing values of type `guintptr`. + + Note that this is not necessarily the correct format to scan or + print a `uintptr_t`, even though the in-memory representation is the + same. + Standard C macros like `PRIuPTR` and `SCNuPTR` should be used for + `uintptr_t`. + + Since: 2.22 diff --git a/glib/docs.c b/glib/docs.c index afe3bc5b6..b4457acf6 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -25,1042 +25,6 @@ * files. */ -/* Basic types {{{1 */ - -/** - * SECTION:types - * @title: Basic Types - * @short_description: standard GLib types, defined for ease-of-use - * and portability - * - * GLib defines a number of commonly used types, which can be divided - * into several groups: - * - New types which are not part of standard C (but are defined in - * various C standard library header files) — #gboolean, #gssize. - * - Integer types which are guaranteed to be the same size across - * all platforms — #gint8, #guint8, #gint16, #guint16, #gint32, - * #guint32, #gint64, #guint64. - * - Types which are easier to use than their standard C counterparts - - * #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong. - * - Types which correspond exactly to standard C types, but are - * included for completeness — #gchar, #gint, #gshort, #glong, - * #gfloat, #gdouble. - * - Types which correspond exactly to standard C99 types, but are available - * to use even if your compiler does not support C99 — #gsize, #goffset, - * #gintptr, #guintptr. - * - * GLib also defines macros for the limits of some of the standard - * integer and floating point types, as well as macros for suitable - * printf() formats for these types. - * - * Note that depending on the platform and build configuration, the format - * macros might not be compatible with the system provided printf() function, - * because GLib might use a different printf() implementation internally. - * The format macros will always work with GLib API (like g_print()), and with - * any C99 compatible printf() implementation. - */ - -/** - * gboolean: - * - * A standard boolean type. - * Variables of this type should only contain the value - * %TRUE or %FALSE. - * - * Never directly compare the contents of a #gboolean variable with the values - * %TRUE or %FALSE. Use `if (condition)` to check a #gboolean is "true", instead - * of `if (condition == TRUE)`. Likewise use `if (!condition)` to check a - * #gboolean is "false". - * - * There is no validation when assigning to a #gboolean variable and so it could - * contain any value represented by a #gint. This is why the use of `if - * (condition)` is recommended. All non-zero values in C evaluate to "true". - */ - -/** - * gpointer: - * - * An untyped pointer, exactly equivalent to `void *`. - * - * The standard C `void *` type should usually be preferred in - * new code, but `gpointer` can be used in contexts where a type name - * must be a single word, such as in the g_type_name() of %G_TYPE_POINTER - * or when generating a family of function names for multiple types - * using macros. - */ - -/** - * gconstpointer: - * - * An untyped pointer to constant data, exactly equivalent to `const void *`. - * - * The data pointed to should not be changed. - * - * This is typically used in function prototypes to indicate - * that the data pointed to will not be altered by the function. - * - * The standard C `const void *` type should usually be preferred in - * new code, but `gconstpointer` can be used in contexts where a type name - * must be a single word. - */ - -/** - * gchar: - * - * Equivalent to the standard C `char` type. - * - * This type only exists for symmetry with `guchar`. - * The standard C `char` type should be preferred in new code. - */ - -/** - * guchar: - * - * Equivalent to the standard C `unsigned char` type. - * - * The standard C `unsigned char` type should usually be preferred in - * new code, but `guchar` can be used in contexts where a type name - * must be a single word, such as in the g_type_name() of %G_TYPE_UCHAR - * or when generating a family of function names for multiple types - * using macros. - */ - -/** - * gint: - * - * Equivalent to the standard C `int` type. - * - * Values of this type can range from `INT_MIN` to `INT_MAX`, - * or equivalently from %G_MININT to %G_MAXINT. - * - * This type only exists for symmetry with `guint`. - * The standard C `int` type should be preferred in new code. - */ - -/** - * G_MININT: - * - * The minimum value which can be held in a #gint. - * - * This is the same as standard C `INT_MIN`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * G_MAXINT: - * - * The maximum value which can be held in a #gint. - * - * This is the same as standard C `INT_MAX`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * guint: - * - * Equivalent to the standard C `unsigned int` type. - * - * Values of this type can range from 0 to `UINT_MAX`, - * or equivalently 0 to %G_MAXUINT. - * - * The standard C `unsigned int` type should usually be preferred in - * new code, but `guint` can be used in contexts where a type name - * must be a single word, such as in the g_type_name() of %G_TYPE_UINT - * or when generating a family of function names for multiple types - * using macros. - */ - -/** - * G_MAXUINT: - * - * The maximum value which can be held in a #guint. - * - * This is the same as standard C `UINT_MAX`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * gshort: - * - * Equivalent to the standard C `short` type. - * - * Values of this type can range from `SHRT_MIN` to `SHRT_MAX`, - * or equivalently %G_MINSHORT to %G_MAXSHORT. - * - * This type only exists for symmetry with `gushort`. - * The standard C `short` type should be preferred in new code. - */ - -/** - * G_MINSHORT: - * - * The minimum value which can be held in a #gshort. - * - * This is the same as standard C `SHRT_MIN`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * G_MAXSHORT: - * - * The maximum value which can be held in a #gshort. - * - * This is the same as standard C `SHRT_MAX`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * gushort: - * - * Equivalent to the standard C `unsigned short` type. - * - * Values of this type can range from 0 to `USHRT_MAX`, - * or equivalently from 0 to %G_MAXUSHORT. - * - * The standard C `unsigned short` type should usually be preferred in - * new code, but `gushort` can be used in contexts where a type name - * must be a single word, such as when generating a family of function - * names for multiple types using macros. - */ - -/** - * G_MAXUSHORT: - * - * The maximum value which can be held in a #gushort. - * - * This is the same as standard C `USHRT_MAX`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * glong: - * - * Equivalent to the standard C `long` type. - * - * Values of this type can range from `LONG_MIN` to `LONG_MAX`, - * or equivalently %G_MINLONG to %G_MAXLONG. - * - * This type only exists for symmetry with `gulong`. - * The standard C `long` type should be preferred in new code. - */ - -/** - * G_MINLONG: - * - * The minimum value which can be held in a #glong. - * - * This is the same as standard C `LONG_MIN`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * G_MAXLONG: - * - * The maximum value which can be held in a #glong. - * - * This is the same as standard C `ULONG_MAX`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * gulong: - * - * Equivalent to the standard C `unsigned long` type. - * - * Values of this type can range from 0 to %G_MAXULONG. - * - * The standard C `unsigned long` type should usually be preferred in - * new code, but `gulong` can be used in contexts where a type name - * must be a single word, such as in the g_type_name() of %G_TYPE_ULONG - * or when generating a family of function names for multiple types - * using macros. - */ - -/** - * G_MAXULONG: - * - * The maximum value which can be held in a #gulong. - * - * This is the same as standard C `ULONG_MAX`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * gint8: - * - * A signed integer guaranteed to be 8 bits on all platforms, - * similar to the standard C `int8_t`. - * - * The `int8_t` type should be preferred in new code, unless - * consistency with pre-existing APIs requires use of `gint8` - * (see #gsize for more details). - * - * Values of this type can range from %G_MININT8 (= -128) to - * %G_MAXINT8 (= 127). - */ - -/** - * G_MAXINT8: - * - * The maximum value which can be held in a #gint8. - * - * This is the same as standard C `INT8_MAX`, which should be - * preferred in new code. - * - * Since: 2.4 - */ - -/** - * guint8: - * - * An unsigned integer guaranteed to be 8 bits on all platforms, - * similar to the standard C `uint8_t`. - * - * The `uint8_t` type should be preferred in new code, unless - * consistency with pre-existing APIs requires use of `guint8` - * (see #gsize for more details). - * - * Values of this type can range from 0 to %G_MAXUINT8 (= 255). - */ - -/** - * G_MAXUINT8: - * - * The maximum value which can be held in a #guint8. - * - * This is the same as standard C `UINT8_MAX`, which should be - * preferred in new code. - * - * Since: 2.4 - */ - -/** - * gint16: - * - * A signed integer guaranteed to be 16 bits on all platforms, - * similar to the standard C `int16_t`. - * - * The `int16_t` type should be preferred in new code, unless - * consistency with pre-existing APIs requires use of `gint16` - * (see #gsize for more details). - * - * Values of this type can range from %G_MININT16 (= -32,768) to - * %G_MAXINT16 (= 32,767). - * - * To print or scan values of this type, use - * %G_GINT16_MODIFIER and/or %G_GINT16_FORMAT. - */ - -/** - * G_MAXINT16: - * - * The maximum value which can be held in a #gint16. - * - * This is the same as standard C `INT16_MAX`, which should be - * preferred in new code. - * - * Since: 2.4 - */ - -/** - * G_GINT16_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gint16 or #guint16. It - * is a string literal, but doesn't include the percent-sign, such - * that you can add precision and length modifiers between percent-sign - * and conversion specifier and append a conversion specifier. - * - * The following example prints "0x7b"; - * |[ - * gint16 value = 123; - * g_print ("%#" G_GINT16_MODIFIER "x", value); - * ]| - * - * This is not necessarily the correct modifier for printing and scanning - * `int16_t` values, even though the in-memory representation is the same. - * Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`. - * - * Since: 2.4 - */ - -/** - * G_GINT16_FORMAT: - * - * This is the platform dependent conversion specifier for scanning and - * printing values of type #gint16. It is a string literal, but doesn't - * include the percent-sign, such that you can add precision and length - * modifiers between percent-sign and conversion specifier. - * - * |[ - * gint16 in; - * gint32 out; - * sscanf ("42", "%" G_GINT16_FORMAT, &in) - * out = in * 1000; - * g_print ("%" G_GINT32_FORMAT, out); - * - * This is not necessarily the correct format for printing and scanning - * `int16_t` values, even though the in-memory representation is the same. - * Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`. - * ]| - */ - -/** - * guint16: - * - * An unsigned integer guaranteed to be 16 bits on all platforms, - * similar to the standard C `uint16_t`. - * - * The `uint16_t` type should be preferred in new code, unless - * consistency with pre-existing APIs requires use of `guint16` - * (see #gsize for more details). - * - * Values of this type can range from 0 to %G_MAXUINT16 (= 65,535). - * - * To print or scan values of this type, use - * %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT. - */ - -/** - * G_MAXUINT16: - * - * The maximum value which can be held in a #guint16. - * - * This is the same as standard C `UINT16_MAX`, which should be - * preferred in new code. - * - * Since: 2.4 - */ - -/** - * G_GUINT16_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #guint16. See also %G_GINT16_FORMAT - * - * This is not necessarily the correct modifier for printing and scanning - * `uint16_t` values, even though the in-memory representation is the same. - * Standard C macros like `PRIu16` and `SCNu16` should be used for `uint16_t`. - */ - -/** - * gint32: - * - * A signed integer guaranteed to be 32 bits on all platforms. - * - * The `int32_t` type should be preferred in new code, unless - * consistency with pre-existing APIs requires use of `gint16` - * (see #gsize for more details). - * - * Values of this type can range from %G_MININT32 (= -2,147,483,648) - * to %G_MAXINT32 (= 2,147,483,647). - * - * To print or scan values of this type, use - * %G_GINT32_MODIFIER and/or %G_GINT32_FORMAT. - * - * Note that on platforms with more than one 32-bit standard integer type, - * `gint32` and `int32_t` are not necessarily implemented by the same - * 32-bit integer type. - * For example, on an ILP32 platform where `int` and `long` are both 32-bit, - * it might be the case that one of these types is `int` and the other - * is `long`. - * See #gsize for more details of what this implies. - */ - -/** - * G_MAXINT32: - * - * The maximum value which can be held in a #gint32. - * - * This is the same as standard C `INT32_MAX`, which should be - * preferred in new code. - * - * Since: 2.4 - */ - -/** - * G_GINT32_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gint32 or #guint32. It - * is a string literal. See also %G_GINT16_MODIFIER. - * - * This is not necessarily the correct modifier for printing and scanning - * `int32_t` values, even though the in-memory representation is the same. - * Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`. - * - * Since: 2.4 - */ - -/** - * G_GINT32_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #gint32. See also %G_GINT16_FORMAT. - * - * This is not necessarily the correct modifier for printing and scanning - * `int32_t` values, even though the in-memory representation is the same. - * Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`. - */ - -/** - * guint32: - * - * An unsigned integer guaranteed to be 32 bits on all platforms, - * similar to the standard C `uint32_t`. - * - * The `uint32_t` type should be preferred in new code, unless - * consistency with pre-existing APIs requires use of `guint32` - * (see #gsize for more details). - * - * Values of this type can range from 0 to %G_MAXUINT32 (= 4,294,967,295). - * - * To print or scan values of this type, use - * %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT. - * - * Note that on platforms with more than one 32-bit standard integer type, - * `guint32` and `uint32_t` are not necessarily implemented by the same - * 32-bit integer type. - * See #gsize for more details of what this implies. - */ - -/** - * G_MAXUINT32: - * - * The maximum value which can be held in a #guint32. - * - * This is the same as standard C `UINT32_MAX`, which should be - * preferred in new code. - * - * Since: 2.4 - */ - -/** - * G_GUINT32_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #guint32. See also %G_GINT16_FORMAT. - * - * This is not necessarily the correct modifier for printing and scanning - * `uint32_t` values, even though the in-memory representation is the same. - * Standard C macros like `PRIu32` and `SCNu32` should be used for `uint32_t`. - */ - -/** - * gint64: - * - * A signed integer guaranteed to be 64 bits on all platforms, - * similar to the standard C `int64_t`. - * - * The `int64_t` type should be preferred in new code, unless - * consistency with pre-existing APIs requires use of `gint64` - * (see #gsize for more details). - * - * Values of this type can range from %G_MININT64 - * (= -9,223,372,036,854,775,808) to %G_MAXINT64 - * (= 9,223,372,036,854,775,807). - * - * To print or scan values of this type, use - * %G_GINT64_MODIFIER and/or %G_GINT64_FORMAT. - * - * Note that on platforms with more than one 64-bit standard integer type, - * `gint64` and `int64_t` are not necessarily implemented by the same - * 64-bit integer type. - * For example, on a platform where both `long` and `long long` are 64-bit, - * it might be the case that one of those types is used for `gint64` - * and the other is used for `int64_t`. - * See #gsize for more details of what this implies. - */ - -/** - * G_MAXINT64: - * - * The maximum value which can be held in a #gint64. - */ - -/** - * G_GINT64_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gint64 or #guint64. - * It is a string literal. - * - * Some platforms do not support printing 64-bit integers, even - * though the types are supported. On such platforms %G_GINT64_MODIFIER - * is not defined. - * - * This is not necessarily the correct modifier for printing and scanning - * `int64_t` values, even though the in-memory representation is the same. - * Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`. - * - * Since: 2.4 - */ - -/** - * G_GINT64_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #gint64. See also %G_GINT16_FORMAT. - * - * Some platforms do not support scanning and printing 64-bit integers, - * even though the types are supported. On such platforms %G_GINT64_FORMAT - * is not defined. Note that scanf() may not support 64-bit integers, even - * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() - * is not recommended for parsing anyway; consider using g_ascii_strtoull() - * instead. - * - * This is not necessarily the correct format for printing and scanning - * `int64_t` values, even though the in-memory representation is the same. - * Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`. - */ - -/** - * guint64: - * - * An unsigned integer guaranteed to be 64-bits on all platforms, - * similar to the standard C `uint64_t` type. - * - * The `uint64_t` type should be preferred in new code, unless - * consistency with pre-existing APIs requires use of `guint64` - * (see #gsize for more details). - * - * Values of this type can range from 0 to %G_MAXUINT64 - * (= 18,446,744,073,709,551,615). - * - * To print or scan values of this type, use - * %G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT. - * - * Note that on platforms with more than one 64-bit standard integer type, - * `guint64` and `uint64_t` are not necessarily implemented by the same - * 64-bit integer type. - * See #gsize for more details of what this implies. - */ - -/** - * G_MAXUINT64: - * - * The maximum value which can be held in a #guint64. - * - * This is the same as standard C `UINT64_MAX`, which should be - * preferred in new code. - */ - -/** - * G_GUINT64_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #guint64. See also %G_GINT16_FORMAT. - * - * Some platforms do not support scanning and printing 64-bit integers, - * even though the types are supported. On such platforms %G_GUINT64_FORMAT - * is not defined. Note that scanf() may not support 64-bit integers, even - * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() - * is not recommended for parsing anyway; consider using g_ascii_strtoull() - * instead. - * - * This is not necessarily the correct modifier for printing and scanning - * `uint64_t` values, even though the in-memory representation is the same. - * Standard C macros like `PRIu64` and `SCNu64` should be used for `uint64_t`. - */ - -/** - * G_GINT64_CONSTANT: - * @val: a literal integer value, e.g. 0x1d636b02300a7aa7 - * - * This macro is used to insert 64-bit integer literals - * into the source code. - * - * It is similar to the standard C `INT64_C` macro, - * which should be preferred in new code. - */ - -/** - * G_GUINT64_CONSTANT: - * @val: a literal integer value, e.g. 0x1d636b02300a7aa7U - * - * This macro is used to insert 64-bit unsigned integer - * literals into the source code. - * - * It is similar to the standard C `UINT64_C` macro, - * which should be preferred in new code. - * - * Since: 2.10 - */ - -/** - * gfloat: - * - * Equivalent to the standard C `float` type. - * - * Values of this type can range from `-FLT_MAX` to `FLT_MAX`, - * or equivalently from -%G_MAXFLOAT to %G_MAXFLOAT. - */ - -/** - * G_MINFLOAT: - * - * The minimum positive value which can be held in a #gfloat. - * - * If you are interested in the smallest value which can be held - * in a #gfloat, use -%G_MAXFLOAT. - * - * This is the same as standard C `FLT_MIN`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * G_MAXFLOAT: - * - * The maximum value which can be held in a #gfloat. - * - * This is the same as standard C `FLT_MAX`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * gdouble: - * - * Equivalent to the standard C `double` type. - * - * Values of this type can range from `-DBL_MAX` to `DBL_MAX`, - * or equivalently from -%G_MAXDOUBLE to %G_MAXDOUBLE. - */ - -/** - * G_MINDOUBLE: - * - * The minimum positive value which can be held in a #gdouble. - * - * If you are interested in the smallest value which can be held - * in a #gdouble, use -%G_MAXDOUBLE. - * - * This is the same as standard C `DBL_MIN`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * G_MAXDOUBLE: - * - * The maximum value which can be held in a #gdouble. - * - * This is the same as standard C `DBL_MAX`, which is available since C99 - * and should be preferred in new code. - */ - -/** - * gsize: - * - * An unsigned integer type of the result of the `sizeof` operator, - * corresponding to the `size_t` type defined in C99. - * - * The standard `size_t` type should be preferred in new code, unless - * consistency with pre-existing APIs requires `gsize` - * (see below for more details). - * - * `gsize` is usually 32 bit wide on a 32-bit platform and 64 bit wide - * on a 64-bit platform. Values of this type can range from 0 to - * %G_MAXSIZE. - * - * This type is wide enough to hold the size of the largest possible - * memory allocation, but is not guaranteed to be wide enough to hold - * the numeric value of a pointer: on platforms that use tagged pointers, - * such as [CHERI](https://cheri-cpu.org/), pointers can be numerically - * larger than the size of the address space. - * If the numeric value of a pointer needs to be stored in an integer - * without information loss, use the standard C types `intptr_t` or - * `uintptr_t`, or the similar GLib types #gintptr or #guintptr. - * - * To print or scan values of this type, use - * %G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT. - * - * Note that on platforms where more than one standard integer type is - * the same size, `size_t` and `gsize` are always the same size but are - * not necessarily implemented by the same standard integer type. - * For example, on an ILP32 platform where `int`, `long` and pointers - * are all 32-bit, `size_t` might be `unsigned long` while `gsize` - * might be `unsigned int`. - * This can result in compiler warnings or unexpected C++ name-mangling - * if the two types are used inconsistently. - * - * As a result, changing a type from `gsize` to `size_t` in existing APIs - * might be an incompatible API or ABI change, especially if C++ - * is involved. The safe option is to leave existing APIs using the same type - * that they have historically used, and only use the standard C types in - * new APIs. - * - * Similar considerations apply to all the fixed-size types - * (#gint8, #guint8, #gint16, #guint16, #gint32, #guint32, #gint64, - * #guint64 and #goffset), as well as #gintptr and #guintptr. - * Types that are 32 bits or larger are particularly likely to be - * affected by this. - */ - -/** - * G_MAXSIZE: - * - * The maximum value which can be held in a #gsize. - * - * This is the same as standard C `SIZE_MAX` (available since C99), - * which should be preferred in new code. - * - * Since: 2.4 - */ - -/** - * G_GSIZE_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gsize. It - * is a string literal. - * - * Note that this is not necessarily the correct modifier to scan or - * print a `size_t`, even though the in-memory representation is the - * same. The Standard C `"z"` modifier should be used for `size_t`, - * assuming a C99-compliant `printf` implementation is available. - * - * Since: 2.6 - */ - -/** - * G_GSIZE_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #gsize. See also %G_GINT16_FORMAT. - * - * Note that this is not necessarily the correct format to scan or - * print a `size_t`, even though the in-memory representation is the - * same. The standard C `"zu"` format should be used for `size_t`, - * assuming a C99-compliant `printf` implementation is available. - * - * Since: 2.6 - */ - -/** - * gssize: - * - * A signed variant of #gsize, corresponding to the - * `ssize_t` defined in POSIX or the similar `SSIZE_T` in Windows. - * - * In new platform-specific code, consider using `ssize_t` or `SSIZE_T` - * directly. - * - * Values of this type can range from %G_MINSSIZE - * to %G_MAXSSIZE. - * - * Note that on platforms where `ssize_t` is implemented, `ssize_t` and - * `gssize` might be implemented by different standard integer types - * of the same size. Similarly, on Windows, `SSIZE_T` and `gssize` - * might be implemented by different standard integer types of the same - * size. See #gsize for more details. - * - * This type is also not guaranteed to be the same as standard C - * `ptrdiff_t`, although they are the same on many platforms. - * - * To print or scan values of this type, use - * %G_GSSIZE_MODIFIER and/or %G_GSSIZE_FORMAT. - */ - -/** - * G_MINSSIZE: - * - * The minimum value which can be held in a #gssize. - * - * Since: 2.14 - */ - -/** - * G_MAXSSIZE: - * - * The maximum value which can be held in a #gssize. - * - * Since: 2.14 - */ - -/** - * G_GSSIZE_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #gssize. See also %G_GINT16_FORMAT. - * - * Note that this is not necessarily the correct format to scan or print - * a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory - * representation is the same. - * On POSIX platforms, the `"zd"` format should be used for `ssize_t`. - * - * Since: 2.6 - */ - -/** - * G_GSSIZE_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gssize. It - * is a string literal. - * - * Note that this is not necessarily the correct modifier to scan or print - * a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory - * representation is the same. - * On POSIX platforms, the `"z"` modifier should be used for `ssize_t`. - * - * Since: 2.6 - */ - -/** - * goffset: - * - * A signed integer type that is used for file offsets, - * corresponding to the POSIX type `off_t` as if compiling with - * `_FILE_OFFSET_BITS` set to 64. #goffset is always 64 bits wide, even on - * 32-bit architectures, and even if `off_t` is only 32 bits. - * Values of this type can range from %G_MINOFFSET to - * %G_MAXOFFSET. - * - * To print or scan values of this type, use - * %G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT. - * - * On platforms with more than one 64-bit standard integer type, - * even if `off_t` is also 64 bits in size, `goffset` and `off_t` are not - * necessarily implemented by the same 64-bit integer type. - * See #gsize for more details of what this implies. - * - * Since: 2.14 - */ - -/** - * G_MINOFFSET: - * - * The minimum value which can be held in a #goffset. - */ - -/** - * G_MAXOFFSET: - * - * The maximum value which can be held in a #goffset. - */ - -/** - * G_GOFFSET_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #goffset. It is a string - * literal. See also %G_GINT64_MODIFIER. - * - * This modifier should only be used with #goffset values, and not - * with `off_t`, which is not necessarily the same type or even the same size. - * - * Since: 2.20 - */ - -/** - * G_GOFFSET_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #goffset. See also %G_GINT64_FORMAT. - * - * This format should only be used with #goffset values, and not - * with `off_t`, which is not necessarily the same type or even the same size. - * - * Since: 2.20 - */ - -/** - * G_GOFFSET_CONSTANT: - * @val: a literal integer value, e.g. 0x1d636b02300a7aa7 - * - * This macro is used to insert #goffset 64-bit integer literals - * into the source code. - * - * See also G_GINT64_CONSTANT(). - * - * Since: 2.20 - */ - -/** - * gintptr: - * - * Corresponds to the C99 type intptr_t, - * a signed integer type that can hold any pointer. - * - * The standard `intptr_t` type should be preferred in new code, unless - * consistency with pre-existing APIs requires `gintptr`. - * Note that `intptr_t` and `gintptr` might be implemented by different - * standard integer types of the same size. See #gsize for more details. - * - * #gintptr is not guaranteed to be the same type or the same size as #gssize, - * even though they are the same on many CPU architectures. - * - * To print or scan values of this type, use - * %G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT. - * - * Since: 2.18 - */ - -/** - * G_GINTPTR_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gintptr or #guintptr. - * It is a string literal. - * - * Note that this is not necessarily the correct modifier to scan or - * print an `intptr_t`, even though the in-memory representation is the - * same. - * Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for - * `intptr_t`. - * - * Since: 2.22 - */ - -/** - * G_GINTPTR_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #gintptr. - * - * Note that this is not necessarily the correct format to scan or - * print an `intptr_t`, even though the in-memory representation is the - * same. - * Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for - * `intptr_t`. - * - * Since: 2.22 - */ - -/** - * guintptr: - * - * Corresponds to the C99 type uintptr_t, - * an unsigned integer type that can hold any pointer. - * - * The standard `uintptr_t` type should be preferred in new code, unless - * consistency with pre-existing APIs requires `guintptr`. - * Note that `uintptr_t` and `guintptr` might be implemented by different - * standard integer types of the same size. See #gsize for more details. - * - * #guintptr is not guaranteed to be the same type or the same size as #gsize, - * even though they are the same on many CPU architectures. - * - * To print or scan values of this type, use - * %G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT. - * - * Since: 2.18 - */ - -/** - * G_GUINTPTR_FORMAT: - * - * This is the platform dependent conversion specifier - * for scanning and printing values of type #guintptr. - * - * Note that this is not necessarily the correct format to scan or - * print a `uintptr_t`, even though the in-memory representation is the - * same. - * Standard C macros like `PRIuPTR` and `SCNuPTR` should be used for - * `uintptr_t`. - * - * Since: 2.22 - */ - /* Type conversion {{{1 */ /**