<refentry id="glib-Standard-Macros">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Standard-Macros.top_of_page">Standard Macros</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Standard Macros</refname>
<refpurpose>commonly-used macros.</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Standard-Macros.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

#define             <link linkend="G-OS-WIN32--CAPS">G_OS_WIN32</link>
#define             <link linkend="G-OS-BEOS--CAPS">G_OS_BEOS</link>
#define             <link linkend="G-OS-UNIX--CAPS">G_OS_UNIX</link>

#define             <link linkend="G-DIR-SEPARATOR--CAPS">G_DIR_SEPARATOR</link>
#define             <link linkend="G-DIR-SEPARATOR-S--CAPS">G_DIR_SEPARATOR_S</link>
#define             <link linkend="G-IS-DIR-SEPARATOR--CAPS">G_IS_DIR_SEPARATOR</link>                  (c)
#define             <link linkend="G-SEARCHPATH-SEPARATOR--CAPS">G_SEARCHPATH_SEPARATOR</link>
#define             <link linkend="G-SEARCHPATH-SEPARATOR-S--CAPS">G_SEARCHPATH_SEPARATOR_S</link>

#define             <link linkend="TRUE--CAPS">TRUE</link>
#define             <link linkend="FALSE--CAPS">FALSE</link>

#define             <link linkend="NULL--CAPS">NULL</link>

#define             <link linkend="MIN--CAPS">MIN</link>                                 (a, b)
#define             <link linkend="MAX--CAPS">MAX</link>                                 (a, b)

#define             <link linkend="ABS--CAPS">ABS</link>                                 (a)
#define             <link linkend="CLAMP--CAPS">CLAMP</link>                               (x, low, high)

#define             <link linkend="G-STRUCT-MEMBER--CAPS">G_STRUCT_MEMBER</link>                     (member_type, struct_p, struct_offset)
#define             <link linkend="G-STRUCT-MEMBER-P--CAPS">G_STRUCT_MEMBER_P</link>                   (struct_p, struct_offset)
#define             <link linkend="G-STRUCT-OFFSET--CAPS">G_STRUCT_OFFSET</link>                     (struct_type, member)

#define             <link linkend="G-MEM-ALIGN--CAPS">G_MEM_ALIGN</link>

#define             <link linkend="G-CONST-RETURN--CAPS">G_CONST_RETURN</link>
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Standard-Macros.description" role="desc">
<title role="desc.title">Description</title>
<para>
These macros provide a few commonly-used features.
</para>
</refsect1>

