docs: Soft-deprecate g(u)intptr in favour of (u)intptr_t

These have a status similar to size_t: they're Standard C types and
straightforward to use in portable code this decade, but we can't
guarantee that we have chosen the same underlying type that the platform
uses.

Helps: https://gitlab.gnome.org/GNOME/glib/-/issues/1484
Signed-off-by: Simon McVittie <smcv@collabora.com>
This commit is contained in:
Simon McVittie 2022-10-21 14:33:29 +01:00
parent 43d8545045
commit 589f29e005

View File

@ -834,6 +834,14 @@
* 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.
*
@ -847,6 +855,12 @@
* 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
*/
@ -856,6 +870,12 @@
* 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
*/
@ -865,6 +885,14 @@
* 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.
*
@ -877,6 +905,12 @@
* 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
*/