doc/verify.texi

   1 @c GNU verify module documentation
   2
   3 @c Copyright (C) 2006, 2009-2013 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.3
   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_expr
  18
  19 The @samp{verify} module supports compile-time tests, as opposed to
  20 the standard @code{assert} macro 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{V})} and @code{verify_expr
  26 (@var{V}, @var{EXPR})}.  Both accept an integer constant expression
  27 argument @var{V} and verify that it is nonzero.  If not, a compile-time error
  28 results.
  29
  30 @code{verify (@var{V});} is a declaration; it can occur outside of
  31 functions.  In contrast, @code{verify_expr (@var{V}, @var{EXPR})} is
  32 an expression that returns the value of @var{EXPR}; it can be used in
  33 macros that expand to expressions.  If @var{EXPR} is an integer
  34 constant expression, then @code{verify_expr (@var{V}, @var{EXPR})} is
  35 also an integer constant expression.  Although @var{EXPR} and
  36 @code{verify_expr (@var{V}, @var{EXPR})}@ are guaranteed to have the
  37 same side effects and value and type (after integer promotion), they
  38 need not have the same type if @var{EXPR}'s type is an integer that is
  39 narrower than @code{int} or @code{unsigned int}.
  40
  41 @var{V} should be an integer constant expression in the sense
  42 of the C standard.  Its leaf operands should be integer, enumeration,
  43 or character constants; or @code{sizeof} expressions that return
  44 constants; or floating constants that are the immediate operands of
  45 casts.  Outside a @code{sizeof} subexpression, @var{V} should
  46 not contain any assignments, function calls, comma operators, casts to
  47 non-integer types, or subexpressions whose values are outside the
  48 representable ranges for their types.  If @var{V} is not an
  49 integer constant expression, then a compiler might reject a usage like
  50 @samp{verify (@var{V});} even when @var{V} is
  51 nonzero.
  52
  53 Although the standard @code{assert} macro is a runtime test, C11
  54 specifies a builtin @code{_Static_assert (@var{V},
  55 @var{STRING-LITERAL})}, its @file{assert.h} header has a similar macro
  56 named @code{static_assert}, and C++11 has a similar
  57 @code{static_assert} builtin.  These builtins and macros differ
  58 from @code{verify} in two major ways.  First, they can also be used
  59 within a @code{struct} or @code{union} specifier, in place of an
  60 ordinary member declaration.  Second, they require the programmer to
  61 specify a compile-time diagnostic as a string literal.
  62
  63 Here are some example uses of @code{verify} and @code{verify_expr}.
  64
  65 @example
  66 #include <verify.h>
  67
  68 #include <limits.h>
  69 #include <time.h>
  70
  71 /* Verify that time_t is an integer type.  */
  72 verify ((time_t) 1.5 == 1);
  73
  74 /* Verify that time_t is no smaller than int.  */
  75 verify (sizeof (int) <= sizeof (time_t));
  76
  77 /* Verify that time_t is signed.  */
  78 verify ((time_t) -1 < 0);
  79
  80 /* Verify that time_t uses two's complement representation.  */
  81 verify (~ (time_t) -1 == 0);
  82
  83 /* Return the maximum value of the integer type T,
  84    verifying that T is an unsigned integer type.
  85    The cast to (T) is outside the call to verify_expr
  86    so that the result is of type T
  87    even when T is narrower than unsigned int.  */
  88 #define MAX_UNSIGNED_VAL(t) \
  89    ((T) verify_expr (0 < (T) -1, -1))
  90 @end example