mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-02-24 03:02:10 +01:00
docs: Move byte conversion macro documentation to Markdown
Helps: #3037
This commit is contained in:
Matthias Clasen
Philip Withnall
parent
9725c012b1
commit
a73d3d7b8f
281
docs/reference/glib/conversion-macros.md
Normal file
281
docs/reference/glib/conversion-macros.md
Normal file
@ -0,0 +1,281 @@
|
||||
Title: Conversion Macros
|
||||
|
||||
# Conversion Macros
|
||||
|
||||
## Type Conversion
|
||||
|
||||
Many times GLib, GTK, and other libraries allow you to pass "user data" to a
|
||||
callback, in the form of a void pointer. From time to time you want to pass
|
||||
an integer instead of a pointer. You could allocate an integer, with
|
||||
something like:
|
||||
|
||||
```c
|
||||
int *ip = g_new (int, 1);
|
||||
*ip = 42;
|
||||
```
|
||||
|
||||
But this is inconvenient, and it's annoying to have to free the memory at
|
||||
some later time.
|
||||
|
||||
Pointers are always at least 32 bits in size (on all platforms GLib intends
|
||||
to support). Thus you can store at least 32-bit integer values in a pointer
|
||||
value. Naively, you might try this, but it's incorrect:
|
||||
|
||||
```c
|
||||
gpointer p;
|
||||
int i;
|
||||
p = (void*) 42;
|
||||
i = (int) p;
|
||||
```
|
||||
|
||||
Again, that example was not correct, don't copy it.
|
||||
|
||||
The problem is that on some systems you need to do this:
|
||||
|
||||
```c
|
||||
gpointer p;
|
||||
int i;
|
||||
p = (void*) (long) 42;
|
||||
i = (int) (long) p;
|
||||
```
|
||||
|
||||
The GLib macros `GPOINTER_TO_INT()`, `GINT_TO_POINTER()`, etc. take care to
|
||||
do the right thing on every platform.
|
||||
|
||||
**Warning**: You may not store pointers in integers. This is not portable in
|
||||
any way, shape or form. These macros only allow storing integers in
|
||||
pointers, and only preserve 32 bits of the integer; values outside the range
|
||||
of a 32-bit integer will be mangled.
|
||||
|
||||
|
||||
``GINT_TO_POINTER(value)``, ``GPOINTER_TO_INT(value)``
|
||||
: Stuffs an integer into a pointer type, and vice versa. Remember, you may not
|
||||
store pointers in integers. This is not portable in any way, shape or form.
|
||||
These macros only allow storing integers in pointers, and only preserve 32
|
||||
bits of the integer; values outside the range of a 32-bit integer will be
|
||||
mangled.
|
||||
|
||||
``GUINT_TO_POINTER(value)``, ``GPOINTER_TO_UINT(value)``
|
||||
: Stuffs an unsigned integer into a pointer type, and vice versa.
|
||||
|
||||
``GSIZE_TO_POINTER(value)``, ``GPOINTER_TO_SIZE(value)``
|
||||
: Stuffs a `size_t` into a pointer type, and vice versa.
|
||||
|
||||
## Byte Order Conversion
|
||||
|
||||
These macros provide a portable way to determine the host byte order and to
|
||||
convert values between different byte orders.
|
||||
|
||||
The byte order is the order in which bytes are stored to create larger data
|
||||
types such as the #gint and #glong values. The host byte order is the byte
|
||||
order used on the current machine.
|
||||
|
||||
Some processors store the most significant bytes (i.e. the bytes that hold
|
||||
the largest part of the value) first. These are known as big-endian
|
||||
processors. Other processors (notably the x86 family) store the most
|
||||
significant byte last. These are known as little-endian processors.
|
||||
|
||||
Finally, to complicate matters, some other processors store the bytes in a
|
||||
rather curious order known as PDP-endian. For a 4-byte word, the 3rd most
|
||||
significant byte is stored first, then the 4th, then the 1st and finally the
|
||||
2nd.
|
||||
|
||||
Obviously there is a problem when these different processors communicate
|
||||
with each other, for example over networks or by using binary file formats.
|
||||
This is where these macros come in. They are typically used to convert
|
||||
values into a byte order which has been agreed on for use when communicating
|
||||
between different processors. The Internet uses what is known as 'network
|
||||
byte order' as the standard byte order (which is in fact the big-endian byte
|
||||
order).
|
||||
|
||||
Note that the byte order conversion macros may evaluate their arguments
|
||||
multiple times, thus you should not use them with arguments which have
|
||||
side-effects.
|
||||
|
||||
`G_BYTE_ORDER`
|
||||
: The host byte order. This can be either `G_LITTLE_ENDIAN` or `G_BIG_ENDIAN`.
|
||||
|
||||
`G_LITTLE_ENDIAN`
|
||||
: Specifies the little endian byte order.
|
||||
|
||||
`G_BIG_ENDIAN`
|
||||
: Specifies the big endian byte order.
|
||||
|
||||
`G_PDP_ENDIAN`
|
||||
: Specifies the PDP endian byte order.
|
||||
|
||||
### Signed
|
||||
|
||||
`GINT_FROM_BE(value)`
|
||||
: Converts an `int` value from big-endian to host byte order.
|
||||
|
||||
`GINT_FROM_LE(value)`
|
||||
: Converts an `int` value from little-endian to host byte order.
|
||||
|
||||
`GINT_TO_BE(value)`
|
||||
: Converts an `int` value from host byte order to big-endian.
|
||||
|
||||
`GINT_TO_LE(value)`
|
||||
: Converts an `int` value from host byte order to little-endian.
|
||||
|
||||
`GLONG_FROM_BE(value)`
|
||||
: Converts a `long` value from big-endian to the host byte order.
|
||||
|
||||
`GLONG_FROM_LE(value)`
|
||||
: Converts a `long` value from little-endian to host byte order.
|
||||
|
||||
`GLONG_TO_BE(value)`
|
||||
: Converts a `long` value from host byte order to big-endian.
|
||||
|
||||
`GLONG_TO_LE(value)`
|
||||
: Converts a `long` value from host byte order to little-endian.
|
||||
|
||||
`GSSIZE_FROM_BE(value)`
|
||||
: Converts a `ssize_t` value from big-endian to host byte order.
|
||||
|
||||
`GSSIZE_FROM_LE(value)`
|
||||
: Converts a `ssize_t` value from little-endian to host byte order.
|
||||
|
||||
`GSSIZE_TO_BE(value)`
|
||||
: Converts a `ssize_t` value from host byte order to big-endian.
|
||||
|
||||
`GSSIZE_TO_LE(value)`
|
||||
: Converts a `ssize_t` value from host byte order to little-endian.
|
||||
|
||||
`GINT16_FROM_BE(value)`
|
||||
: Converts an `int16_t` value from big-endian to host byte order.
|
||||
|
||||
`GINT16_FROM_LE(value)`
|
||||
: Converts an `int16_t` value from little-endian to host byte order.
|
||||
|
||||
`GINT16_TO_BE(value)`
|
||||
: Converts an `int16_t` value from host byte order to big-endian.
|
||||
|
||||
`GINT16_TO_LE(value)`
|
||||
: Converts an `int16_t` value from host byte order to little-endian.
|
||||
|
||||
`GINT32_FROM_BE(value)`
|
||||
: Converts an `int32_t` value from big-endian to host byte order.
|
||||
|
||||
`GINT32_FROM_LE(value)`
|
||||
: Converts an `int32_t` value from little-endian to host byte order.
|
||||
|
||||
`GINT32_TO_BE(value)`
|
||||
: Converts an `int32_t` value from host byte order to big-endian.
|
||||
|
||||
`GINT32_TO_LE(value)`
|
||||
: Converts an `int32_t` value from host byte order to little-endian.
|
||||
|
||||
`GINT64_FROM_BE(value)`
|
||||
: Converts an `int64_t` value from big-endian to host byte order.
|
||||
|
||||
`GINT64_FROM_LE(value)`
|
||||
: Converts an `int64_t` value from little-endian to host byte order.
|
||||
|
||||
`GINT64_TO_BE(value)`
|
||||
: Converts an `int64_t` value from host byte order to big-endian.
|
||||
|
||||
`GINT64_TO_LE(value)`
|
||||
: Converts an `int64_t` value from host byte order to little-endian.
|
||||
|
||||
### Unsigned
|
||||
|
||||
`GUINT_FROM_BE(value)`
|
||||
: Converts an `unsigned int` value from big-endian to host byte order.
|
||||
|
||||
`GUINT_FROM_LE(value)`
|
||||
: Converts an `unsigned int` value from little-endian to host byte order.
|
||||
|
||||
`GUINT_TO_BE(value)`
|
||||
: Converts an `unsigned int` value from host byte order to big-endian.
|
||||
|
||||
`GUINT_TO_LE(value)`
|
||||
: Converts an `unsigned int` value from host byte order to little-endian.
|
||||
|
||||
`GULONG_FROM_BE(value)`
|
||||
: Converts an `unsigned long` value from big-endian to host byte order.
|
||||
|
||||
`GULONG_FROM_LE(value)`
|
||||
: Converts an `unsigned long` value from little-endian to host byte order.
|
||||
|
||||
`GULONG_TO_BE(value)`
|
||||
: Converts an `unsigned long` value from host byte order to big-endian.
|
||||
|
||||
`GULONG_TO_LE(value)`
|
||||
: Converts an `unsigned long` value from host byte order to little-endian.
|
||||
|
||||
`GSIZE_FROM_BE(value)`
|
||||
: Converts a `size_t` value from big-endian to the host byte order.
|
||||
|
||||
`GSIZE_FROM_LE(value)`
|
||||
: Converts a `size_t` value from little-endian to host byte order.
|
||||
|
||||
`GSIZE_TO_BE(value)`
|
||||
: Converts a `size_t` value from host byte order to big-endian.
|
||||
|
||||
`GSIZE_TO_LE(value)`
|
||||
: Converts a `size_t` value from host byte order to little-endian.
|
||||
|
||||
`GUINT16_FROM_BE(value)`
|
||||
: Converts an `uint16_t` value from big-endian to host byte order.
|
||||
|
||||
`GUINT16_FROM_LE(value)`
|
||||
: Converts an `uint16_t` value from little-endian to host byte order.
|
||||
|
||||
`GUINT16_TO_BE(value)`
|
||||
: Converts an `uint16_t` value from host byte order to big-endian.
|
||||
|
||||
`GUINT16_TO_LE(value)`
|
||||
: Converts an `uint16_t` value from host byte order to little-endian.
|
||||
|
||||
`GUINT32_FROM_BE(value)`
|
||||
: Converts an `uint32_t` value from big-endian to host byte order.
|
||||
|
||||
`GUINT32_FROM_LE(value)`
|
||||
: Converts an `uint32_t` value from little-endian to host byte order.
|
||||
|
||||
`GUINT32_TO_BE(value)`
|
||||
: Converts an `uint32_t` value from host byte order to big-endian.
|
||||
|
||||
`GUINT32_TO_LE(value)`
|
||||
: Converts an `uint32_t` value from host byte order to little-endian.
|
||||
|
||||
`GUINT64_FROM_BE(value)`
|
||||
: Converts an `uint64_t` value from big-endian to host byte order.
|
||||
|
||||
`GUINT64_FROM_LE(value)`
|
||||
: Converts an `uint64_t` value from little-endian to host byte order.
|
||||
|
||||
`GUINT64_TO_BE(value)`
|
||||
: Converts an `uint64_t` value from host byte order to big-endian.
|
||||
|
||||
`GUINT64_TO_LE(value)`
|
||||
: Converts an `uint64_t` value from host byte order to little-endian.
|
||||
|
||||
`GUINT16_SWAP_BE_PDP(value)`
|
||||
: Converts an `uint16_t` value between big-endian and pdp-endian byte order.
|
||||
The conversion is symmetric so it can be used both ways.
|
||||
|
||||
`GUINT16_SWAP_LE_BE(value)`
|
||||
: Converts an `uint16_t` value between little-endian and big-endian byte order.
|
||||
The conversion is symmetric so it can be used both ways.
|
||||
|
||||
`GUINT16_SWAP_LE_PDP(value)`
|
||||
: Converts an `uint16_t` value between little-endian and pdp-endian byte order.
|
||||
The conversion is symmetric so it can be used both ways.
|
||||
|
||||
`GUINT32_SWAP_BE_PDP(value)`
|
||||
: Converts an `uint32_t` value between big-endian and pdp-endian byte order.
|
||||
The conversion is symmetric so it can be used both ways.
|
||||
|
||||
`GUINT32_SWAP_LE_BE(value)`
|
||||
: Converts an `uint32_t` value between little-endian and big-endian byte order.
|
||||
The conversion is symmetric so it can be used both ways.
|
||||
|
||||
`GUINT32_SWAP_LE_PDP(value)`
|
||||
: Converts an `uint32_t` value between little-endian and pdp-endian byte order.
|
||||
The conversion is symmetric so it can be used both ways.
|
||||
|
||||
`GUINT64_SWAP_LE_BE(value)`
|
||||
: Converts a `uint64_t` value between little-endian and big-endian byte order.
|
||||
The conversion is symmetric so it can be used both ways.
|
||||
@ -41,6 +41,7 @@ urlmap_file = "urlmap.js"
|
||||
# The same order will be used when generating the index
|
||||
content_files = [
|
||||
"character-set.md",
|
||||
"conversion-macros.md",
|
||||
"reference-counting.md",
|
||||
"threads.md",
|
||||
]
|
||||
|
||||
77
glib/docs.c
77
glib/docs.c
@ -1063,48 +1063,6 @@
|
||||
|
||||
/* Type conversion {{{1 */
|
||||
|
||||
/**
|
||||
* SECTION:type_conversion
|
||||
* @title: Type Conversion Macros
|
||||
* @short_description: portably storing integers in pointer variables
|
||||
*
|
||||
* Many times GLib, GTK, and other libraries allow you to pass "user
|
||||
* data" to a callback, in the form of a void pointer. From time to time
|
||||
* you want to pass an integer instead of a pointer. You could allocate
|
||||
* an integer, with something like:
|
||||
* |[<!-- language="C" -->
|
||||
* int *ip = g_new (int, 1);
|
||||
* *ip = 42;
|
||||
* ]|
|
||||
* But this is inconvenient, and it's annoying to have to free the
|
||||
* memory at some later time.
|
||||
*
|
||||
* Pointers are always at least 32 bits in size (on all platforms GLib
|
||||
* intends to support). Thus you can store at least 32-bit integer values
|
||||
* in a pointer value. Naively, you might try this, but it's incorrect:
|
||||
* |[<!-- language="C" -->
|
||||
* gpointer p;
|
||||
* int i;
|
||||
* p = (void*) 42;
|
||||
* i = (int) p;
|
||||
* ]|
|
||||
* Again, that example was not correct, don't copy it.
|
||||
* The problem is that on some systems you need to do this:
|
||||
* |[<!-- language="C" -->
|
||||
* gpointer p;
|
||||
* int i;
|
||||
* p = (void*) (long) 42;
|
||||
* i = (int) (long) p;
|
||||
* ]|
|
||||
* The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
|
||||
* to do the right thing on every platform.
|
||||
*
|
||||
* Warning: You may not store pointers in integers. This is not
|
||||
* portable in any way, shape or form. These macros only allow storing
|
||||
* integers in pointers, and only preserve 32 bits of the integer; values
|
||||
* outside the range of a 32-bit integer will be mangled.
|
||||
*/
|
||||
|
||||
/**
|
||||
* GINT_TO_POINTER:
|
||||
* @i: integer to stuff into a pointer
|
||||
@ -1162,41 +1120,6 @@
|
||||
|
||||
/* Byte order {{{1 */
|
||||
|
||||
/**
|
||||
* SECTION:byte_order
|
||||
* @title: Byte Order Macros
|
||||
* @short_description: a portable way to convert between different byte orders
|
||||
*
|
||||
* These macros provide a portable way to determine the host byte order
|
||||
* and to convert values between different byte orders.
|
||||
*
|
||||
* The byte order is the order in which bytes are stored to create larger
|
||||
* data types such as the #gint and #glong values.
|
||||
* The host byte order is the byte order used on the current machine.
|
||||
*
|
||||
* Some processors store the most significant bytes (i.e. the bytes that
|
||||
* hold the largest part of the value) first. These are known as big-endian
|
||||
* processors. Other processors (notably the x86 family) store the most
|
||||
* significant byte last. These are known as little-endian processors.
|
||||
*
|
||||
* Finally, to complicate matters, some other processors store the bytes in
|
||||
* a rather curious order known as PDP-endian. For a 4-byte word, the 3rd
|
||||
* most significant byte is stored first, then the 4th, then the 1st and
|
||||
* finally the 2nd.
|
||||
*
|
||||
* Obviously there is a problem when these different processors communicate
|
||||
* with each other, for example over networks or by using binary file formats.
|
||||
* This is where these macros come in. They are typically used to convert
|
||||
* values into a byte order which has been agreed on for use when
|
||||
* communicating between different processors. The Internet uses what is
|
||||
* known as 'network byte order' as the standard byte order (which is in
|
||||
* fact the big-endian byte order).
|
||||
*
|
||||
* Note that the byte order conversion macros may evaluate their arguments
|
||||
* multiple times, thus you should not use them with arguments which have
|
||||
* side-effects.
|
||||
*/
|
||||
|
||||
/**
|
||||
* G_BYTE_ORDER:
|
||||
*
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user