diff options
Diffstat (limited to 'gnulib/doc/verify.texi')
m--------- | gnulib | 0 | ||||
-rw-r--r-- | gnulib/doc/verify.texi | 90 |
2 files changed, 90 insertions, 0 deletions
diff --git a/gnulib b/gnulib deleted file mode 160000 -Subproject 443bc5ffcf7429e557f4a371b0661abe98ddbc1 diff --git a/gnulib/doc/verify.texi b/gnulib/doc/verify.texi new file mode 100644 index 0000000..5fa8b14 --- /dev/null +++ b/gnulib/doc/verify.texi @@ -0,0 +1,90 @@ +@c GNU verify module documentation + +@c Copyright (C) 2006, 2009-2011 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.3 +@c or any later version published by the Free Software Foundation; +@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +@node Compile-time Assertions +@section Compile-time Assertions + +@cindex assertion +@findex verify +@findex verify_expr + +The @samp{verify} module supports compile-time tests, as opposed to +the standard @code{assert} macro which supports only runtime tests. +Since the tests occur at compile-time, they are more reliable, and +they require no runtime overhead. + +This module provides a header file @file{verify.h} that defines two +macros: @code{verify (@var{V})} and @code{verify_expr +(@var{V}, @var{EXPR})}. Both accept an integer constant expression +argument @var{V} and verify that it is nonzero. If not, a compile-time error +results. + +@code{verify (@var{V});} is a declaration; it can occur outside of +functions. In contrast, @code{verify_expr (@var{V}, @var{EXPR})} is +an expression that returns the value of @var{EXPR}; it can be used in +macros that expand to expressions. If @var{EXPR} is an integer +constant expression, then @code{verify_expr (@var{V}, @var{EXPR})} is +also an integer constant expression. Although @var{EXPR} and +@code{verify_expr (@var{V}, @var{EXPR})}@ are guaranteed to have the +same side effects and value and type (after integer promotion), they +need not have the same type if @var{EXPR}'s type is an integer that is +narrower than @code{int} or @code{unsigned int}. + +@var{V} should be an integer constant expression in the sense +of the C standard. Its leaf operands should be integer, enumeration, +or character constants; or @code{sizeof} expressions that return +constants; or floating constants that are the immediate operands of +casts. Outside a @code{sizeof} subexpression, @var{V} should +not contain any assignments, function calls, comma operators, casts to +non-integer types, or subexpressions whose values are outside the +representable ranges for their types. If @var{V} is not an +integer constant expression, then a compiler might reject a usage like +@samp{verify (@var{V});} even when @var{V} is +nonzero. + +Although the standard @code{assert} macro is a runtime test, draft C1X +specifies a builtin @code{_Static_assert (@var{V}, +@var{STRING-LITERAL})}, its @file{assert.h} header has a similar macro +named @code{static_assert}, and draft C++0X has a similar +@code{static_assert} builtin. These draft builtins and macros differ +from @code{verify} in two major ways. First, they can also be used +within a @code{struct} or @code{union} specifier, in place of an +ordinary member declaration. Second, they require the programmer to +specify a compile-time diagnostic as a string literal. + +Here are some example uses of @code{verify} and @code{verify_expr}. + +@example +#include <verify.h> + +#include <limits.h> +#include <time.h> + +/* Verify that time_t is an integer type. */ +verify ((time_t) 1.5 == 1); + +/* Verify that time_t is no smaller than int. */ +verify (sizeof (int) <= sizeof (time_t)); + +/* Verify that time_t is signed. */ +verify ((time_t) -1 < 0); + +/* Verify that time_t uses two's complement representation. */ +verify (~ (time_t) -1 == 0); + +/* Return the maximum value of the integer type T, + verifying that T is an unsigned integer type. + The cast to (T) is outside the call to verify_expr + so that the result is of type T + even when T is narrower than unsigned int. */ +#define MAX_UNSIGNED_VAL(t) \ + ((T) verify_expr (0 < (T) -1, -1)) +@end example |