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