<refsect1 id="glib-Standard-Macros.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="G-OS-WIN32--CAPS" role="macro">
<title>G_OS_WIN32</title>
<indexterm zone="G-OS-WIN32--CAPS"><primary sortas="OS_WIN32">G_OS_WIN32</primary></indexterm><programlisting>#define G_OS_WIN32
</programlisting>
<para>
This macro is defined only on Windows. So you can bracket
Windows-specific code in "&num;ifdef G_OS_WIN32".
</para></refsect2>
<refsect2 id="G-OS-BEOS--CAPS" role="macro">
<title>G_OS_BEOS</title>
<indexterm zone="G-OS-BEOS--CAPS"><primary sortas="OS_BEOS">G_OS_BEOS</primary></indexterm><programlisting>#define G_OS_BEOS
</programlisting>
<para>
This macro is defined only on BeOS. So you can bracket
BeOS-specific code in "&num;ifdef G_OS_BEOS".
</para></refsect2>
<refsect2 id="G-OS-UNIX--CAPS" role="macro">
<title>G_OS_UNIX</title>
<indexterm zone="G-OS-UNIX--CAPS"><primary sortas="OS_UNIX">G_OS_UNIX</primary></indexterm><programlisting>#define G_OS_UNIX
</programlisting>
<para>
This macro is defined only on UNIX. So you can bracket
UNIX-specific code in "&num;ifdef G_OS_UNIX".
</para></refsect2>
<refsect2 id="G-DIR-SEPARATOR--CAPS" role="macro">
<title>G_DIR_SEPARATOR</title>
<indexterm zone="G-DIR-SEPARATOR--CAPS"><primary sortas="DIR_SEPARATOR">G_DIR_SEPARATOR</primary></indexterm><programlisting>#define             G_DIR_SEPARATOR</programlisting>
<para>
The directory separator character.
This is '/' on UNIX machines and '\' under Windows.
</para></refsect2>
<refsect2 id="G-DIR-SEPARATOR-S--CAPS" role="macro">
<title>G_DIR_SEPARATOR_S</title>
<indexterm zone="G-DIR-SEPARATOR-S--CAPS"><primary sortas="DIR_SEPARATOR_S">G_DIR_SEPARATOR_S</primary></indexterm><programlisting>#define             G_DIR_SEPARATOR_S</programlisting>
<para>
The directory separator as a string.
This is "/" on UNIX machines and "\" under Windows.
</para></refsect2>
<refsect2 id="G-IS-DIR-SEPARATOR--CAPS" role="macro" condition="since:2.6">
<title>G_IS_DIR_SEPARATOR()</title>
<indexterm zone="G-IS-DIR-SEPARATOR--CAPS" role="2.6"><primary sortas="IS_DIR_SEPARATOR">G_IS_DIR_SEPARATOR</primary></indexterm><programlisting>#define             G_IS_DIR_SEPARATOR(c)</programlisting>
<para>
Checks whether a character is a directory
separator. It returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for '/' on UNIX
machines and for '\' or '/' under Windows.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter>&#160;:</term>
<listitem><simpara>a character
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.6</para></refsect2>
<refsect2 id="G-SEARCHPATH-SEPARATOR--CAPS" role="macro">
<title>G_SEARCHPATH_SEPARATOR</title>
<indexterm zone="G-SEARCHPATH-SEPARATOR--CAPS"><primary sortas="SEARCHPATH_SEPARATOR">G_SEARCHPATH_SEPARATOR</primary></indexterm><programlisting>#define             G_SEARCHPATH_SEPARATOR</programlisting>
<para>
The search path separator character.
This is ':' on UNIX machines and ';' under Windows.
</para></refsect2>
<refsect2 id="G-SEARCHPATH-SEPARATOR-S--CAPS" role="macro">
<title>G_SEARCHPATH_SEPARATOR_S</title>
<indexterm zone="G-SEARCHPATH-SEPARATOR-S--CAPS"><primary sortas="SEARCHPATH_SEPARATOR_S">G_SEARCHPATH_SEPARATOR_S</primary></indexterm><programlisting>#define             G_SEARCHPATH_SEPARATOR_S</programlisting>
<para>
The search path separator as a string.
This is ":" on UNIX machines and ";" under Windows.
</para></refsect2>
<refsect2 id="TRUE--CAPS" role="macro">
<title>TRUE</title>
<indexterm zone="TRUE--CAPS"><primary>TRUE</primary></indexterm><programlisting>#define	TRUE	(!FALSE)
</programlisting>
<para>
Defines the <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> value for the <link linkend="gboolean"><type>gboolean</type></link> type.
</para></refsect2>
<refsect2 id="FALSE--CAPS" role="macro">
<title>FALSE</title>
<indexterm zone="FALSE--CAPS"><primary>FALSE</primary></indexterm><programlisting>#define	FALSE	(0)
</programlisting>
<para>
Defines the <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> value for the <link linkend="gboolean"><type>gboolean</type></link> type.
</para></refsect2>
<refsect2 id="NULL--CAPS" role="macro">
<title>NULL</title>
<indexterm zone="NULL--CAPS"><primary>NULL</primary></indexterm><programlisting>#define             NULL</programlisting>
<para>
Defines the standard <link linkend="NULL--CAPS"><literal>NULL</literal></link> pointer.
</para></refsect2>
<refsect2 id="MIN--CAPS" role="macro">
<title>MIN()</title>
<indexterm zone="MIN--CAPS"><primary>MIN</primary></indexterm><programlisting>#define MIN(a, b)  (((a) &lt; (b)) ? (a) : (b))
</programlisting>
<para>
Calculates the minimum of <parameter>a</parameter> and <parameter>b</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>a</parameter>&#160;:</term>
<listitem><simpara>a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>b</parameter>&#160;:</term>
<listitem><simpara>a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the minimum of <parameter>a</parameter> and <parameter>b</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="MAX--CAPS" role="macro">
<title>MAX()</title>
<indexterm zone="MAX--CAPS"><primary>MAX</primary></indexterm><programlisting>#define MAX(a, b)  (((a) &gt; (b)) ? (a) : (b))
</programlisting>
<para>
Calculates the maximum of <parameter>a</parameter> and <parameter>b</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>a</parameter>&#160;:</term>
<listitem><simpara>a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>b</parameter>&#160;:</term>
<listitem><simpara>a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the maximum of <parameter>a</parameter> and <parameter>b</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="ABS--CAPS" role="macro">
<title>ABS()</title>
<indexterm zone="ABS--CAPS"><primary>ABS</primary></indexterm><programlisting>#define ABS(a)	   (((a) &lt; 0) ? -(a) : (a))
</programlisting>
<para>
Calculates the absolute value of <parameter>a</parameter>.
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><variablelist role="params">
<varlistentry><term><parameter>a</parameter>&#160;:</term>
<listitem><simpara>a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the absolute value of <parameter>a</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="CLAMP--CAPS" role="macro">
<title>CLAMP()</title>
<indexterm zone="CLAMP--CAPS"><primary>CLAMP</primary></indexterm><programlisting>#define CLAMP(x, low, high)  (((x) &gt; (high)) ? (high) : (((x) &lt; (low)) ? (low) : (x)))
</programlisting>
<para>
Ensures that <parameter>x</parameter> is between the limits set by <parameter>low</parameter> and <parameter>high</parameter>. If <parameter>low</parameter> is
greater than <parameter>high</parameter> the result is undefined.
</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><variablelist role="params">
<varlistentry><term><parameter>x</parameter>&#160;:</term>
<listitem><simpara>the value to clamp.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>low</parameter>&#160;:</term>
<listitem><simpara>the minimum value allowed.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>high</parameter>&#160;:</term>
<listitem><simpara>the maximum value allowed.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the value of <parameter>x</parameter> clamped to the range between <parameter>low</parameter> and <parameter>high</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="G-STRUCT-MEMBER--CAPS" role="macro">
<title>G_STRUCT_MEMBER()</title>
<indexterm zone="G-STRUCT-MEMBER--CAPS"><primary sortas="STRUCT_MEMBER">G_STRUCT_MEMBER</primary></indexterm><programlisting>#define             G_STRUCT_MEMBER(member_type, struct_p, struct_offset)</programlisting>
<para>
Returns a member of a structure at a given offset, using the given type.
</para><variablelist role="params">
<varlistentry><term><parameter>member_type</parameter>&#160;:</term>
<listitem><simpara>the type of the struct field.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>struct_p</parameter>&#160;:</term>
<listitem><simpara>a pointer to a struct.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>struct_offset</parameter>&#160;:</term>
<listitem><simpara>the offset of the field from the start of the struct, in bytes.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the struct member.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="G-STRUCT-MEMBER-P--CAPS" role="macro">
<title>G_STRUCT_MEMBER_P()</title>
<indexterm zone="G-STRUCT-MEMBER-P--CAPS"><primary sortas="STRUCT_MEMBER_P">G_STRUCT_MEMBER_P</primary></indexterm><programlisting>#define             G_STRUCT_MEMBER_P(struct_p, struct_offset)</programlisting>
<para>
Returns an untyped pointer to a given offset of a struct.
</para><variablelist role="params">
<varlistentry><term><parameter>struct_p</parameter>&#160;:</term>
<listitem><simpara>a pointer to a struct.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>struct_offset</parameter>&#160;:</term>
<listitem><simpara>the offset from the start of the struct, in bytes.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>an untyped pointer to <parameter>struct_p</parameter> plus <parameter>struct_offset</parameter> bytes.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="G-STRUCT-OFFSET--CAPS" role="macro">
<title>G_STRUCT_OFFSET()</title>
<indexterm zone="G-STRUCT-OFFSET--CAPS"><primary sortas="STRUCT_OFFSET">G_STRUCT_OFFSET</primary></indexterm><programlisting>#define             G_STRUCT_OFFSET(struct_type, member)</programlisting>
<para>
Returns the offset, in bytes, of a member of a struct.
</para><variablelist role="params">
<varlistentry><term><parameter>struct_type</parameter>&#160;:</term>
<listitem><simpara>a structure type, e.g. <structname>GtkWidget</structname>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>member</parameter>&#160;:</term>
<listitem><simpara>a field in the structure, e.g. <structfield>window</structfield>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the offset of <parameter>member</parameter> from the start of <parameter>struct_type</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="G-MEM-ALIGN--CAPS" role="macro">
<title>G_MEM_ALIGN</title>
<indexterm zone="G-MEM-ALIGN--CAPS"><primary sortas="MEM_ALIGN">G_MEM_ALIGN</primary></indexterm><programlisting>#define             G_MEM_ALIGN</programlisting>
<para>
Indicates the number of bytes to which memory will be aligned on the
current platform.
</para></refsect2>
<refsect2 id="G-CONST-RETURN--CAPS" role="macro">
<title>G_CONST_RETURN</title>
<indexterm zone="G-CONST-RETURN--CAPS"><primary sortas="CONST_RETURN">G_CONST_RETURN</primary></indexterm><programlisting>#define             G_CONST_RETURN</programlisting>
<para>
If <link linkend="G-DISABLE-CONST-RETURNS--CAPS"><literal>G_DISABLE_CONST_RETURNS</literal></link> 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></refsect2>

</refsect1>




</refentry>
