doc/verify.texi

   1 @c GNU verify module documentation
   2
   3 @c Copyright (C) 2006 Free Software Foundation, Inc.
   4
   5 @c Permission is granted to copy, distribute and/or modify this document
   6 @c under the terms of the GNU Free Documentation License, Version 1.2
   7 @c or any later version published by the Free Software Foundation;
   8 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
   9 @c Texts.  A copy of the license is included in the ``GNU Free
  10 @c Documentation License'' file as part of this distribution.
  11
  12 @node Compile-time Assertions
  13 @section Compile-time Assertions
  14
  15 @cindex assertion
  16 @findex verify
  17 @findex verify_true
  18
  19 The @samp{verify} module supports compile-time tests, as opposed to
  20 the standard @file{assert.h} header which supports only runtime tests.
  21 Since the tests occur at compile-time, they are more reliable, and
  22 they require no runtime overhead.
  23
  24 This module provides a header file @file{verify.h} that defines two
  25 macros: @code{verify (@var{EXPRESSION})} and @code{verify_true
  26 (@var{EXPRESSION})}.  Both accept an integer constant expression
  27 argument and verify that it is nonzero.  If not, a compile-time error
  28 results.
  29
  30 @code{verify (@var{EXPRESSION});} is a declaration; it can occur
  31 outside of functions.  In contrast, @code{verify_true
  32 (@var{EXPRESSION})} is an integer constant expression that always
  33 evaluates to 1; it can be used in macros that expand to
  34 expressions.
  35
  36 @var{EXPRESSION} should be an integer constant expression in the sense
  37 of the C standard.  Its leaf operands should be integer, enumeration,
  38 or character constants; or @code{sizeof} expressions that return
  39 constants; or floating constants that are the immediate operands of
  40 casts.  Outside a @code{sizeof} subexpression, @var{EXPRESSION} should
  41 not contain any assignments, function calls, comma operators, casts to
  42 non-integer types, or subexpressions whose values are outside the
  43 representable ranges for their types.  If @var{EXPRESSION} is not an
  44 integer constant expression, then a compiler might reject a usage like
  45 @samp{verify (@var{EXPRESSION});} even when @var{EXPRESSION} is
  46 nonzero.
  47
  48 Here are some example uses.
  49
  50 @example
  51 #include <verify.h>
  52
  53 #include <limits.h>
  54 #include <time.h>
  55
  56 /* Verify that time_t is an integer type.  */
  57 verify ((time_t) 1.5 == 1);
  58
  59 /* Verify that time_t is at least as wide as int.  */
  60 verify (INT_MIN == (time_t) INT_MIN);
  61 verify (INT_MAX == (time_t) INT_MAX);
  62
  63 /* Verify that time_t is signed.  */
  64 verify ((time_t) -1 < 0);
  65
  66 /* Verify that time_t uses two's complement representation.  */
  67 verify (~ (time_t) -1 == 0);
  68
  69 /* Return the maximum value of the integer type T,
  70    verifying that T is an unsigned integer type.  */
  71 #define MAX_UNSIGNED_VAL_WITH_COMMA(t) \
  72    (verify_true (0 < (T) -1), (T) -1)
  73
  74 /* Same as MAX_UNSIGNED_VAL_WITH_COMMA,
  75    but expand to an integer constant expression,
  76    which cannot contain a comma operator.
  77    The cast to (T) is outside the conditional expression
  78    so that the result is of type T
  79    even when T is narrower than unsigned int.  */
  80 #define MAX_UNSIGNED_VAL(t) ((T) \
  81    ((T) (verify_true (0 < (T) -1) ? -1 : 0))
  82 @end example