From aa93a59f7a386221797b809f18ee670edfbaff02 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Tue, 17 May 2011 13:07:28 -0700 Subject: [PATCH] verify: add doc to gnulib manual and fix example * doc/gnulib.texi (Compile-time Assertions): New node, for 'verify'. * doc/verify.texi (Compile-time Assertions): Update 'assert' doc. (Compile-time Assertions): Fix example so it can't overflow. --- ChangeLog | 7 +++++++ doc/gnulib.texi | 3 +++ doc/verify.texi | 19 ++++++++++++++----- 3 files changed, 24 insertions(+), 5 deletions(-) diff --git a/ChangeLog b/ChangeLog index 295a71d7d6..73d186b3ce 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2011-05-17 Paul Eggert + + verify: add doc to gnulib manual and fix example + * doc/gnulib.texi (Compile-time Assertions): New node, for 'verify'. + * doc/verify.texi (Compile-time Assertions): Update 'assert' doc. + (Compile-time Assertions): Fix example so it can't overflow. + 2011-05-17 Jim Meyering warnings.m4: don't usurp save_CPPFLAGS variable name diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 309f3767d7..d6e43d8ed8 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -6496,6 +6496,7 @@ This list of functions is sorted according to the header that declares them. * alloca:: * alloca-opt:: * Safe Allocation Macros:: +* Compile-time Assertions:: * String Functions in C Locale:: * Quoting:: * error and progname:: @@ -6524,6 +6525,8 @@ This list of functions is sorted according to the header that declares them. @include safe-alloc.texi +@include verify.texi + @node String Functions in C Locale @section Character and String Functions in C Locale diff --git a/doc/verify.texi b/doc/verify.texi index 86ab8fe44d..f95279d692 100644 --- a/doc/verify.texi +++ b/doc/verify.texi @@ -17,7 +17,7 @@ @findex verify_true The @samp{verify} module supports compile-time tests, as opposed to -the standard @file{assert.h} header which supports only runtime tests. +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. @@ -45,7 +45,17 @@ integer constant expression, then a compiler might reject a usage like @samp{verify (@var{EXPRESSION});} even when @var{EXPRESSION} is nonzero. -Here are some example uses. +Although the standard @code{assert} macro is a runtime test, draft C1X +specifies a builtin @code{_Static_assert (@var{EXPRESSION}, +@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_true}. @example #include @@ -56,9 +66,8 @@ Here are some example uses. /* Verify that time_t is an integer type. */ verify ((time_t) 1.5 == 1); -/* Verify that time_t is at least as wide as int. */ -verify (INT_MIN == (time_t) INT_MIN); -verify (INT_MAX == (time_t) INT_MAX); +/* 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); -- 2.30.2