Miscellaneous Macros
<!-- ##### SECTION Short_Description ##### -->
-specialised macros which are not used often.
+specialized macros which are not used often.
<!-- ##### SECTION Long_Description ##### -->
<para>
<!-- ##### MACRO G_BEGIN_DECLS ##### -->
<para>
-
+Used (along with #G_END_DECLS) to bracket header files. If the
+compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
+around the header.
</para>
<!-- ##### MACRO G_END_DECLS ##### -->
<para>
-
+Used (along with #G_BEGIN_DECLS) to bracket header files. If the
+compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
+around the header.
</para>
<!-- ##### MACRO G_N_ELEMENTS ##### -->
<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>
-@arr:
+@arr: the array
<!-- ##### MACRO G_VA_COPY ##### -->
<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>memmove()</function> and GLib
+does not include <function>string.h</function> for you.
+</para>
+<!-- # Unused Parameters # -->
@ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
@ap2: a <type>va_list</type>.
<!-- ##### MACRO G_STRINGIFY ##### -->
<para>
-
+Accepts a macro or a string and converts it into a string.
</para>
-@macro_or_string:
+@macro_or_string: a macro or a string.
<!-- ##### MACRO G_GNUC_EXTENSION ##### -->
<para>
-Expands to "__extension__" when GNU C is used as the compiler.
-This simply tells GNU C not to warn about the following non-standard code
-when compiling with the -pedantic option.
+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>
<!-- ##### MACRO G_GNUC_CONST ##### -->
<para>
-Expands to the GNU C const function attribute if the compiler is GNU C.
-This enables optimization of the function.
+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>
+
+
+
+<!-- ##### MACRO G_GNUC_DEPRECATED ##### -->
+<para>
+Expands to the GNU C <literal>deprecated</literal> attribute if the compiler
+is <command>gcc</command>.
+It can be used to mark typedefs, variables and functions as deprecated.
+When called with the <option>-Wdeprecated</option> option, the compiler will
+generate warnings when deprecated interfaces are used.
See the GNU C documentation for details.
</para>
+@Since: 2.2
<!-- ##### MACRO G_GNUC_NORETURN ##### -->
<para>
-Expands to the GNU C noreturn function attribute if the compiler is GNU C.
+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.
<!-- ##### MACRO G_GNUC_UNUSED ##### -->
<para>
-Expands to the GNU C unused function attribute if the compiler is GNU C.
+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>
<!-- ##### MACRO G_GNUC_PURE ##### -->
<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>
<!-- ##### MACRO G_GNUC_PRINTF ##### -->
<para>
-Expands to the GNU C format function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
This is used for declaring functions which take a variable number of
arguments, with the same syntax as <function>printf()</function>.
It allows the compiler to type-check the arguments passed to the function.
See the GNU C documentation for details.
</para>
+<informalexample><programlisting>
+gint g_snprintf (gchar *string,
+ gulong n,
+ gchar const *format,
+ ...) G_GNUC_PRINTF (3, 4);
+</programlisting></informalexample>
@format_idx: the index of the argument corresponding to the format string.
(The arguments are numbered from 1).
<!-- ##### MACRO G_GNUC_SCANF ##### -->
<para>
-Expands to the GNU C format function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
This is used for declaring functions which take a variable number of
arguments, with the same syntax as <function>scanf()</function>.
It allows the compiler to type-check the arguments passed to the function.
<!-- ##### MACRO G_GNUC_FORMAT ##### -->
<para>
-Expands to the GNU C format_arg function attribute if the compiler is GNU C.
-This is used for declaring functions which take a variable number of
-parameters, like <function>printf()</function> and
-<function>scanf()</function>. See the GNU C documentation for details.
-
-FIXME: I can't find this in my GNU C documentation. Take out?
+Expands to the GNU C <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>.
+This function attribute specifies that a function takes a format
+string for a <function>printf()</function>, <function>scanf()</function>,
+<function>strftime()</function> or <function>strfmon()</function> style
+function and modifies it, so that the result can be passed to a
+<function>printf()</function>, <function>scanf()</function>,
+<function>strftime()</function> or <function>strfmon()</function> style
+function (with the remaining arguments to the format function the same as
+they would have been for the unmodified string).
+See the GNU C documentation for details.
</para>
+<informalexample><programlisting>
+gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
+</programlisting></informalexample>
@arg_idx: the index of the argument.
<!-- ##### MACRO G_GNUC_FUNCTION ##### -->
<para>
-Expands to the GNU C __FUNCTION__ variable if the compiler is GNU C,
-or "" if it isn't.
-The GNU C __FUNCTION__ variable contains the name of the current function.
-See the GNU C documentation for details.
+Expands to the GNU C <literal>__FUNCTION__</literal> variable if the
+compiler is <command>gcc</command>, or "" if it isn't. The GNU C
+<literal>__FUNCTION__</literal> variable contains the name of the
+current function. See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
<para>
-Expands to the GNU C __PRETTY_FUNCTION__ variable if the compiler is GNU C,
-or "" if it isn't.
-The GNU C __PRETTY_FUNCTION__ variable contains the name of the current
-function. For a C program this is the same as the __FUNCTION__ variable
-but for C++ it also includes extra information such as the class
-and function prototype. See the GNU C documentation for details.
+Expands to the GNU C <literal>__PRETTY_FUNCTION__</literal> variable
+if the compiler is <command>gcc</command>, or "" if it isn't.
+The GNU C <literal>__PRETTY_FUNCTION__</literal> variable contains the
+name of the current function. For a C program this is the same as the
+<literal>__FUNCTION__</literal> variable but for C++ it also includes
+extra information such as the class and function prototype. See the
+GNU C documentation for details.
+</para>
+
+
+
+<!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
+<para>
+Expands to the GNU C <literal>no_instrument_function</literal> function
+attribute if the compiler is <command>gcc</command>. Functions with this
+attribute will not be
+instrumented for profiling, when the compiler is called with the
+<option>-finstrument-functions</option> option.
+See the GNU C documentation for details.
+</para>
+
+
+
+<!-- ##### MACRO G_LIKELY ##### -->
+<para>
+Hints the compiler that the expression is likely to evaluate to a true
+value. The compiler may use this information for optimizations.
+</para>
+<informalexample><programlisting>
+if (G_LIKELY (random () != 1))
+ g_print ("not one");
+</programlisting></informalexample>
+
+@expr: the expression
+@Since: 2.2
+
+
+<!-- ##### MACRO G_UNLIKELY ##### -->
+<para>
+Hints the compiler that the expression is unlikely to evaluate to a true
+value. The compiler may use this information for optimizations.
</para>
+<informalexample><programlisting>
+if (G_UNLIKELY (random () == 1))
+ g_print ("a random one");
+</programlisting></informalexample>
+@expr: the expression
+@Since: 2.2
<!-- ##### MACRO G_STRLOC ##### -->
<para>
+Expands to a string identifying the current code position.
+</para>
+
+
+
+<!-- ##### MACRO G_GINT16_MODIFIER ##### -->
+<para>
+The platform dependent length modifier for constructing printf() conversion
+specifiers for values of type #gint16. It is a string literal, but doesn't
+include the percent-sign, such that you can add precision and length
+modifiers between percent-sign and conversion specifier and append a
+conversion specifier.
+</para>
+<para>
+The following example prints "0x7b";
+<informalexample>
+<programlisting>
+gint16 value = 123;
+g_print ("%#" G_GINT16_MODIFIER "x", value);
+</programlisting>
+</informalexample>
</para>
+@Since: 2.4
<!-- ##### MACRO G_GINT16_FORMAT ##### -->
+<!-- ##### MACRO G_GINT32_MODIFIER ##### -->
+<para>
+The platform dependent length modifier for constructing printf() conversion
+specifiers for values of type #gint32. See also #G_GINT16_MODIFIER.
+</para>
+
+@Since: 2.4
+
<!-- ##### MACRO G_GINT32_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
+<!-- ##### MACRO G_GINT64_MODIFIER ##### -->
+<para>
+The platform dependent length modifier for constructing printf() conversion
+specifiers for values of type #gint32. See also #G_GINT16_MODIFIER.
+</para>
+
+<note>
+<para>
+Some platforms do not support printing 64 bit integers,
+even though the types are supported. On such platforms #G_GINT64_MODIFIER
+is not defined.
+</para>
+</note>
+
+@Since: 2.4
+
<!-- ##### MACRO G_GINT64_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
<note>
<para>
Some platforms do not support scanning and printing 64 bit integers,
-even though the types are supported. On such platforms G_GINT64_FORMAT
-is not defined.
+even though the types are supported. On such platforms #G_GINT64_FORMAT
+is not defined. Note that scanf() may not support 64 bit integers, even
+if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not
+recommended for parsing anyway; consider using g_strtoull() instead.
</para>
</note>
<note>
<para>
Some platforms do not support scanning and printing 64 bit integers,
-even though the types are supported. On such platforms G_GUINT64_FORMAT
-is not defined.
+even though the types are supported. On such platforms #G_GUINT64_FORMAT
+is not defined. Note that scanf() may not support 64 bit integers, even
+if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not
+recommended for parsing anyway; consider using g_strtoull() instead.
</para>
</note>
projects / platform / upstream / glib.git / blobdiff