1 @c GNU verify module documentation
3 @c Copyright (C) 2006, 2009-2011 Free Software Foundation, Inc.
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.
12 @node Compile-time Assertions
13 @section Compile-time Assertions
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.
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
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
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
48 Although the standard @code{assert} macro is a runtime test, draft C1X
49 specifies a builtin @code{_Static_assert (@var{EXPRESSION},
50 @var{STRING-LITERAL})}, its @file{assert.h} header has a similar macro
51 named @code{static_assert}, and draft C++0X has a similar
52 @code{static_assert} builtin. These draft builtins and macros differ
53 from @code{verify} in two major ways. First, they can also be used
54 within a @code{struct} or @code{union} specifier, in place of an
55 ordinary member declaration. Second, they require the programmer to
56 specify a compile-time diagnostic as a string literal.
58 Here are some example uses of @code{verify} and @code{verify_true}.
66 /* Verify that time_t is an integer type. */
67 verify ((time_t) 1.5 == 1);
69 /* Verify that time_t is no smaller than int. */
70 verify (sizeof (int) <= sizeof (time_t));
72 /* Verify that time_t is signed. */
73 verify ((time_t) -1 < 0);
75 /* Verify that time_t uses two's complement representation. */
76 verify (~ (time_t) -1 == 0);
78 /* Return the maximum value of the integer type T,
79 verifying that T is an unsigned integer type. */
80 #define MAX_UNSIGNED_VAL_WITH_COMMA(t) \
81 (verify_true (0 < (T) -1), (T) -1)
83 /* Same as MAX_UNSIGNED_VAL_WITH_COMMA,
84 but expand to an integer constant expression,
85 which cannot contain a comma operator.
86 The cast to (T) is outside the conditional expression
87 so that the result is of type T
88 even when T is narrower than unsigned int. */
89 #define MAX_UNSIGNED_VAL(t) ((T) \
90 ((T) (verify_true (0 < (T) -1) ? -1 : 0))