macros_misc.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="glib-Miscellaneous-Macros">
<refmeta>
<refentrytitle>Miscellaneous Macros</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Miscellaneous Macros</refname><refpurpose>specialized macros which are not used often.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


#define     <link linkend="G-INLINE-FUNC-CAPS">G_INLINE_FUNC</link>

#define     <link linkend="G-STMT-START-CAPS">G_STMT_START</link>
#define     <link linkend="G-STMT-END-CAPS">G_STMT_END</link>

#define     <link linkend="G-BEGIN-DECLS-CAPS">G_BEGIN_DECLS</link>
#define     <link linkend="G-END-DECLS-CAPS">G_END_DECLS</link>

#define     <link linkend="G-N-ELEMENTS-CAPS">G_N_ELEMENTS</link>                    (arr)

#define     <link linkend="G-VA-COPY-CAPS">G_VA_COPY</link>

#define     <link linkend="G-STRINGIFY-CAPS">G_STRINGIFY</link>                     (macro_or_string)

#define     <link linkend="G-GNUC-EXTENSION-CAPS">G_GNUC_EXTENSION</link>
#define     <link linkend="G-GNUC-CONST-CAPS">G_GNUC_CONST</link>
#define     <link linkend="G-GNUC-NORETURN-CAPS">G_GNUC_NORETURN</link>
#define     <link linkend="G-GNUC-UNUSED-CAPS">G_GNUC_UNUSED</link>
#define     <link linkend="G-GNUC-PURE-CAPS">G_GNUC_PURE</link>
#define     <link linkend="G-GNUC-PRINTF-CAPS">G_GNUC_PRINTF</link>                   ( format_idx, arg_idx )
#define     <link linkend="G-GNUC-SCANF-CAPS">G_GNUC_SCANF</link>                    ( format_idx, arg_idx )
#define     <link linkend="G-GNUC-FORMAT-CAPS">G_GNUC_FORMAT</link>                   ( arg_idx )
#define     <link linkend="G-GNUC-FUNCTION-CAPS">G_GNUC_FUNCTION</link>
#define     <link linkend="G-GNUC-PRETTY-FUNCTION-CAPS">G_GNUC_PRETTY_FUNCTION</link>
#define     <link linkend="G-GNUC-NO-INSTRUMENT-CAPS">G_GNUC_NO_INSTRUMENT</link>

#define     <link linkend="G-STRLOC-CAPS">G_STRLOC</link>

