<!-- ##### SECTION Title ##### --> Miscellaneous Macros <!-- ##### SECTION Short_Description ##### --> specialized macros which are not used often. <!-- ##### SECTION Long_Description ##### --> <para> These macros provide more specialized features which are not needed so often by application programmers. </para> <!-- ##### SECTION See_Also ##### --> <para> </para> <!-- ##### MACRO G_INLINE_FUNC ##### --> <para> Used to declare inline functions. If inline functions are not supported on the particular platform, the macro evaluates to the empty string. </para> <!-- ##### MACRO G_STMT_START ##### --> <para> Used within multi-statement macros so that they can be used in places where only one statement is expected by the compiler. </para> <!-- ##### MACRO G_STMT_END ##### --> <para> Used within multi-statement macros so that they can be used in places where only one statement is expected by the compiler. </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: 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: a macro or a string. <!-- ##### MACRO G_GNUC_EXTENSION ##### --> <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> <!-- ##### MACRO G_GNUC_CONST ##### --> <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> <!-- ##### 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 <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> <!-- ##### MACRO G_GNUC_UNUSED ##### --> <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> <!-- ##### 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 <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). @arg_idx: the index of the first of the format arguments. <!-- ##### MACRO G_GNUC_SCANF ##### --> <para> 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. See the GNU C documentation for details. </para> @format_idx: the index of the argument corresponding to the format string. (The arguments are numbered from 1). @arg_idx: the index of the first of the format arguments. <!-- ##### MACRO G_GNUC_FORMAT ##### --> <para> 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 <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 <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_STRFUNC ##### --> <para> </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 ##### --> <para> This is the platform dependent conversion specifier for scanning and printing 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. </para> <para> <informalexample> <programlisting> gint16 in; gint32 out; sscanf ("42", "%" G_GINT16_FORMAT, &in) out = in * 1000; g_print ("%" G_GINT32_FORMAT, out); </programlisting> </informalexample> </para> <!-- ##### MACRO G_GUINT16_FORMAT ##### --> <para> This is the platform dependent conversion specifier for scanning and printing values of type #guint16. See also #G_GINT16_FORMAT. </para> <!-- ##### 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 printing values of type #gint32. See also #G_GINT16_FORMAT. </para> <!-- ##### MACRO G_GUINT32_FORMAT ##### --> <para> This is the platform dependent conversion specifier for scanning and printing values of type #guint32. See also #G_GINT16_FORMAT. </para> <!-- ##### MACRO G_GINT64_MODIFIER ##### --> <para> The platform dependent length modifier for constructing printf() conversion specifiers for values of type #gint64. 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 printing values of type #gint64. See also #G_GINT16_FORMAT. </para> <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. 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> <!-- ##### MACRO G_GUINT64_FORMAT ##### --> <para> This is the platform dependent conversion specifier for scanning and printing values of type #guint64. See also #G_GINT16_FORMAT. </para> <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. 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> <!-- ##### MACRO G_GSIZE_MODIFIER ##### --> <para> </para> <!-- ##### MACRO G_GSIZE_FORMAT ##### --> <para> </para> <!-- ##### MACRO G_GSSIZE_FORMAT ##### --> <para> </para>