chiark - git - mdw - mLib/blob - utils/macros.h

   1 /* -*-c-*-
   2  *
   3  * Handy macros
   4  *
   5  * (c) 2003 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of the mLib utilities library.
  11  *
  12  * mLib is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU Library General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * mLib is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with mLib; if not, write to the Free
  24  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25  * MA 02111-1307, USA.
  26  */
  27
  28 #ifndef MLIB_MACROS_H
  29 #define MLIB_MACROS_H
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35 /*----- Header files ------------------------------------------------------*/
  36
  37 #include <assert.h>
  38
  39 #ifndef MLIB_COMPILER_H
  40 #  include "compiler.h"
  41 #endif
  42
  43 /*----- Miscellaneous utility macros --------------------------------------*/
  44
  45 /* --- @N@ --- *
  46  *
  47  * Arguments:   @type v[]@ = an actual array, not a pointer
  48  *
  49  * Returns:     The number of elements in @v@.
  50  */
  51
  52 #define N(v) (sizeof(v)/sizeof(*(v)))
  53
  54 /* --- @STR@ --- *
  55  *
  56  * Arguments:   @x@ = some tokens
  57  *
  58  * Returns:     A string literal containing the macro-expanded text of @x@.
  59  */
  60
  61 #define MLIB__STR(x) #x
  62 #define STR(x) MLIB__STR(x)
  63
  64 /* --- @GLUE@ --- *
  65  *
  66  * Arguments:   @x, y@ = two sequences of tokens
  67  *
  68  * Returns:     A single token formed by gluing together the macro-expansions
  69  *              of @x@ and @y@.
  70  */
  71
  72 #define MLIB__GLUE(x, y) x##y
  73 #define GLUE(x, y) MLIB__GLUE(x, y)
  74
  75 /* --- @STATIC_ASSERT@ --- *
  76  *
  77  * Arguments:   @int cond@ = a condition
  78  *              @msg@ = a string literal message
  79  *
  80  * Returns:     ---
  81  *
  82  * Use:         Fail at compile time unless @cond@ is nonzero.  The failure
  83  *              might report @msg@.
  84  */
  85
  86 #ifdef static_assert
  87 #  define STATIC_ASSERT(cond, msg) static_assert(!!(cond), msg)
  88 #else
  89 #  define STATIC_ASSERT(cond, msg)                                      \
  90         IGNORABLE extern char static_assert_failed[2*!!(cond) - 1]
  91 #endif
  92
  93 /* --- @COMMA@ --- *
  94  *
  95  * Arguments:   ---
  96  *
  97  * Returns:     A `%|,|%' token, which can be usefully passed to macros to
  98  *              avoid argument splitting.
  99  */
 100
 101 #define COMMA ,
 102
 103 /*----- String and character hacks ----------------------------------------*/
 104
 105 /* --- @IS...@ --- *
 106  *
 107  * Arguments:   @int ch@ = a character code, but not @EOF@
 108  *
 109  * Returns:     Nonzero if @ch@ is in the relevant @<ctype.h>@ category.
 110  *
 111  * Use:         Classifies characters, but safely even if characters are
 112  *              signed.
 113  *
 114  *              There is a macro for each of the @<ctype.h>@ @is...@
 115  *              functions.
 116  */
 117
 118 #define CTYPE_HACK(func, ch) (func((unsigned char)(ch)))
 119
 120 #define ISALNUM(ch) CTYPE_HACK(isalnum, ch)
 121 #define ISALPHA(ch) CTYPE_HACK(isalpha, ch)
 122 #define ISASCII(ch) CTYPE_HACK(isascii, ch)
 123 #define ISBLANK(ch) CTYPE_HACK(isblank, ch)
 124 #define ISCNTRL(ch) CTYPE_HACK(iscntrl, ch)
 125 #define ISDIGIT(ch) CTYPE_HACK(isdigit, ch)
 126 #define ISGRAPH(ch) CTYPE_HACK(isgraph, ch)
 127 #define ISLOWER(ch) CTYPE_HACK(islower, ch)
 128 #define ISPRINT(ch) CTYPE_HACK(isprint, ch)
 129 #define ISPUNCT(ch) CTYPE_HACK(ispunct, ch)
 130 #define ISSPACE(ch) CTYPE_HACK(isspace, ch)
 131 #define ISUPPER(ch) CTYPE_HACK(isupper, ch)
 132 #define ISXDIGIT(ch) CTYPE_HACK(isxdigit, ch)
 133
 134 /* --- @TO...@ --- *
 135  *
 136  * Arguments:   @int ch@ = a character code, but not @EOF@
 137  *
 138  * Returns:     The converted character code.
 139  *
 140  * Use:         Converts characters, but safely even if characters are
 141  *              signed.
 142  *
 143  *              There is a macro for each of the @<ctype.h>@ @to...@
 144  *              functions.
 145  */
 146
 147 #define TOASCII(ch) CTYPE_HACK(toascii, ch)
 148 #define TOLOWER(ch) CTYPE_HACK(tolower, ch)
 149 #define TOUPPER(ch) CTYPE_HACK(toupper, ch)
 150
 151 /* --- @MEMCMP@, @STRCMP@, @STRNCMP@ --- *
 152  *
 153  * Arguments:   @const type *x, *y@ = pointers to strings
 154  *              @op@ = a relational operator symbol
 155  *              @size_t n@ = length of the strings
 156  *
 157  * Returns:     Nonzero if the relationship between the strings satisfies the
 158  *              operator @op@, otherwise zero.
 159  *
 160  * Use:         These macros mitigate the author's frequent error of failing
 161  *              to compare the result of the underlying standard functions
 162  *              against zero, effectively reversing the sense of an intended
 163  *              test for equality.
 164  */
 165
 166 #define MEMCMP(x, op, y, n) (memcmp((x), (y), (n)) op 0)
 167 #define STRCMP(x, op, y) (strcmp((x), (y)) op 0)
 168 #define STRNCMP(x, op, y, n) (strncmp((x), (y), (n)) op 0)
 169
 170 /*----- Compiler-specific definitions -------------------------------------*/
 171
 172 /* The descriptions of these are given below, with the fallback
 173  * definitions.
 174  */
 175
 176 #if GCC_VERSION_P(2, 5) || CLANG_VERSION_P(3, 3)
 177 #  define NORETURN __attribute__((__noreturn__))
 178 #  define PRINTF_LIKE(fix, aix) __attribute__((__format__(printf, fix, aix)))
 179 #  define SCANF_LIKE(fix, aix) __attribute__((__format__(scanf, fix, aix)))
 180 #  define IGNORABLE __attribute__((__unused__))
 181 #endif
 182
 183 #if GCC_VERSION_P(3, 4) || CLANG_VERSION_P(3, 3)
 184 #  define MUST_CHECK __attribute__((__warn_unused_result__))
 185 #endif
 186
 187 #if GCC_VERSION_P(4, 5) || CLANG_VERSION_P(3, 3)
 188 #  define DEPRECATED(msg) __attribute__((__deprecated__(msg)))
 189 #elif GCC_VERSION_P(3, 1)
 190 #  define DEPRECATED(msg) __attribute__((__deprecated__))
 191 #endif
 192
 193 #if GCC_VERSION_P(4, 0) || CLANG_VERSION_P(3, 3)
 194 #  define EXECL_LIKE(ntrail) __attribute__((__sentinel__(ntrail)))
 195 #endif
 196
 197 #if GCC_VERSION_P(2, 7) || CLANG_VERSION_P(0, 0)
 198 #  define LAUNDER(x)                                                    \
 199         ({ __typeof__(x) _y; __asm__("" : "=g"(_y) : "0"(x)); _y; })
 200 #  define RELAX do __asm__ __volatile__("" ::: "memory"); while (0)
 201 #endif
 202
 203 #if CLANG_VERSION_P(3, 3)
 204
 205 #  define MLIB__PRAGMA_HACK(x) _Pragma(#x)
 206 #  define MLIB__MUFFLE_WARNINGS(warns, body)                            \
 207         _Pragma("clang diagnostic push")                                \
 208         warns                                                           \
 209         body                                                            \
 210         _Pragma("clang diagnostic pop")
 211 #  define CLANG_WARNING(warn)                                           \
 212         MLIB__PRAGMA_HACK(clang diagnostic ignored warn)
 213 #  define MUFFLE_WARNINGS_DECL(warns, body)                             \
 214         MLIB__MUFFLE_WARNINGS(warns, body)
 215 #  define MUFFLE_WARNINGS_EXPR(warns, body)                             \
 216         __extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
 217 #  define MUFFLE_WARNINGS_STMT(warns, body)                             \
 218         do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)
 219
 220 #endif
 221
 222 #if GCC_VERSION_P(4, 6)
 223
 224    /* --- Diagnostic suppression in GCC: a tale of woe --- *
 225     *
 226     * This is extremely unpleasant, largely as a result of bugs in the GCC
 227     * preprocessor's handling of @_Pragma@.  The fundamental problem is
 228     * that it's the preprocessor, and not the compiler proper, which
 229     * detects @_Pragma@, emitting @#pragma@ lines into its output; and it
 230     * does it during macro expansion, even if the macro is being expanded
 231     * during argument collection.  Since arguments are expanded before
 232     * replacing the macro's invocation with its body, a pragma in an
 233     * argument will be emitted %%\emph{before}%% any pragmata in the body,
 234     * even if they appear before the argument in the body -- and even if
 235     * the argument doesn't actually appear anywhere at all in the body.
 236     *
 237     * Another, rather less significant, problem is that @_Pragma@'s
 238     * argument is a single string literal, recognized in translation phase
 239     * 4, before string-literal concatenation in phase 6, so we must build
 240     * pragma bodies as token lists and then stringify them.
 241     *
 242     * As a result, we need some subterfuge here.  The @MLIB__PRAGMA_HACK@
 243     * macro issues a @_Pragma@ on its argument token list, which it
 244     * stringifies; this deals with the second problem.  The first is
 245     * trickier: we must delay expansion of @MLIB__PRAGMA_HACK@ from the
 246     * argument collection phase to the body rescanning phase, and we do
 247     * this by splitting the invocations between @GCC_WARNING@ macro calls:
 248     * the name is left hanging from the previous call (or from
 249     * @MLIB__MUFFLE_WARNINGS@, in the first case) and the body is supplied
 250     * by @GCC_WARNING@, which also supplies the next @MLIB__PRAGMA_HACK@.
 251     * The remaining problem is to make sure we can dispose of the final
 252     * trailing @MLIB__PRAGMA_HACK@ harmlessly, which we do by introducing
 253     * an extra argument @emitp@, which may be either @t@ or @nil@; this
 254     * dispatches to an appropriate helper macro by means of token-pasting.
 255     *
 256     * I'm so sorry.
 257     */
 258
 259 #  define MLIB__PRAGMA_HACK_t(x) _Pragma(#x)
 260 #  define MLIB__PRAGMA_HACK_nil(x)
 261 #  define MLIB__PRAGMA_HACK(emitp, x) MLIB__PRAGMA_HACK_##emitp(x)
 262 #  define MLIB__MUFFLE_WARNINGS(warns, body)                            \
 263         _Pragma("GCC diagnostic push") MLIB__PRAGMA_HACK                \
 264         warns                                                           \
 265         (nil, nil)                                                      \
 266         body                                                            \
 267         _Pragma("GCC diagnostic pop")
 268 #  define GCC_WARNING(warn)                                             \
 269         (t, GCC diagnostic ignored warn) MLIB__PRAGMA_HACK
 270 #  define MUFFLE_WARNINGS_DECL(warns, body)                             \
 271         MLIB__MUFFLE_WARNINGS(warns, body)
 272 #  define MUFFLE_WARNINGS_EXPR(warns, body)                             \
 273         __extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
 274 #  define MUFFLE_WARNINGS_STMT(warns, body)                             \
 275         do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)
 276 #endif
 277
 278 /* --- Fallback definitions, mostly trivial --- */
 279
 280 /* --- @DISCARD@ --- *
 281  *
 282  * Arguments:   @x@ = a function call
 283  *
 284  * Returns:     ---
 285  *
 286  * Use:         Explicitly discard the result of @x@.  This counteracts a
 287  *              @MUST_CHECK@ attribute on the called function.
 288  */
 289
 290 #ifndef DISCARD
 291 #  define DISCARD(x) do if (x); while (0)
 292 #endif
 293
 294 /* --- @IGNORE@ --- *
 295  *
 296  * Arguments:   @x@ = any expression
 297  *
 298  * Returns:     ---
 299  *
 300  * Use:         Ignore the value of @x@, overriding compiler warnings.
 301  */
 302
 303 #ifndef IGNORE
 304 #  define IGNORE(x) ((void)(x))
 305 #endif
 306
 307 /* --- @LAUNDER@ --- *
 308  *
 309  * Arguments:   @x@ = some integer expression
 310  *
 311  * Returns:     @x@.
 312  *
 313  * Use:         Causes a compiler to know nothing about the value of @x@,
 314  *              even if it looks obvious, e.g., it's a constant.
 315  */
 316
 317 #ifndef LAUNDER
 318 #  define LAUNDER(x) (x)
 319 #endif
 320
 321 /* --- @RELAX@ --- *
 322  *
 323  * Arguments:   ---
 324  *
 325  * Returns:     ---
 326  *
 327  * Use:         Does nothing, but the compiler doesn't know that.
 328  */
 329
 330 #ifndef RELAX
 331 #  define RELAX
 332 #endif
 333
 334 /* --- @DEPRECATED@, @NORETURN@, @IGNORABLE@, @MUST_CHECK@ --- *
 335  *
 336  * Use:         These are (mostly) function attributes; write them among the
 337  *              declaration specifiers for a function definition or
 338  *              declaration.  These may not do anything, but the intended
 339  *              behaviour is as follows.
 340  *
 341  *                * @DEPRECATED(msg)@ -- report a warning, quoting the string
 342  *                  literal @msg@, if the function is called.
 343  *
 344  *                * @NORETURN@ -- promise that the function doesn't return to
 345  *                  its caller: either it kills the process, or it performs
 346  *                  some nonlocal transfer.
 347  *
 348  *                * @IGNORABLE@ -- the item (which might be data rather than
 349  *                  a function) might not be referred to, but that's OK:
 350  *                  don't warn about it.
 351  *
 352  *                @ @MUST_CHECK@ -- warn if the return value of a function is
 353  *                  ignored.  Use @DISCARD@ if you really don't care.
 354  */
 355
 356 #ifndef DEPRECATED
 357 #  define DEPRECATED(msg)
 358 #endif
 359
 360 #ifndef NORETURN
 361 #  define NORETURN
 362 #endif
 363
 364 #ifndef IGNORABLE
 365 #  define IGNORABLE
 366 #endif
 367
 368 #ifndef MUST_CHECK
 369 #  define MUST_CHECK
 370 #endif
 371
 372 /* --- @PRINTF_LIKE@, @SCANF_LIKE@, @EXECL_LIKE@ --- *
 373  *
 374  * Arguments:   @int fmtix@ = format string argument index (starting from 1)
 375  *              @int argix@ = variable format argument tail index (starting
 376  *                      from 1)
 377  *              @int ntrail@ = number of arguments following terminator
 378  *
 379  * Use:         These are function attributes.  Again, they might not do
 380  *              anything at all.  By intention, they give the compiler
 381  *              information about a variadic function's arguments, so that it
 382  *              can warn about misuse.
 383  *
 384  *                * @PRINTF_LIKE@ -- the function takes a @printf@-style
 385  *                  format string as argument @fmtix@ and an argument tail
 386  *                  (which may be empty) beginning with argument @argix@.
 387  *
 388  *                * @SCANF_LIKE@ -- the function takes a @scanf@-style
 389  *                  format string as argument @fmtix@ and an argument tail
 390  *                  (which may be empty) beginning with argument @argix@.
 391  *
 392  *                * @EXECL_LIKE@ -- the function takes a sequence of pointer
 393  *                  arguments terminated by a null pointer, followed by
 394  *                  @ntrail@ further arguments.
 395  */
 396
 397 #ifndef PRINTF_LIKE
 398 #  define PRINF_LIKE(fmtix, argix)
 399 #endif
 400
 401 #ifndef SCANF_LIKE
 402 #  define SCANF_LIKE(fmtix, argix)
 403 #endif
 404
 405 #ifndef EXECL_LIKE
 406 #  define EXECL_LIKE(ntrail)
 407 #endif
 408
 409 /* --- @MUFFLE_WARNINGS_...@ --- *
 410  *
 411  * Arguments:   @warns@ = a sequence of @..._WARNING@ calls (see below)
 412  *              @body@ = some program text
 413  *
 414  * Use:         Muffle specific warnings within the program text.
 415  *
 416  *              For @MUFFLE_WARNINGS_DECL@, the program text is a
 417  *              declaration; for @MUFFLE_WARNINGS_EXPR@, it is an expression,
 418  *              and for @MUFFLE_WARNINGS_STMT@, it is a statement.
 419  *
 420  *              The warnings to be muffled are given as a list of
 421  *              @..._WARNING@ macros, with no separators.  The list can
 422  *              list warnings from multiple different compilers: entries for
 423  *              irrelevant compilers will be ignored.
 424  */
 425
 426 #ifndef MUFFLE_WARNINGS_DECL
 427 #  define MUFFLE_WARNINGS_DECL(warns, body) body
 428 #endif
 429
 430 #ifndef MUFFLE_WARNINGS_EXPR
 431 #  define MUFFLE_WARNINGS_EXPR(warns, body) (body)
 432 #endif
 433
 434 #ifndef MUFFLE_WARNINGS_STMT
 435 #  define MUFFLE_WARNINGS_STMT(warns, body) do { body } while (0)
 436 #endif
 437
 438 /* --- @GCC_WARNING@ --- *
 439  *
 440  * Arguments:   @warn@ = a string literal naming a warning, with `%|-W...|%'
 441  *                      prefix
 442  *
 443  * Use:         Names a GCC warning: use within @MUFFLE_WARNINGS_...@.
 444  *
 445  *              Note that GCC's warning suppression is very buggy.
 446  */
 447
 448 #ifndef GCC_WARNING
 449 #  define GCC_WARNING(warn)
 450 #endif
 451
 452 /* --- @CLANG_WARNING@ --- *
 453  *
 454  * Arguments:   @warn@ = a string literal naming a warning, with `%|-W...|%'
 455  *                      prefix
 456  *
 457  * Use:         Names a Clang warning: use within @MUFFLE_WARNINGS_...@.
 458  */
 459
 460 #ifndef CLANG_WARNING
 461 #  define CLANG_WARNING(warn)
 462 #endif
 463
 464 /*----- That's all, folks -------------------------------------------------*/
 465
 466 #ifdef __cplusplus
 467   }
 468 #endif
 469
 470 #endif