<!-- ##### 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>