mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-03-27 10:00:06 +01:00
255 lines
5.3 KiB
Plaintext
255 lines
5.3 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Standard Macros
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
commonly-used macros.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
These macros provide a few commonly-used features.
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### MACRO GLIB_MAJOR_VERSION ##### -->
|
|
<para>
|
|
The major version number of the GLib library.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO GLIB_MINOR_VERSION ##### -->
|
|
<para>
|
|
The minor version number of the GLib library.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO GLIB_MICRO_VERSION ##### -->
|
|
<para>
|
|
The micro version number of the GLib library.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_OS_WIN32 ##### -->
|
|
<para>
|
|
This macro is defined only on Windows. So you can bracket
|
|
Windows-specific code in "#ifdef G_OS_WIN32".
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_OS_BEOS ##### -->
|
|
<para>
|
|
This macro is defined only on BeOS. So you can bracket
|
|
BeOS-specific code in "#ifdef G_OS_BEOS".
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_OS_UNIX ##### -->
|
|
<para>
|
|
This macro is defined only on UNIX. So you can bracket
|
|
UNIX-specific code in "#ifdef G_OS_UNIX".
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO GLIB_CHECK_VERSION ##### -->
|
|
<para>
|
|
Checks the version of the GLib library.
|
|
It returns %TRUE if the GLib library is the same or newer than the given
|
|
version.
|
|
|
|
<example>
|
|
<title>Checking the version of the GLib library.</title>
|
|
<programlisting>
|
|
if (!GLIB_CHECK_VERSION (1, 2, 0))
|
|
g_error ("GLib version 1.2.0 or above is needed");
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
@major: the major version number.
|
|
@minor: the minor version number.
|
|
@micro: the micro version number.
|
|
|
|
|
|
<!-- ##### MACRO G_DIR_SEPARATOR ##### -->
|
|
<para>
|
|
The directory separator character.
|
|
This is '/' on UNIX machines and '\' under Windows.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_DIR_SEPARATOR_S ##### -->
|
|
<para>
|
|
The directory separator as a string.
|
|
This is "/" on UNIX machines and "\" under Windows.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_SEARCHPATH_SEPARATOR ##### -->
|
|
<para>
|
|
The search path separator character.
|
|
This is ':' on UNIX machines and ';' under Windows.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_SEARCHPATH_SEPARATOR_S ##### -->
|
|
<para>
|
|
The search path separator as a string.
|
|
This is ":" on UNIX machines and ";" under Windows.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO TRUE ##### -->
|
|
<para>
|
|
Defines the %TRUE value for the #gboolean type.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO FALSE ##### -->
|
|
<para>
|
|
Defines the %FALSE value for the #gboolean type.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO NULL ##### -->
|
|
<para>
|
|
Defines the standard %NULL pointer.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO MIN ##### -->
|
|
<para>
|
|
Calculates the minimum of @a and @b.
|
|
</para>
|
|
|
|
@a: a numeric value.
|
|
@b: a numeric value.
|
|
@Returns: the minimum of @a and @b.
|
|
|
|
|
|
<!-- ##### MACRO MAX ##### -->
|
|
<para>
|
|
Calculates the maximum of @a and @b.
|
|
</para>
|
|
|
|
@a: a numeric value.
|
|
@b: a numeric value.
|
|
@Returns: the maximum of @a and @b.
|
|
|
|
|
|
<!-- ##### MACRO ABS ##### -->
|
|
<para>
|
|
Calculates the absolute value of @a.
|
|
The absolute value is simply the number with any negative sign taken away.
|
|
</para>
|
|
<para>
|
|
For example,
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
ABS(-10) is 10.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
ABS(10) is also 10.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
@a: a numeric value.
|
|
@Returns: the absolute value of @a.
|
|
|
|
|
|
<!-- ##### MACRO CLAMP ##### -->
|
|
<para>
|
|
Ensures that @x is between the limits set by @low and @high.
|
|
</para>
|
|
<para>
|
|
For example,
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
CLAMP(5, 10, 15) is 10.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
CLAMP(15, 5, 10) is 10.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
CLAMP(20, 15, 25) is 20.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
@x: the value to clamp.
|
|
@low: the minimum value allowed.
|
|
@high: the maximum value allowed.
|
|
@Returns: the value of @x clamped to the range between @low and @high.
|
|
|
|
|
|
<!-- ##### MACRO G_STRUCT_MEMBER ##### -->
|
|
<para>
|
|
Returns a member of a structure at a given offset, using the given type.
|
|
</para>
|
|
|
|
@member_type: the type of the struct field.
|
|
@struct_p: a pointer to a struct.
|
|
@struct_offset: the offset of the field from the start of the struct, in bytes.
|
|
@Returns: the struct member.
|
|
|
|
|
|
<!-- ##### MACRO G_STRUCT_MEMBER_P ##### -->
|
|
<para>
|
|
Returns an untyped pointer to a given offset of a struct.
|
|
</para>
|
|
|
|
@struct_p: a pointer to a struct.
|
|
@struct_offset: the offset from the start of the struct, in bytes.
|
|
@Returns: an untyped pointer to @struct_p plus @struct_offset bytes.
|
|
|
|
|
|
<!-- ##### MACRO G_STRUCT_OFFSET ##### -->
|
|
<para>
|
|
Returns the offset, in bytes, of a member of a struct.
|
|
</para>
|
|
|
|
@struct_type: a structure type, e.g. <structname>GtkWidget</structname>.
|
|
@member: a field in the structure, e.g. <structfield>window</structfield>.
|
|
@Returns: the offset of @member from the start of @struct_type.
|
|
|
|
|
|
<!-- ##### MACRO G_MEM_ALIGN ##### -->
|
|
<para>
|
|
Indicates the number of bytes to which memory will be aligned on the
|
|
current platform.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_CONST_RETURN ##### -->
|
|
<para>
|
|
If %G_DISABLE_CONST_RETURNS is defined, this macro expands to nothing.
|
|
By default, the macro expands to <literal>const</literal>. The macro
|
|
should be used in place of <literal>const</literal> for functions that
|
|
return a value that should not be modified. The purpose of this macro is
|
|
to allow us to turn on <literal>const</literal> for returned constant
|
|
strings by default, while allowing programmers who find that annoying to
|
|
turn it off. This macro should only be used for return values and for
|
|
<emphasis>out</emphasis> parameters, it doesn't make sense for
|
|
<emphasis>in</emphasis> parameters.
|
|
</para>
|
|
|
|
|
|
|