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_GNUC_INTERNAL ##### -->
 255 <para>
 256 Expands to the GNU C <literal>visibility(hidden)</literal> attribute if the
 257 compiler is <command>gcc</command>. This attribute can be used for marking
 258 library functions as being used internally to the lib only, to not create
 259 inefficient PLT entries. Note that static functions do not need to be marked
 260 as internal in this way. See the GNU C documentation for details.
 261 </para>
 262
 263 Since: 2.6
 264
 265
 266
 267 <!-- ##### MACRO G_LIKELY ##### -->
 268 <para>
 269 Hints the compiler that the expression is likely to evaluate to a true
 270 value. The compiler may use this information for optimizations.
 271 </para>
 272 <informalexample><programlisting>
 273 if (G_LIKELY (random () != 1))
 274   g_print ("not one");
 275 </programlisting></informalexample>
 276
 277 @expr: the expression
 278 @Since: 2.2
 279
 280
 281 <!-- ##### MACRO G_UNLIKELY ##### -->
 282 <para>
 283 Hints the compiler that the expression is unlikely to evaluate to a true
 284 value. The compiler may use this information for optimizations.
 285 </para>
 286 <informalexample><programlisting>
 287 if (G_UNLIKELY (random () == 1))
 288   g_print ("a random one");
 289 </programlisting></informalexample>
 290
 291 @expr: the expression
 292 @Since: 2.2
 293
 294
 295 <!-- ##### MACRO G_STRLOC ##### -->
 296 <para>
 297 Expands to a string identifying the current code position.
 298 </para>
 299
 300
 301
 302 <!-- ##### MACRO G_STRFUNC ##### -->
 303 <para>
 304
 305 </para>
 306
 307
 308
 309 <!-- ##### MACRO G_GINT16_MODIFIER ##### -->
 310 <para>
 311 The platform dependent length modifier for constructing printf() conversion
 312 specifiers for values of type #gint16. It is a string literal, but doesn't
 313 include the percent-sign, such that you can add precision and length
 314 modifiers between percent-sign and conversion specifier and append a
 315 conversion specifier.
 316 </para>
 317
 318 <para>
 319 The following example prints "0x7b";
 320 <informalexample>
 321 <programlisting>
 322 gint16 value = 123;
 323 g_print ("%#" G_GINT16_MODIFIER "x", value);
 324 </programlisting>
 325 </informalexample>
 326 </para>
 327
 328 @Since: 2.4
 329
 330
 331 <!-- ##### MACRO G_GINT16_FORMAT ##### -->
 332 <para>
 333 This is the platform dependent conversion specifier for scanning and
 334 printing values of type #gint16. It is a string literal, but doesn't
 335 include the percent-sign, such that you can add precision and length
 336 modifiers between percent-sign and conversion specifier.
 337 </para>
 338
 339 <para>
 340 <informalexample>
 341 <programlisting>
 342 gint16 in;
 343 gint32 out;
 344 sscanf ("42", "%" G_GINT16_FORMAT, &amp;in)
 345 out = in * 1000;
 346 g_print ("%" G_GINT32_FORMAT, out);
 347 </programlisting>
 348 </informalexample>
 349 </para>
 350
 351
 352
 353 <!-- ##### MACRO G_GUINT16_FORMAT ##### -->
 354 <para>
 355 This is the platform dependent conversion specifier for scanning and
 356 printing values of type #guint16. See also #G_GINT16_FORMAT.
 357 </para>
 358
 359
 360
 361 <!-- ##### MACRO G_GINT32_MODIFIER ##### -->
 362 <para>
 363 The platform dependent length modifier for constructing printf() conversion
 364 specifiers for values of type #gint32. See also #G_GINT16_MODIFIER.
 365 </para>
 366
 367 @Since: 2.4
 368
 369
 370 <!-- ##### MACRO G_GINT32_FORMAT ##### -->
 371 <para>
 372 This is the platform dependent conversion specifier for scanning and
 373 printing values of type #gint32. See also #G_GINT16_FORMAT.
 374 </para>
 375
 376
 377
 378 <!-- ##### MACRO G_GUINT32_FORMAT ##### -->
 379 <para>
 380 This is the platform dependent conversion specifier for scanning and
 381 printing values of type #guint32. See also #G_GINT16_FORMAT.
 382 </para>
 383
 384
 385
 386 <!-- ##### MACRO G_GINT64_MODIFIER ##### -->
 387 <para>
 388 The platform dependent length modifier for constructing printf() conversion
 389 specifiers for values of type #gint64. See also #G_GINT16_MODIFIER.
 390 </para>
 391
 392 <note>
 393 <para>
 394 Some platforms do not support printing 64 bit integers,
 395 even though the types are supported. On such platforms #G_GINT64_MODIFIER
 396 is not defined.
 397 </para>
 398 </note>
 399
 400 @Since: 2.4
 401
 402
 403 <!-- ##### MACRO G_GINT64_FORMAT ##### -->
 404 <para>
 405 This is the platform dependent conversion specifier for scanning and
 406 printing values of type #gint64. See also #G_GINT16_FORMAT.
 407 </para>
 408
 409 <note>
 410 <para>
 411 Some platforms do not support scanning and printing 64 bit integers,
 412 even though the types are supported. On such platforms #G_GINT64_FORMAT
 413 is not defined. Note that scanf() may not support 64 bit integers, even
 414 if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not
 415 recommended for parsing anyway; consider using g_strtoull() instead.
 416 </para>
 417 </note>
 418
 419
 420
 421 <!-- ##### MACRO G_GUINT64_FORMAT ##### -->
 422 <para>
 423 This is the platform dependent conversion specifier for scanning and
 424 printing values of type #guint64. See also #G_GINT16_FORMAT.
 425 </para>
 426
 427 <note>
 428 <para>
 429 Some platforms do not support scanning and printing 64 bit integers,
 430 even though the types are supported. On such platforms #G_GUINT64_FORMAT
 431 is not defined.  Note that scanf() may not support 64 bit integers, even
 432 if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() is not
 433 recommended for parsing anyway; consider using g_strtoull() instead.
 434 </para>
 435 </note>
 436
 437
 438
 439 <!-- ##### MACRO G_GSIZE_MODIFIER ##### -->
 440 <para>
 441
 442 </para>
 443
 444
 445
 446 <!-- ##### MACRO G_GSIZE_FORMAT ##### -->
 447 <para>
 448
 449 </para>
 450
 451
 452
 453 <!-- ##### MACRO G_GSSIZE_FORMAT ##### -->
 454 <para>
 455
 456 </para>
 457
 458
 459