luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-12 23:46:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Clarify the relationship between gssize, ssize_t and SSIZE_T

Browse Source 
This is similar to the relationship between gsize and size_t, except
that size_t is a Standard C type but ssize_t is platform-specific
(specifically, ssize_t is a POSIX type, and on Windows the equivalent
is SSIZE_T), making it more awkward to use in portable code. As a
result, continuing to use gssize is more useful than continuing to use
gsize.

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 15:19:47 +01:00
parent 9f19eb454b
commit de2602736d
1 changed files with 24 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
glib/docs.c
View File

@ -703,10 +703,23 @@
* gssize:
*
* A signed variant of #gsize, corresponding to the
* ssize_t defined on most platforms.
* `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.
*/
@ -733,6 +746,11 @@
* 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
*/
@ -743,6 +761,11 @@
* 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
*/