docs/reference/glib/tmpl/macros_misc.sgml - third_party/glib - Git at Google

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

 <!-- ##### SECTION Stability_Level ##### -->


 <!-- ##### 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 calls
 to 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_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
 calls to 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_MALLOC ##### -->
 <para>
 Expands to the GNU C <literal>malloc</literal> function attribute if the compiler is
 <command>gcc</command>. Declaring a function as malloc enables better optimization of the
 function. A function can have the malloc attribute if it returns a pointer which is guaranteed
 to not alias with any other pointer when the function returns (in practice, this means newly
 allocated memory).
 See the GNU C documentation for details.
 </para>

 @Since: 2.6


 <!-- ##### 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_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_HAVE_GNUC_VISIBILITY ##### -->
 <para>
 This macro is defined as 1 if the the compiler supports ELF visibility
 attributes (currently only <command>gcc</command>).
 </para>

 Since: 2.6


 <!-- ##### MACRO G_GNUC_INTERNAL ##### -->
 <para>
 Expands to the GNU C <literal>visibility(hidden)</literal> attribute if the
 compiler supports it  (currently only <command>gcc</command>). This attribute
 can be used for marking library functions as being used internally to the lib
 only, to not create inefficient PLT entries. Note that static functions do not
 need to be marked as internal in this way. See the GNU C documentation for details.
 </para>

 Since: 2.6


 <!-- ##### 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>
 Expands to a string identifying the current function.
 </para>

 @Since: 2.4


 <!-- ##### MACRO G_GINT16_MODIFIER ##### -->
 <para>
 The platform dependent length modifier for constructing printf() conversion
 specifiers for values of type #gint16 or #guint16. 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, &amp;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 or #guint32. 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 or #guint64. 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>
 The platform dependent length modifier for constructing printf() conversion
 specifiers for values of type #gsize or #gssize. See also #G_GINT16_MODIFIER.
 </para>

 @Since: 2.6


 <!-- ##### MACRO G_GSIZE_FORMAT ##### -->
 <para>
 This is the platform dependent conversion specifier for scanning and
 printing values of type #gsize. See also #G_GINT16_FORMAT.
 </para>

 @Since: 2.6


 <!-- ##### MACRO G_GSSIZE_FORMAT ##### -->
 <para>
 This is the platform dependent conversion specifier for scanning and
 printing values of type #gssize. See also #G_GINT16_FORMAT.
 </para>

 @Since: 2.6
	<!-- ##### 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>

	<!-- ##### SECTION Stability_Level ##### -->


	<!-- ##### 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 calls
	to 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_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
	calls to 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_MALLOC ##### -->
	<para>
	Expands to the GNU C <literal>malloc</literal> function attribute if the compiler is
	<command>gcc</command>. Declaring a function as malloc enables better optimization of the
	function. A function can have the malloc attribute if it returns a pointer which is guaranteed
	to not alias with any other pointer when the function returns (in practice, this means newly
	allocated memory).
	See the GNU C documentation for details.
	</para>

	@Since: 2.6


	<!-- ##### 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_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_HAVE_GNUC_VISIBILITY ##### -->
	<para>
	This macro is defined as 1 if the the compiler supports ELF visibility
	attributes (currently only <command>gcc</command>).
	</para>

	Since: 2.6



	<!-- ##### MACRO G_GNUC_INTERNAL ##### -->
	<para>
	Expands to the GNU C <literal>visibility(hidden)</literal> attribute if the
	compiler supports it (currently only <command>gcc</command>). This attribute
	can be used for marking library functions as being used internally to the lib
	only, to not create inefficient PLT entries. Note that static functions do not
	need to be marked as internal in this way. See the GNU C documentation for details.
	</para>

	Since: 2.6



	<!-- ##### 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>
	Expands to a string identifying the current function.
	</para>

	@Since: 2.4


	<!-- ##### MACRO G_GINT16_MODIFIER ##### -->
	<para>
	The platform dependent length modifier for constructing printf() conversion
	specifiers for values of type #gint16 or #guint16. 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 or #guint32. 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 or #guint64. 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>
	The platform dependent length modifier for constructing printf() conversion
	specifiers for values of type #gsize or #gssize. See also #G_GINT16_MODIFIER.
	</para>

	@Since: 2.6


	<!-- ##### MACRO G_GSIZE_FORMAT ##### -->
	<para>
	This is the platform dependent conversion specifier for scanning and
	printing values of type #gsize. See also #G_GINT16_FORMAT.
	</para>

	@Since: 2.6


	<!-- ##### MACRO G_GSSIZE_FORMAT ##### -->
	<para>
	This is the platform dependent conversion specifier for scanning and
	printing values of type #gssize. See also #G_GINT16_FORMAT.
	</para>

	@Since: 2.6