1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 specialized macros which are not used often.
7 <!-- ##### SECTION Long_Description ##### -->
9 These macros provide more specialized features which are not needed so often
10 by application programmers.
13 <!-- ##### SECTION See_Also ##### -->
18 <!-- ##### MACRO G_INLINE_FUNC ##### -->
20 Used to declare inline functions. If inline functions are not supported on
21 the particular platform, the macro evaluates to the empty string.
26 <!-- ##### MACRO G_STMT_START ##### -->
28 Used within multi-statement macros so that they can be used in places where
29 only one statement is expected by the compiler.
34 <!-- ##### MACRO G_STMT_END ##### -->
36 Used within multi-statement macros so that they can be used in places where
37 only one statement is expected by the compiler.
42 <!-- ##### MACRO G_BEGIN_DECLS ##### -->
44 Used (along with #G_END_DECLS) to bracket header files. If the
45 compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
51 <!-- ##### MACRO G_END_DECLS ##### -->
53 Used (along with #G_BEGIN_DECLS) to bracket header files. If the
54 compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
60 <!-- ##### MACRO G_N_ELEMENTS ##### -->
62 Determines the number of elements in an array. The array must be
63 declared so the compiler knows its size at compile-time; this
64 macro will not work on an array allocated on the heap, only static
65 arrays or arrays on the stack.
71 <!-- ##### MACRO G_VA_COPY ##### -->
73 Portable way to copy <type>va_list</type> variables.
76 In order to use this function, you must include <filename>string.h</filename>
77 yourself, because this macro may use <function>memmove()</function> and GLib
78 does not include <function>string.h</function> for you.
81 <!-- # Unused Parameters # -->
82 @ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
83 @ap2: a <type>va_list</type>.
86 <!-- ##### MACRO G_STRINGIFY ##### -->
88 Accepts a macro or a string and converts it into a string.
91 @macro_or_string: a macro or a string.
94 <!-- ##### MACRO G_GNUC_EXTENSION ##### -->
96 Expands to <literal>__extension__</literal> when <command>gcc</command> is
98 This simply tells <command>gcc</command> not to warn about the following non-standard code
99 when compiling with the <option>-pedantic</option> option.
104 <!-- ##### MACRO G_GNUC_CONST ##### -->
106 Expands to the GNU C <literal>const</literal> function attribute if the compiler is <command>gcc</command>.
107 Declaring a function as const enables better optimization of the function.
108 A const function doesn't examine any values except its parameters,
109 and has no effects except its return value.
110 See the GNU C documentation for details.
113 A function that has pointer arguments and examines the data pointed to
114 must <emphasis>not</emphasis> be declared const. Likewise, a function that
115 calls a non-const function usually must not be const. It doesn't make sense
116 for a const function to return void.
121 <!-- ##### MACRO G_GNUC_DEPRECATED ##### -->
123 Expands to the GNU C <literal>deprecated</literal> attribute if the compiler
124 is <command>gcc</command>.
125 It can be used to mark typedefs, variables and functions as deprecated.
126 When called with the <option>-Wdeprecated</option> option, the compiler will
127 generate warnings when deprecated interfaces are used.
128 See the GNU C documentation for details.
134 <!-- ##### MACRO G_GNUC_NORETURN ##### -->
136 Expands to the GNU C <literal>noreturn</literal> function attribute if the
137 compiler is <command>gcc</command>.
138 It is used for declaring functions which never return.
139 It enables optimization of the function, and avoids possible compiler
140 warnings. See the GNU C documentation for details.
145 <!-- ##### MACRO G_GNUC_UNUSED ##### -->
147 Expands to the GNU C <literal>unused</literal> function attribute if the compiler is <command>gcc</command>.
148 It is used for declaring functions which may never be used.
149 It avoids possible compiler warnings. See the GNU C documentation for details.
154 <!-- ##### MACRO G_GNUC_PURE ##### -->
156 Expands to the GNU C <literal>pure</literal> function attribute if the compiler is <command>gcc</command>.
157 Declaring a function as pure enables better optimization of the function.
158 A pure function has no effects except its return value and the return
159 value depends only on the parameters and/or global variables.
160 See the GNU C documentation for details.
165 <!-- ##### MACRO G_GNUC_PRINTF ##### -->
167 Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
168 This is used for declaring functions which take a variable number of
169 arguments, with the same syntax as <function>printf()</function>.
170 It allows the compiler to type-check the arguments passed to the function.
171 See the GNU C documentation for details.
173 <informalexample><programlisting>
174 gint g_snprintf (gchar *string,
177 ...) G_GNUC_PRINTF (3, 4);
178 </programlisting></informalexample>
180 @format_idx: the index of the argument corresponding to the format string.
181 (The arguments are numbered from 1).
182 @arg_idx: the index of the first of the format arguments.
185 <!-- ##### MACRO G_GNUC_SCANF ##### -->
187 Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
188 This is used for declaring functions which take a variable number of
189 arguments, with the same syntax as <function>scanf()</function>.
190 It allows the compiler to type-check the arguments passed to the function.
191 See the GNU C documentation for details.
194 @format_idx: the index of the argument corresponding to the format string.
195 (The arguments are numbered from 1).
196 @arg_idx: the index of the first of the format arguments.
199 <!-- ##### MACRO G_GNUC_FORMAT ##### -->
201 Expands to the GNU C <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>.
202 This function attribute specifies that a function takes a format
203 string for a <function>printf()</function>, <function>scanf()</function>,
204 <function>strftime()</function> or <function>strfmon()</function> style
205 function and modifies it, so that the result can be passed to a
206 <function>printf()</function>, <function>scanf()</function>,
207 <function>strftime()</function> or <function>strfmon()</function> style
208 function (with the remaining arguments to the format function the same as
209 they would have been for the unmodified string).
210 See the GNU C documentation for details.
212 <informalexample><programlisting>
213 gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
214 </programlisting></informalexample>
216 @arg_idx: the index of the argument.
219 <!-- ##### MACRO G_GNUC_FUNCTION ##### -->
221 Expands to the GNU C <literal>__FUNCTION__</literal> variable if the
222 compiler is <command>gcc</command>, or "" if it isn't. The GNU C
223 <literal>__FUNCTION__</literal> variable contains the name of the
224 current function. See the GNU C documentation for details.
229 <!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
231 Expands to the GNU C <literal>__PRETTY_FUNCTION__</literal> variable
232 if the compiler is <command>gcc</command>, or "" if it isn't.
233 The GNU C <literal>__PRETTY_FUNCTION__</literal> variable contains the
234 name of the current function. For a C program this is the same as the
235 <literal>__FUNCTION__</literal> variable but for C++ it also includes
236 extra information such as the class and function prototype. See the
237 GNU C documentation for details.
242 <!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
244 Expands to the GNU C <literal>no_instrument_function</literal> function
245 attribute if the compiler is <command>gcc</command>. Functions with this
246 attribute will not be
247 instrumented for profiling, when the compiler is called with the
248 <option>-finstrument-functions</option> option.
249 See the GNU C documentation for details.
254 <!-- ##### MACRO G_LIKELY ##### -->
256 Hints the compiler that the expression is likely to evaluate to a true
257 value. The compiler may use this information for optimizations.
259 <informalexample><programlisting>
260 if (G_LIKELY (random () != 1))
262 </programlisting></informalexample>
264 @expr: the expression
268 <!-- ##### MACRO G_UNLIKELY ##### -->
270 Hints the compiler that the expression is unlikely to evaluate to a true
271 value. The compiler may use this information for optimizations.
273 <informalexample><programlisting>
274 if (G_UNLIKELY (random () == 1))
275 g_print ("a random one");
276 </programlisting></informalexample>
278 @expr: the expression
282 <!-- ##### MACRO G_STRLOC ##### -->
284 Expands to a string identifying the current code position.
289 <!-- ##### MACRO G_GINT16_MODIFIER ##### -->
291 The platform dependent length modifier for constructing printf() conversion
292 specifiers for values of type #gint16. It is a string literal, but doesn't
293 include the percent-sign, such that you can add precision and length
294 modifiers between percent-sign and conversion specifier and append a
295 conversion specifier.
299 The following example prints "0x7b";
303 g_print ("%#" G_GINT16_MODIFIER "x", value);
311 <!-- ##### MACRO G_GINT16_FORMAT ##### -->
313 This is the platform dependent conversion specifier for scanning and
314 printing values of type #gint16. It is a string literal, but doesn't
315 include the percent-sign, such that you can add precision and length
316 modifiers between percent-sign and conversion specifier.
324 sscanf ("42", "%" G_GINT16_FORMAT, &in)
326 g_print ("%" G_GINT32_FORMAT, out);
333 <!-- ##### MACRO G_GUINT16_FORMAT ##### -->
335 This is the platform dependent conversion specifier for scanning and
336 printing values of type #guint16. See also #G_GINT16_FORMAT.
341 <!-- ##### MACRO G_GINT32_MODIFIER ##### -->
343 The platform dependent length modifier for constructing printf() conversion
344 specifiers for values of type #gint32. See also #G_GINT16_MODIFIER.
349 <!-- ##### MACRO G_GINT32_FORMAT ##### -->
351 This is the platform dependent conversion specifier for scanning and
352 printing values of type #gint32. See also #G_GINT16_FORMAT.
357 <!-- ##### MACRO G_GUINT32_FORMAT ##### -->
359 This is the platform dependent conversion specifier for scanning and
360 printing values of type #guint32. See also #G_GINT16_FORMAT.
365 <!-- ##### MACRO G_GINT64_MODIFIER ##### -->
367 The platform dependent length modifier for constructing printf() conversion
368 specifiers for values of type #gint32. See also #G_GINT16_MODIFIER.
373 Some platforms do not support printing 64 bit integers,
374 even though the types are supported. On such platforms #G_GINT64_MODIFIER
381 <!-- ##### MACRO G_GINT64_FORMAT ##### -->
383 This is the platform dependent conversion specifier for scanning and
384 printing values of type #gint64. See also #G_GINT16_FORMAT.
389 Some platforms do not support scanning and printing 64 bit integers,
390 even though the types are supported. On such platforms #G_GINT64_FORMAT
391 is not defined. Note that scanf() may not support 64 bit integers, even
392 if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not
393 recommended for parsing anyway; consider using g_strtoull() instead.
399 <!-- ##### MACRO G_GUINT64_FORMAT ##### -->
401 This is the platform dependent conversion specifier for scanning and
402 printing values of type #guint64. See also #G_GINT16_FORMAT.
407 Some platforms do not support scanning and printing 64 bit integers,
408 even though the types are supported. On such platforms #G_GUINT64_FORMAT
409 is not defined. Note that scanf() may not support 64 bit integers, even
410 if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not
411 recommended for parsing anyway; consider using g_strtoull() instead.