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_NORETURN ##### -->
 122 <para>
 123 Expands to the GNU C <literal>noreturn</literal> function attribute if the compiler is <command>gcc</command>.
 124 It is used for declaring functions which never return.
 125 It enables optimization of the function, and avoids possible compiler
 126 warnings. See the GNU C documentation for details.
 127 </para>
 128
 129
 130
 131 <!-- ##### MACRO G_GNUC_UNUSED ##### -->
 132 <para>
 133 Expands to the GNU C <literal>unused</literal> function attribute if the compiler is <command>gcc</command>.
 134 It is used for declaring functions which may never be used.
 135 It avoids possible compiler warnings. See the GNU C documentation for details.
 136 </para>
 137
 138
 139
 140 <!-- ##### MACRO G_GNUC_PURE ##### -->
 141 <para>
 142 Expands to the GNU C <literal>pure</literal> function attribute if the compiler is <command>gcc</command>.
 143 Declaring a function as pure enables better optimization of the function.
 144 A pure function has no effects except its return value and the return
 145 value depends only on the parameters and/or global variables.
 146 See the GNU C documentation for details.
 147 </para>
 148
 149
 150
 151 <!-- ##### MACRO G_GNUC_PRINTF ##### -->
 152 <para>
 153 Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
 154 This is used for declaring functions which take a variable number of
 155 arguments, with the same syntax as <function>printf()</function>.
 156 It allows the compiler to type-check the arguments passed to the function.
 157 See the GNU C documentation for details.
 158 </para>
 159 <informalexample><programlisting>
 160 gint g_snprintf (gchar  *string,
 161                  gulong       n,
 162                  gchar const *format,
 163                  ...) G_GNUC_PRINTF (3, 4);
 164 </programlisting></informalexample>
 165
 166 @format_idx: the index of the argument corresponding to the format string.
 167 (The arguments are numbered from 1).
 168 @arg_idx: the index of the first of the format arguments.
 169
 170
 171 <!-- ##### MACRO G_GNUC_SCANF ##### -->
 172 <para>
 173 Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
 174 This is used for declaring functions which take a variable number of
 175 arguments, with the same syntax as <function>scanf()</function>.
 176 It allows the compiler to type-check the arguments passed to the function.
 177 See the GNU C documentation for details.
 178 </para>
 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_FORMAT ##### -->
 186 <para>
 187 Expands to the GNU C <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>.
 188 This function attribute specifies that a function takes a format
 189 string for a <function>printf()</function>, <function>scanf()</function>,
 190 <function>strftime()</function> or <function>strfmon()</function> style
 191 function and modifies it, so that the result can be passed to a
 192 <function>printf()</function>, <function>scanf()</function>,
 193 <function>strftime()</function> or <function>strfmon()</function> style
 194 function (with the remaining arguments to the format function the same as
 195 they would have been for the unmodified string).
 196 See the GNU C documentation for details.
 197 </para>
 198 <informalexample><programlisting>
 199 gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
 200 </programlisting></informalexample>
 201
 202 @arg_idx: the index of the argument.
 203
 204
 205 <!-- ##### MACRO G_GNUC_FUNCTION ##### -->
 206 <para>
 207 Expands to the GNU C <literal>__FUNCTION__</literal> variable if the
 208 compiler is <command>gcc</command>, or "" if it isn't. The GNU C
 209 <literal>__FUNCTION__</literal> variable contains the name of the
 210 current function. See the GNU C documentation for details.
 211 </para>
 212
 213
 214
 215 <!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
 216 <para>
 217 Expands to the GNU C <literal>__PRETTY_FUNCTION__</literal> variable
 218 if the compiler is <command>gcc</command>, or "" if it isn't.
 219 The GNU C <literal>__PRETTY_FUNCTION__</literal> variable contains the
 220 name of the current function. For a C program this is the same as the
 221 <literal>__FUNCTION__</literal> variable but for C++ it also includes
 222 extra information such as the class and function prototype. See the
 223 GNU C documentation for details.
 224 </para>
 225
 226
 227
 228 <!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
 229 <para>
 230 Expands to the GNU C <literal>no_instrument_function</literal> function
 231 attribute if the compiler is <command>gcc</command>. Functions with this
 232 attribute will not be
 233 instrumented for profiling, when the compiler is called with the
 234 <option>-finstrument-functions</option> option.
 235 See the GNU C documentation for details.
 236 </para>
 237
 238
 239
 240 <!-- ##### MACRO G_LIKELY ##### -->
 241 <para>
 242 Hints the compiler that the expression is likely to evaluate to a true
 243 value. The compiler may use this information for optimizations.
 244 </para>
 245 <informalexample><programlisting>
 246 if (G_LIKELY (random () != 1))
 247   g_print ("not one");
 248 </programlisting></informalexample>
 249
 250 @expr: the expression
 251
 252
 253 <!-- ##### MACRO G_UNLIKELY ##### -->
 254 <para>
 255 Hints the compiler that the expression is unlikely to evaluate to a true
 256 value. The compiler may use this information for optimizations.
 257 </para>
 258 <informalexample><programlisting>
 259 if (G_UNLIKELY (random () == 1))
 260   g_print ("a random one");
 261 </programlisting></informalexample>
 262
 263 @expr: the expression
 264
 265
 266 <!-- ##### MACRO G_STRLOC ##### -->
 267 <para>
 268 Expands to a string identifying the current code position.
 269 </para>
 270
 271
 272
 273 <!-- ##### MACRO G_GINT16_FORMAT ##### -->
 274 <para>
 275 This is the platform dependent conversion specifier for scanning and
 276 printing values of type #gint16. It is a string literal, but doesn't
 277 include the percent-sign, such that you can add precision and length
 278 modifiers between percent-sign and conversion specifier.
 279 </para>
 280
 281 <para>
 282 <informalexample>
 283 <programlisting>
 284 gint16 in;
 285 gint32 out;
 286 sscanf ("42", "%" G_GINT16_FORMAT, &amp;in)
 287 out = in * 1000;
 288 g_print ("%" G_GINT32_FORMAT, out);
 289 </programlisting>
 290 </informalexample>
 291 </para>
 292
 293
 294
 295 <!-- ##### MACRO G_GUINT16_FORMAT ##### -->
 296 <para>
 297 This is the platform dependent conversion specifier for scanning and
 298 printing values of type #guint16. See also #G_GINT16_FORMAT.
 299 </para>
 300
 301
 302
 303 <!-- ##### MACRO G_GINT32_FORMAT ##### -->
 304 <para>
 305 This is the platform dependent conversion specifier for scanning and
 306 printing values of type #gint32. See also #G_GINT16_FORMAT.
 307 </para>
 308
 309
 310
 311 <!-- ##### MACRO G_GUINT32_FORMAT ##### -->
 312 <para>
 313 This is the platform dependent conversion specifier for scanning and
 314 printing values of type #guint32. See also #G_GINT16_FORMAT.
 315 </para>
 316
 317
 318
 319 <!-- ##### MACRO G_GINT64_FORMAT ##### -->
 320 <para>
 321 This is the platform dependent conversion specifier for scanning and
 322 printing values of type #gint64. See also #G_GINT16_FORMAT.
 323 </para>
 324
 325 <note>
 326 <para>
 327 Some platforms do not support scanning and printing 64 bit integers,
 328 even though the types are supported. On such platforms #G_GINT64_FORMAT
 329 is not defined.
 330 </para>
 331 </note>
 332
 333
 334
 335 <!-- ##### MACRO G_GUINT64_FORMAT ##### -->
 336 <para>
 337 This is the platform dependent conversion specifier for scanning and
 338 printing values of type #guint64. 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_GUINT64_FORMAT
 345 is not defined.
 346 </para>
 347 </note>
 348
 349
 350