summaryrefslogtreecommitdiff
path: root/gnulib/doc/verify.texi
diff options
context:
space:
mode:
Diffstat (limited to 'gnulib/doc/verify.texi')
m---------gnulib0
-rw-r--r--gnulib/doc/verify.texi90
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