#define     <link linkend="G-GINT16-FORMAT-CAPS">G_GINT16_FORMAT</link>
#define     <link linkend="G-GUINT16-FORMAT-CAPS">G_GUINT16_FORMAT</link>
#define     <link linkend="G-GINT32-FORMAT-CAPS">G_GINT32_FORMAT</link>
#define     <link linkend="G-GUINT32-FORMAT-CAPS">G_GUINT32_FORMAT</link>
#define     <link linkend="G-GINT64-FORMAT-CAPS">G_GINT64_FORMAT</link>
#define     <link linkend="G-GUINT64-FORMAT-CAPS">G_GUINT64_FORMAT</link>

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
These macros provide more specialized features which are not needed so often
by application programmers.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="G-INLINE-FUNC-CAPS">G_INLINE_FUNC</title>
<programlisting>#define     G_INLINE_FUNC</programlisting>
<para>
Used to declare inline functions. If inline functions are not supported on
the particular platform, the macro evaluates to the empty string.
</para></refsect2>
<refsect2>
<title><anchor id="G-STMT-START-CAPS">G_STMT_START</title>
<programlisting>#define     G_STMT_START</programlisting>
<para>
Used within multi-statement macros so that they can be used in places where
only one statement is expected by the compiler.
</para></refsect2>
<refsect2>
<title><anchor id="G-STMT-END-CAPS">G_STMT_END</title>
<programlisting>#define     G_STMT_END</programlisting>
<para>
Used within multi-statement macros so that they can be used in places where
only one statement is expected by the compiler.
</para></refsect2>
<refsect2>
<title><anchor id="G-BEGIN-DECLS-CAPS">G_BEGIN_DECLS</title>
<programlisting>#define     G_BEGIN_DECLS</programlisting>
<para>
Used (along with <link linkend="G-END-DECLS-CAPS">G_END_DECLS</link>) to bracket header files. If the
compiler in use is a C++ compiler, adds <literal>extern "C"</literal> 
around the header.
</para></refsect2>
<refsect2>
<title><anchor id="G-END-DECLS-CAPS">G_END_DECLS</title>
<programlisting>#define     G_END_DECLS</programlisting>
<para>
Used (along with <link linkend="G-BEGIN-DECLS-CAPS">G_BEGIN_DECLS</link>) to bracket header files. If the
compiler in use is a C++ compiler, adds <literal>extern "C"</literal> 
around the header.
</para></refsect2>
<refsect2>
<title><anchor id="G-N-ELEMENTS-CAPS">G_N_ELEMENTS()</title>
<programlisting>#define G_N_ELEMENTS(arr)		(sizeof (arr) / sizeof ((arr)[0]))
</programlisting>
<para>
Determines the number of elements in an array. The array must be
declared so the compiler knows its size at compile-time; this 
macro will not work on an array allocated on the heap, only static
arrays or arrays on the stack.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>arr</parameter>&nbsp;:</entry>
<entry>the array


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-VA-COPY-CAPS">G_VA_COPY</title>
<programlisting>#define     G_VA_COPY</programlisting>
<para>
Portable way to copy <type>va_list</type> variables.
</para>
<para>
In order to use this function, you must include <filename>string.h</filename> 
yourself, because this macro may use <function><link linkend="memmove">memmove</link>()</function> and GLib 
does not include <function>string.h</function> for you.
</para></refsect2>
<refsect2>
<title><anchor id="G-STRINGIFY-CAPS">G_STRINGIFY()</title>
<programlisting>#define G_STRINGIFY(macro_or_string)	G_STRINGIFY_ARG (macro_or_string)
</programlisting>
<para>
Accepts a macro or a string and converts it into a string.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>macro_or_string</parameter>&nbsp;:</entry>
<entry>a macro or a string.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-GNUC-EXTENSION-CAPS">G_GNUC_EXTENSION</title>
<programlisting>#define     G_GNUC_EXTENSION</programlisting>
<para>
Expands to <literal>__extension__</literal> when <command>gcc</command> is 
used as the compiler.
This simply tells <command>gcc</command> not to warn about the following non-standard code
when compiling with the <option>-pedantic</option> option.
</para></refsect2>
<refsect2>
<title><anchor id="G-GNUC-CONST-CAPS">G_GNUC_CONST</title>
<programlisting>#define     G_GNUC_CONST</programlisting>
<para>
Expands to the GNU C <literal>const</literal> function attribute if the compiler is <command>gcc</command>.
Declaring a function as const enables better optimization of the function.
A const function doesn't examine any values except its parameters,
and has no effects except its return value.
See the GNU C documentation for details. 
</para>
<note><para>
A function that has pointer arguments and examines the data pointed to 
must <emphasis>not</emphasis> be declared const. Likewise, a function that 
calls a non-const function usually must not be const. It doesn't make sense 
for a const function to return void.
</para></note></refsect2>
<refsect2>
<title><anchor id="G-GNUC-NORETURN-CAPS">G_GNUC_NORETURN</title>
<programlisting>#define     G_GNUC_NORETURN</programlisting>
<para>
Expands to the GNU C <literal>noreturn</literal> function attribute if the compiler is <command>gcc</command>.
It is used for declaring functions which never return.
It enables optimization of the function, and avoids possible compiler
warnings. See the GNU C documentation for details. 
</para></refsect2>
<refsect2>
<title><anchor id="G-GNUC-UNUSED-CAPS">G_GNUC_UNUSED</title>
<programlisting>#define     G_GNUC_UNUSED</programlisting>
<para>
Expands to the GNU C <literal>unused</literal> function attribute if the compiler is <command>gcc</command>.
It is used for declaring functions which may never be used.
It avoids possible compiler warnings. See the GNU C documentation for details. 
</para></refsect2>
<refsect2>
<title><anchor id="G-GNUC-PURE-CAPS">G_GNUC_PURE</title>
<programlisting>#define     G_GNUC_PURE</programlisting>
<para>
Expands to the GNU C <literal>pure</literal> function attribute if the compiler is <command>gcc</command>.
Declaring a function as pure enables better optimization of the function.
A pure function has no effects except its return value and the return 
value depends only on the parameters and/or global variables.
See the GNU C documentation for details. 
</para></refsect2>