docs/reference/glib/tmpl/macros_misc.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Miscellaneous Macros
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 specialised 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 'extern "C"' around the header.
  46 </para>
  47
  48
  49
  50 <!-- ##### MACRO G_END_DECLS ##### -->
  51 <para>
  52 Used (along with #G_BEGIN_DECLS) to bracket header files. If the
  53 compiler in use is a C++ compiler, adds 'extern "C"' around the header.
  54 </para>
  55
  56
  57
  58 <!-- ##### MACRO G_N_ELEMENTS ##### -->
  59 <para>
  60 Determines the number of elements in an array. The array must be
  61 declared so the compiler knows its size at compile-time; this
  62 macro will not work on an array allocated on the heap, only static
  63 arrays or arrays on the stack.
  64 </para>
  65
  66 @arr: the array
  67
  68
  69 <!-- ##### MACRO G_VA_COPY ##### -->
  70 <para>
  71 Portable way to copy <type>va_list</type> variables.
  72 </para>
  73
  74 @ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
  75 @ap2: a <type>va_list</type>.
  76
  77
  78 <!-- ##### MACRO G_STRINGIFY ##### -->
  79 <para>
  80
  81 </para>
  82
  83 @macro_or_string:
  84
  85
  86 <!-- ##### MACRO G_GNUC_EXTENSION ##### -->
  87 <para>
  88 Expands to "__extension__" when GNU C is used as the compiler.
  89 This simply tells GNU C not to warn about the following non-standard code
  90 when compiling with the -pedantic option.
  91 </para>
  92
  93
  94
  95 <!-- ##### MACRO G_GNUC_CONST ##### -->
  96 <para>
  97 Expands to the GNU C const function attribute if the compiler is GNU C.
  98 This enables optimization of the function.
  99 See the GNU C documentation for details.
 100 </para>
 101
 102
 103
 104 <!-- ##### MACRO G_GNUC_NORETURN ##### -->
 105 <para>
 106 Expands to the GNU C noreturn function attribute if the compiler is GNU C.
 107 It is used for declaring functions which never return.
 108 It enables optimization of the function, and avoids possible compiler
 109 warnings. See the GNU C documentation for details.
 110 </para>
 111
 112
 113
 114 <!-- ##### MACRO G_GNUC_UNUSED ##### -->
 115 <para>
 116 Expands to the GNU C unused function attribute if the compiler is GNU C.
 117 It is used for declaring functions which may never be used.
 118 It avoids possible compiler warnings. See the GNU C documentation for details.
 119 </para>
 120
 121
 122
 123 <!-- ##### MACRO G_GNUC_PURE ##### -->
 124 <para>
 125
 126 </para>
 127
 128
 129
 130 <!-- ##### MACRO G_GNUC_PRINTF ##### -->
 131 <para>
 132 Expands to the GNU C format function attribute if the compiler is GNU C.
 133 This is used for declaring functions which take a variable number of
 134 arguments, with the same syntax as <function>printf()</function>.
 135 It allows the compiler to type-check the arguments passed to the function.
 136 See the GNU C documentation for details.
 137 </para>
 138
 139 @format_idx: the index of the argument corresponding to the format string.
 140 (The arguments are numbered from 1).
 141 @arg_idx: the index of the first of the format arguments.
 142
 143
 144 <!-- ##### MACRO G_GNUC_SCANF ##### -->
 145 <para>
 146 Expands to the GNU C format function attribute if the compiler is GNU C.
 147 This is used for declaring functions which take a variable number of
 148 arguments, with the same syntax as <function>scanf()</function>.
 149 It allows the compiler to type-check the arguments passed to the function.
 150 See the GNU C documentation for details.
 151 </para>
 152
 153 @format_idx: the index of the argument corresponding to the format string.
 154 (The arguments are numbered from 1).
 155 @arg_idx: the index of the first of the format arguments.
 156
 157
 158 <!-- ##### MACRO G_GNUC_FORMAT ##### -->
 159 <para>
 160 Expands to the GNU C format_arg function attribute if the compiler is GNU C.
 161 This is used for declaring functions which take a variable number of
 162 parameters, like <function>printf()</function> and
 163 <function>scanf()</function>. See the GNU C documentation for details.
 164
 165 FIXME: I can't find this in my GNU C documentation. Take out?
 166 </para>
 167
 168 @arg_idx: the index of the argument.
 169
 170
 171 <!-- ##### MACRO G_GNUC_FUNCTION ##### -->
 172 <para>
 173 Expands to the GNU C __FUNCTION__ variable if the compiler is GNU C,
 174 or "" if it isn't.
 175 The GNU C __FUNCTION__ variable contains the name of the current function.
 176 See the GNU C documentation for details.
 177 </para>
 178
 179
 180
 181 <!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
 182 <para>
 183 Expands to the GNU C __PRETTY_FUNCTION__ variable if the compiler is GNU C,
 184 or "" if it isn't.
 185 The GNU C __PRETTY_FUNCTION__ variable contains the name of the current
 186 function. For a C program this is the same as the __FUNCTION__ variable
 187 but for C++ it also includes extra information such as the class
 188 and function prototype. See the GNU C documentation for details.
 189 </para>
 190
 191
 192
 193 <!-- ##### MACRO G_STRLOC ##### -->
 194 <para>
 195
 196 </para>
 197
 198
 199
 200 <!-- ##### MACRO G_GINT16_FORMAT ##### -->
 201 <para>
 202 This is the platform dependent conversion specifier for scanning and
 203 printing values of type #gint16. It is a string literal, but doesn't
 204 include the percent-sign, such that you can add precision and length
 205 modifiers between percent-sign and conversion specifier.
 206 </para>
 207
 208 <para>
 209 <informalexample>
 210 <programlisting>
 211 gint16 in;
 212 gint32 out;
 213 sscanf ("42", "%" G_GINT16_FORMAT, &amp;in)
 214 out = in * 1000;
 215 g_print ("%" G_GINT32_FORMAT, out);
 216 </programlisting>
 217 </informalexample>
 218 </para>
 219
 220
 221
 222 <!-- ##### MACRO G_GUINT16_FORMAT ##### -->
 223 <para>
 224 This is the platform dependent conversion specifier for scanning and
 225 printing values of type #guint16. See also #G_GINT16_FORMAT.
 226 </para>
 227
 228
 229
 230 <!-- ##### MACRO G_GINT32_FORMAT ##### -->
 231 <para>
 232 This is the platform dependent conversion specifier for scanning and
 233 printing values of type #gint32. See also #G_GINT16_FORMAT.
 234 </para>
 235
 236
 237
 238 <!-- ##### MACRO G_GUINT32_FORMAT ##### -->
 239 <para>
 240 This is the platform dependent conversion specifier for scanning and
 241 printing values of type #guint32. See also #G_GINT16_FORMAT.
 242 </para>
 243
 244
 245
 246 <!-- ##### MACRO G_GINT64_FORMAT ##### -->
 247 <para>
 248 This is the platform dependent conversion specifier for scanning and
 249 printing values of type #gint64. See also #G_GINT16_FORMAT.
 250 </para>
 251
 252 <note>
 253 <para>
 254 Some platforms do not support scanning and printing 64 bit integers,
 255 even though the types are supported. On such platforms G_GINT64_FORMAT
 256 is not defined.
 257 </para>
 258 </note>
 259
 260
 261
 262 <!-- ##### MACRO G_GUINT64_FORMAT ##### -->
 263 <para>
 264 This is the platform dependent conversion specifier for scanning and
 265 printing values of type #guint64. See also #G_GINT16_FORMAT.
 266 </para>
 267
 268 <note>
 269 <para>
 270 Some platforms do not support scanning and printing 64 bit integers,
 271 even though the types are supported. On such platforms G_GUINT64_FORMAT
 272 is not defined.
 273 </para>
 274 </note>
 275
 276
 277