docs/reference/glib/tmpl/macros_misc.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Miscellaneous Macros
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 specialized macros which are not used often.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 These macros provide more specialized features which are not needed so often
  10 by application programmers.
  11 </para>
  12
  13 <!-- ##### SECTION See_Also ##### -->
  14 <para>
  15
  16 </para>
  17
  18 <!-- ##### MACRO G_INLINE_FUNC ##### -->
  19 <para>
  20 Used to declare inline functions. If inline functions are not supported on
  21 the particular platform, the macro evaluates to the empty string.
  22 </para>
  23
  24
  25
  26 <!-- ##### MACRO G_STMT_START ##### -->
  27 <para>
  28 Used within multi-statement macros so that they can be used in places where
  29 only one statement is expected by the compiler.
  30 </para>
  31
  32
  33
  34 <!-- ##### MACRO G_STMT_END ##### -->
  35 <para>
  36 Used within multi-statement macros so that they can be used in places where
  37 only one statement is expected by the compiler.
  38 </para>
  39
  40
  41
  42 <!-- ##### MACRO G_BEGIN_DECLS ##### -->
  43 <para>
  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>
  46 around the header.
  47 </para>
  48
  49
  50
  51 <!-- ##### MACRO G_END_DECLS ##### -->
  52 <para>
  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>
  55 around the header.
  56 </para>
  57
  58
  59
  60 <!-- ##### MACRO G_N_ELEMENTS ##### -->
  61 <para>
  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.
  66 </para>
  67
  68 @arr: the array
  69
  70
  71 <!-- ##### MACRO G_VA_COPY ##### -->
  72 <para>
  73 Portable way to copy <type>va_list</type> variables.
  74 </para>
  75 <para>
  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.
  79 </para>
  80
  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>.
  84
  85
  86 <!-- ##### MACRO G_STRINGIFY ##### -->
  87 <para>
  88 Accepts a macro or a string and converts it into a string.
  89 </para>
  90
  91 @macro_or_string: a macro or a string.
  92
  93
  94 <!-- ##### MACRO G_GNUC_EXTENSION ##### -->
  95 <para>
  96 Expands to <literal>__extension__</literal> when <command>gcc</command> is
  97 used as the compiler.
  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.
 100 </para>
 101
 102
 103
 104 <!-- ##### MACRO G_GNUC_CONST ##### -->
 105 <para>
 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.
 111 </para>
 112 <note><para>
 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.
 117 </para></note>
 118
 119
 120
 121 <!-- ##### MACRO G_GNUC_DEPRECATED ##### -->
 122 <para>
 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.
 129 </para>
 130
 131 @Since: 2.2
 132
 133
 134 <!-- ##### MACRO G_GNUC_NORETURN ##### -->
 135 <para>
 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.
 141 </para>
 142
 143
 144
 145 <!-- ##### MACRO G_GNUC_UNUSED ##### -->
 146 <para>
 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.
 150 </para>
 151
 152
 153
 154 <!-- ##### MACRO G_GNUC_PURE ##### -->
 155 <para>
 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.
 161 </para>
 162
 163
 164
 165 <!-- ##### MACRO G_GNUC_PRINTF ##### -->
 166 <para>
 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.
 172 </para>
 173 <informalexample><programlisting>
 174 gint g_snprintf (gchar  *string,
 175                  gulong       n,
 176                  gchar const *format,
 177                  ...) G_GNUC_PRINTF (3, 4);
 178 </programlisting></informalexample>
 179
 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.
 183
 184
 185 <!-- ##### MACRO G_GNUC_SCANF ##### -->
 186 <para>
 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.
 192 </para>
 193
 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.
 197
 198
 199 <!-- ##### MACRO G_GNUC_FORMAT ##### -->
 200 <para>
 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.
 211 </para>
 212 <informalexample><programlisting>
 213 gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
 214 </programlisting></informalexample>
 215
 216 @arg_idx: the index of the argument.
 217
 218
 219 <!-- ##### MACRO G_GNUC_FUNCTION ##### -->
 220 <para>
 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.
 225 </para>
 226
 227
 228
 229 <!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
 230 <para>
 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.
 238 </para>
 239
 240
 241
 242 <!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
 243 <para>
 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.
 250 </para>
 251
 252
 253
 254 <!-- ##### MACRO G_LIKELY ##### -->
 255 <para>
 256 Hints the compiler that the expression is likely to evaluate to a true
 257 value. The compiler may use this information for optimizations.
 258 </para>
 259 <informalexample><programlisting>
 260 if (G_LIKELY (random () != 1))
 261   g_print ("not one");
 262 </programlisting></informalexample>
 263
 264 @expr: the expression
 265 @Since: 2.2
 266
 267
 268 <!-- ##### MACRO G_UNLIKELY ##### -->
 269 <para>
 270 Hints the compiler that the expression is unlikely to evaluate to a true
 271 value. The compiler may use this information for optimizations.
 272 </para>
 273 <informalexample><programlisting>
 274 if (G_UNLIKELY (random () == 1))
 275   g_print ("a random one");
 276 </programlisting></informalexample>
 277
 278 @expr: the expression
 279 @Since: 2.2
 280
 281
 282 <!-- ##### MACRO G_STRLOC ##### -->
 283 <para>
 284 Expands to a string identifying the current code position.
 285 </para>
 286
 287
 288
 289 <!-- ##### MACRO G_GINT16_FORMAT ##### -->
 290 <para>
 291 This is the platform dependent conversion specifier for scanning and
 292 printing 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.
 295 </para>
 296
 297 <para>
 298 <informalexample>
 299 <programlisting>
 300 gint16 in;
 301 gint32 out;
 302 sscanf ("42", "%" G_GINT16_FORMAT, &amp;in)
 303 out = in * 1000;
 304 g_print ("%" G_GINT32_FORMAT, out);
 305 </programlisting>
 306 </informalexample>
 307 </para>
 308
 309
 310
 311 <!-- ##### MACRO G_GUINT16_FORMAT ##### -->
 312 <para>
 313 This is the platform dependent conversion specifier for scanning and
 314 printing values of type #guint16. See also #G_GINT16_FORMAT.
 315 </para>
 316
 317
 318
 319 <!-- ##### MACRO G_GINT32_FORMAT ##### -->
 320 <para>
 321 This is the platform dependent conversion specifier for scanning and
 322 printing values of type #gint32. See also #G_GINT16_FORMAT.
 323 </para>
 324
 325
 326
 327 <!-- ##### MACRO G_GUINT32_FORMAT ##### -->
 328 <para>
 329 This is the platform dependent conversion specifier for scanning and
 330 printing values of type #guint32. See also #G_GINT16_FORMAT.
 331 </para>
 332
 333
 334
 335 <!-- ##### MACRO G_GINT64_FORMAT ##### -->
 336 <para>
 337 This is the platform dependent conversion specifier for scanning and
 338 printing values of type #gint64. See also #G_GINT16_FORMAT.
 339 </para>
 340
 341 <note>
 342 <para>
 343 Some platforms do not support scanning and printing 64 bit integers,
 344 even though the types are supported. On such platforms #G_GINT64_FORMAT
 345 is not defined.
 346 </para>
 347 </note>
 348
 349
 350
 351 <!-- ##### MACRO G_GUINT64_FORMAT ##### -->
 352 <para>
 353 This is the platform dependent conversion specifier for scanning and
 354 printing values of type #guint64. See also #G_GINT16_FORMAT.
 355 </para>
 356
 357 <note>
 358 <para>
 359 Some platforms do not support scanning and printing 64 bit integers,
 360 even though the types are supported. On such platforms #G_GUINT64_FORMAT
 361 is not defined.
 362 </para>
 363 </note>
 364
 365
 366