[bpt/emacs.git] / lib / verify.h

/* Compile-time assert-like macros.

   Copyright (C) 2005-2006, 2009-2013 Free Software Foundation, Inc.

   This program is free software: you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */

/* Written by Paul Eggert, Bruno Haible, and Jim Meyering.  */

#ifndef _GL_VERIFY_H
# define _GL_VERIFY_H


/* Define _GL_HAVE__STATIC_ASSERT to 1 if _Static_assert works as per C11.
   This is supported by GCC 4.6.0 and later, in C mode, and its use
   here generates easier-to-read diagnostics when verify (R) fails.

   Define _GL_HAVE_STATIC_ASSERT to 1 if static_assert works as per C++11.
   This will likely be supported by future GCC versions, in C++ mode.

   Use this only with GCC.  If we were willing to slow 'configure'
   down we could also use it with other compilers, but since this
   affects only the quality of diagnostics, why bother?  */
# if (4 < __GNUC__ || (__GNUC__ == 4 && 6 <= __GNUC_MINOR__)) && !defined __cplusplus
#  define _GL_HAVE__STATIC_ASSERT 1
# endif
/* The condition (99 < __GNUC__) is temporary, until we know about the
   first G++ release that supports static_assert.  */
# if (99 < __GNUC__) && defined __cplusplus
#  define _GL_HAVE_STATIC_ASSERT 1
# endif

/* Each of these macros verifies that its argument R is nonzero.  To
   be portable, R should be an integer constant expression.  Unlike
   assert (R), there is no run-time overhead.

   If _Static_assert works, verify (R) uses it directly.  Similarly,
   _GL_VERIFY_TRUE works by packaging a _Static_assert inside a struct
   that is an operand of sizeof.

   The code below uses several ideas for C++ compilers, and for C
   compilers that do not support _Static_assert:

   * The first step is ((R) ? 1 : -1).  Given an expression R, of
     integral or boolean or floating-point type, this yields an
     expression of integral type, whose value is later verified to be
     constant and nonnegative.

   * Next this expression W is wrapped in a type
     struct _gl_verify_type {
       unsigned int _gl_verify_error_if_negative: W;
     }.
     If W is negative, this yields a compile-time error.  No compiler can
     deal with a bit-field of negative size.

     One might think that an array size check would have the same
     effect, that is, that the type struct { unsigned int dummy[W]; }
     would work as well.  However, inside a function, some compilers
     (such as C++ compilers and GNU C) allow local parameters and
     variables inside array size expressions.  With these compilers,
     an array size check would not properly diagnose this misuse of
     the verify macro:

       void function (int n) { verify (n < 0); }

   * For the verify macro, the struct _gl_verify_type will need to
     somehow be embedded into a declaration.  To be portable, this
     declaration must declare an object, a constant, a function, or a
     typedef name.  If the declared entity uses the type directly,
     such as in

       struct dummy {...};
       typedef struct {...} dummy;
       extern struct {...} *dummy;
       extern void dummy (struct {...} *);
       extern struct {...} *dummy (void);

     two uses of the verify macro would yield colliding declarations
     if the entity names are not disambiguated.  A workaround is to
     attach the current line number to the entity name:

       #define _GL_CONCAT0(x, y) x##y
       #define _GL_CONCAT(x, y) _GL_CONCAT0 (x, y)
       extern struct {...} * _GL_CONCAT (dummy, __LINE__);

     But this has the problem that two invocations of verify from
     within the same macro would collide, since the __LINE__ value
     would be the same for both invocations.  (The GCC __COUNTER__
     macro solves this problem, but is not portable.)

     A solution is to use the sizeof operator.  It yields a number,
     getting rid of the identity of the type.  Declarations like

       extern int dummy [sizeof (struct {...})];
       extern void dummy (int [sizeof (struct {...})]);
       extern int (*dummy (void)) [sizeof (struct {...})];

     can be repeated.

   * Should the implementation use a named struct or an unnamed struct?
     Which of the following alternatives can be used?

       extern int dummy [sizeof (struct {...})];
       extern int dummy [sizeof (struct _gl_verify_type {...})];
       extern void dummy (int [sizeof (struct {...})]);
       extern void dummy (int [sizeof (struct _gl_verify_type {...})]);
       extern int (*dummy (void)) [sizeof (struct {...})];
       extern int (*dummy (void)) [sizeof (struct _gl_verify_type {...})];

     In the second and sixth case, the struct type is exported to the
     outer scope; two such declarations therefore collide.  GCC warns
     about the first, third, and fourth cases.  So the only remaining
     possibility is the fifth case:

       extern int (*dummy (void)) [sizeof (struct {...})];

   * GCC warns about duplicate declarations of the dummy function if
     -Wredundant-decls is used.  GCC 4.3 and later have a builtin
     __COUNTER__ macro that can let us generate unique identifiers for
     each dummy function, to suppress this warning.

   * This implementation exploits the fact that older versions of GCC,
     which do not support _Static_assert, also do not warn about the
     last declaration mentioned above.

   * GCC warns if -Wnested-externs is enabled and verify() is used
     within a function body; but inside a function, you can always
     arrange to use verify_expr() instead.

   * In C++, any struct definition inside sizeof is invalid.
     Use a template type to work around the problem.  */

/* Concatenate two preprocessor tokens.  */
# define _GL_CONCAT(x, y) _GL_CONCAT0 (x, y)
# define _GL_CONCAT0(x, y) x##y

/* _GL_COUNTER is an integer, preferably one that changes each time we
   use it.  Use __COUNTER__ if it works, falling back on __LINE__
   otherwise.  __LINE__ isn't perfect, but it's better than a
   constant.  */
# if defined __COUNTER__ && __COUNTER__ != __COUNTER__
#  define _GL_COUNTER __COUNTER__
# else
#  define _GL_COUNTER __LINE__
# endif

/* Generate a symbol with the given prefix, making it unique if
   possible.  */
# define _GL_GENSYM(prefix) _GL_CONCAT (prefix, _GL_COUNTER)

/* Verify requirement R at compile-time, as an integer constant expression
   that returns 1.  If R is false, fail at compile-time, preferably
   with a diagnostic that includes the string-literal DIAGNOSTIC.  */

# define _GL_VERIFY_TRUE(R, DIAGNOSTIC) \
    (!!sizeof (_GL_VERIFY_TYPE (R, DIAGNOSTIC)))

# ifdef __cplusplus
#  if !GNULIB_defined_struct__gl_verify_type
template <int w>
  struct _gl_verify_type {
    unsigned int _gl_verify_error_if_negative: w;
  };
#   define GNULIB_defined_struct__gl_verify_type 1
#  endif
#  define _GL_VERIFY_TYPE(R, DIAGNOSTIC) \
    _gl_verify_type<(R) ? 1 : -1>
# elif defined _GL_HAVE__STATIC_ASSERT
#  define _GL_VERIFY_TYPE(R, DIAGNOSTIC) \
     struct {                                   \
       _Static_assert (R, DIAGNOSTIC);          \
       int _gl_dummy;                          \
     }
# else
#  define _GL_VERIFY_TYPE(R, DIAGNOSTIC) \
     struct { unsigned int _gl_verify_error_if_negative: (R) ? 1 : -1; }
# endif

/* Verify requirement R at compile-time, as a declaration without a
   trailing ';'.  If R is false, fail at compile-time, preferably
   with a diagnostic that includes the string-literal DIAGNOSTIC.

   Unfortunately, unlike C11, this implementation must appear as an
   ordinary declaration, and cannot appear inside struct { ... }.  */

# ifdef _GL_HAVE__STATIC_ASSERT
#  define _GL_VERIFY _Static_assert
# else
#  define _GL_VERIFY(R, DIAGNOSTIC)				       \
     extern int (*_GL_GENSYM (_gl_verify_function) (void))	       \
       [_GL_VERIFY_TRUE (R, DIAGNOSTIC)]
# endif

/* _GL_STATIC_ASSERT_H is defined if this code is copied into assert.h.  */
# ifdef _GL_STATIC_ASSERT_H
#  if !defined _GL_HAVE__STATIC_ASSERT && !defined _Static_assert
#   define _Static_assert(R, DIAGNOSTIC) _GL_VERIFY (R, DIAGNOSTIC)
#  endif
#  if !defined _GL_HAVE_STATIC_ASSERT && !defined static_assert
#   define static_assert _Static_assert /* C11 requires this #define.  */
#  endif
# endif

/* @assert.h omit start@  */

/* Each of these macros verifies that its argument R is nonzero.  To
   be portable, R should be an integer constant expression.  Unlike
   assert (R), there is no run-time overhead.

   There are two macros, since no single macro can be used in all
   contexts in C.  verify_true (R) is for scalar contexts, including
   integer constant expression contexts.  verify (R) is for declaration
   contexts, e.g., the top level.  */

/* Verify requirement R at compile-time, as an integer constant expression.
   Return 1.  This is equivalent to verify_expr (R, 1).

   verify_true is obsolescent; please use verify_expr instead.  */

# define verify_true(R) _GL_VERIFY_TRUE (R, "verify_true (" #R ")")

/* Verify requirement R at compile-time.  Return the value of the
   expression E.  */

# define verify_expr(R, E) \
    (_GL_VERIFY_TRUE (R, "verify_expr (" #R ", " #E ")") ? (E) : (E))

/* Verify requirement R at compile-time, as a declaration without a
   trailing ';'.  */

# define verify(R) _GL_VERIFY (R, "verify (" #R ")")

/* @assert.h omit end@  */

#endif
Commit	Line	Data
a8a2bb29 PE	1	/* Compile-time assert-like macros.
a8a2bb29 PE	2
ab422c4d	3	Copyright (C) 2005-2006, 2009-2013 Free Software Foundation, Inc.
a8a2bb29 PE	4
	5	This program is free software: you can redistribute it and/or modify
	6	it under the terms of the GNU General Public License as published by
	7	the Free Software Foundation; either version 3 of the License, or
	8	(at your option) any later version.
	9
	10	This program is distributed in the hope that it will be useful,
	11	but WITHOUT ANY WARRANTY; without even the implied warranty of
	12	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	13	GNU General Public License for more details.
	14
	15	You should have received a copy of the GNU General Public License
	16	along with this program. If not, see <http://www.gnu.org/licenses/>. */
	17
	18	/* Written by Paul Eggert, Bruno Haible, and Jim Meyering. */
	19
9991d78e PE	20	#ifndef _GL_VERIFY_H
9991d78e PE	21	# define _GL_VERIFY_H
a8a2bb29	22
9991d78e	23
caf8a9b2 PE	24	/* Define _GL_HAVE__STATIC_ASSERT to 1 if _Static_assert works as per C11.
	25	This is supported by GCC 4.6.0 and later, in C mode, and its use
	26	here generates easier-to-read diagnostics when verify (R) fails.
a8a2bb29	27
caf8a9b2	28	Define _GL_HAVE_STATIC_ASSERT to 1 if static_assert works as per C++11.
a8a2bb29 PE	29	This will likely be supported by future GCC versions, in C++ mode.
a8a2bb29 PE	30
9991d78e PE	31	Use this only with GCC. If we were willing to slow 'configure'
	32	down we could also use it with other compilers, but since this
	33	affects only the quality of diagnostics, why bother? */
a8a2bb29	34	# if (4 < __GNUC__ \|\| (__GNUC__ == 4 && 6 <= __GNUC_MINOR__)) && !defined __cplusplus
9991d78e	35	# define _GL_HAVE__STATIC_ASSERT 1
a8a2bb29 PE	36	# endif
	37	/* The condition (99 < __GNUC__) is temporary, until we know about the
	38	first G++ release that supports static_assert. */
	39	# if (99 < __GNUC__) && defined __cplusplus
9991d78e	40	# define _GL_HAVE_STATIC_ASSERT 1
a8a2bb29 PE	41	# endif
	42
	43	/* Each of these macros verifies that its argument R is nonzero. To
	44	be portable, R should be an integer constant expression. Unlike
	45	assert (R), there is no run-time overhead.
	46
a8a2bb29	47	If _Static_assert works, verify (R) uses it directly. Similarly,
9991d78e	48	_GL_VERIFY_TRUE works by packaging a _Static_assert inside a struct
a8a2bb29 PE	49	that is an operand of sizeof.
	50
	51	The code below uses several ideas for C++ compilers, and for C
	52	compilers that do not support _Static_assert:
	53
	54	* The first step is ((R) ? 1 : -1). Given an expression R, of
	55	integral or boolean or floating-point type, this yields an
	56	expression of integral type, whose value is later verified to be
	57	constant and nonnegative.
	58
	59	* Next this expression W is wrapped in a type
9991d78e PE	60	struct _gl_verify_type {
	61	unsigned int _gl_verify_error_if_negative: W;
	62	}.
a8a2bb29 PE	63	If W is negative, this yields a compile-time error. No compiler can
	64	deal with a bit-field of negative size.
	65
	66	One might think that an array size check would have the same
	67	effect, that is, that the type struct { unsigned int dummy[W]; }
	68	would work as well. However, inside a function, some compilers
	69	(such as C++ compilers and GNU C) allow local parameters and
	70	variables inside array size expressions. With these compilers,
	71	an array size check would not properly diagnose this misuse of
	72	the verify macro:
	73
	74	void function (int n) { verify (n < 0); }
	75
9991d78e	76	* For the verify macro, the struct _gl_verify_type will need to
a8a2bb29 PE	77	somehow be embedded into a declaration. To be portable, this
	78	declaration must declare an object, a constant, a function, or a
	79	typedef name. If the declared entity uses the type directly,
	80	such as in
	81
	82	struct dummy {...};
	83	typedef struct {...} dummy;
	84	extern struct {...} *dummy;
	85	extern void dummy (struct {...} *);
	86	extern struct {...} *dummy (void);
	87
	88	two uses of the verify macro would yield colliding declarations
	89	if the entity names are not disambiguated. A workaround is to
	90	attach the current line number to the entity name:
	91
	92	#define _GL_CONCAT0(x, y) x##y
	93	#define _GL_CONCAT(x, y) _GL_CONCAT0 (x, y)
	94	extern struct {...} * _GL_CONCAT (dummy, __LINE__);
	95
	96	But this has the problem that two invocations of verify from
	97	within the same macro would collide, since the __LINE__ value
	98	would be the same for both invocations. (The GCC __COUNTER__
	99	macro solves this problem, but is not portable.)
	100
	101	A solution is to use the sizeof operator. It yields a number,
	102	getting rid of the identity of the type. Declarations like
	103
	104	extern int dummy [sizeof (struct {...})];
	105	extern void dummy (int [sizeof (struct {...})]);
	106	extern int (*dummy (void)) [sizeof (struct {...})];
	107
	108	can be repeated.
	109
	110	* Should the implementation use a named struct or an unnamed struct?
	111	Which of the following alternatives can be used?
	112
	113	extern int dummy [sizeof (struct {...})];
9991d78e	114	extern int dummy [sizeof (struct _gl_verify_type {...})];
a8a2bb29	115	extern void dummy (int [sizeof (struct {...})]);
9991d78e	116	extern void dummy (int [sizeof (struct _gl_verify_type {...})]);
a8a2bb29	117	extern int (*dummy (void)) [sizeof (struct {...})];
9991d78e	118	extern int (*dummy (void)) [sizeof (struct _gl_verify_type {...})];
a8a2bb29 PE	119
	120	In the second and sixth case, the struct type is exported to the
	121	outer scope; two such declarations therefore collide. GCC warns
	122	about the first, third, and fourth cases. So the only remaining
	123	possibility is the fifth case:
	124
	125	extern int (*dummy (void)) [sizeof (struct {...})];
	126
	127	* GCC warns about duplicate declarations of the dummy function if
894bd873	128	-Wredundant-decls is used. GCC 4.3 and later have a builtin
a8a2bb29 PE	129	__COUNTER__ macro that can let us generate unique identifiers for
	130	each dummy function, to suppress this warning.
	131
	132	* This implementation exploits the fact that older versions of GCC,
	133	which do not support _Static_assert, also do not warn about the
	134	last declaration mentioned above.
	135
894bd873 PE	136	* GCC warns if -Wnested-externs is enabled and verify() is used
	137	within a function body; but inside a function, you can always
	138	arrange to use verify_expr() instead.
	139
a8a2bb29 PE	140	* In C++, any struct definition inside sizeof is invalid.
	141	Use a template type to work around the problem. */
	142
	143	/* Concatenate two preprocessor tokens. */
	144	# define _GL_CONCAT(x, y) _GL_CONCAT0 (x, y)
	145	# define _GL_CONCAT0(x, y) x##y
	146
	147	/* _GL_COUNTER is an integer, preferably one that changes each time we
	148	use it. Use __COUNTER__ if it works, falling back on __LINE__
	149	otherwise. __LINE__ isn't perfect, but it's better than a
	150	constant. */
	151	# if defined __COUNTER__ && __COUNTER__ != __COUNTER__
	152	# define _GL_COUNTER __COUNTER__
	153	# else
	154	# define _GL_COUNTER __LINE__
	155	# endif
	156
	157	/* Generate a symbol with the given prefix, making it unique if
	158	possible. */
	159	# define _GL_GENSYM(prefix) _GL_CONCAT (prefix, _GL_COUNTER)
	160
9991d78e PE	161	/* Verify requirement R at compile-time, as an integer constant expression
	162	that returns 1. If R is false, fail at compile-time, preferably
	163	with a diagnostic that includes the string-literal DIAGNOSTIC. */
	164
	165	# define _GL_VERIFY_TRUE(R, DIAGNOSTIC) \
	166	(!!sizeof (_GL_VERIFY_TYPE (R, DIAGNOSTIC)))
a8a2bb29 PE	167
a8a2bb29 PE	168	# ifdef __cplusplus
6a3e57bb	169	# if !GNULIB_defined_struct__gl_verify_type
a8a2bb29	170	template <int w>
9991d78e PE	171	struct _gl_verify_type {
	172	unsigned int _gl_verify_error_if_negative: w;
	173	};
6a3e57bb PE	174	# define GNULIB_defined_struct__gl_verify_type 1
6a3e57bb PE	175	# endif
9991d78e PE	176	# define _GL_VERIFY_TYPE(R, DIAGNOSTIC) \
	177	_gl_verify_type<(R) ? 1 : -1>
	178	# elif defined _GL_HAVE__STATIC_ASSERT
	179	# define _GL_VERIFY_TYPE(R, DIAGNOSTIC) \
	180	struct { \
	181	_Static_assert (R, DIAGNOSTIC); \
	182	int _gl_dummy; \
	183	}
a8a2bb29	184	# else
9991d78e PE	185	# define _GL_VERIFY_TYPE(R, DIAGNOSTIC) \
9991d78e PE	186	struct { unsigned int _gl_verify_error_if_negative: (R) ? 1 : -1; }
a8a2bb29 PE	187	# endif
	188
	189	/* Verify requirement R at compile-time, as a declaration without a
9991d78e PE	190	trailing ';'. If R is false, fail at compile-time, preferably
	191	with a diagnostic that includes the string-literal DIAGNOSTIC.
	192
caf8a9b2	193	Unfortunately, unlike C11, this implementation must appear as an
9991d78e PE	194	ordinary declaration, and cannot appear inside struct { ... }. */
	195
	196	# ifdef _GL_HAVE__STATIC_ASSERT
	197	# define _GL_VERIFY _Static_assert
	198	# else
	199	# define _GL_VERIFY(R, DIAGNOSTIC) \
	200	extern int (*_GL_GENSYM (_gl_verify_function) (void)) \
	201	[_GL_VERIFY_TRUE (R, DIAGNOSTIC)]
	202	# endif
a8a2bb29	203
9991d78e PE	204	/* _GL_STATIC_ASSERT_H is defined if this code is copied into assert.h. */
	205	# ifdef _GL_STATIC_ASSERT_H
	206	# if !defined _GL_HAVE__STATIC_ASSERT && !defined _Static_assert
	207	# define _Static_assert(R, DIAGNOSTIC) _GL_VERIFY (R, DIAGNOSTIC)
	208	# endif
	209	# if !defined _GL_HAVE_STATIC_ASSERT && !defined static_assert
caf8a9b2	210	# define static_assert _Static_assert /* C11 requires this #define. */
9991d78e	211	# endif
2df215b5 PE	212	# endif
2df215b5 PE	213
6a3e57bb	214	/* @assert.h omit start@ */
9991d78e PE	215
	216	/* Each of these macros verifies that its argument R is nonzero. To
	217	be portable, R should be an integer constant expression. Unlike
	218	assert (R), there is no run-time overhead.
	219
	220	There are two macros, since no single macro can be used in all
	221	contexts in C. verify_true (R) is for scalar contexts, including
	222	integer constant expression contexts. verify (R) is for declaration
	223	contexts, e.g., the top level. */
	224
	225	/* Verify requirement R at compile-time, as an integer constant expression.
8c9b2106 PE	226	Return 1. This is equivalent to verify_expr (R, 1).
	227
	228	verify_true is obsolescent; please use verify_expr instead. */
9991d78e	229
6a3e57bb	230	# define verify_true(R) _GL_VERIFY_TRUE (R, "verify_true (" #R ")")
9991d78e	231
8c9b2106 PE	232	/* Verify requirement R at compile-time. Return the value of the
	233	expression E. */
	234
	235	# define verify_expr(R, E) \
	236	(_GL_VERIFY_TRUE (R, "verify_expr (" #R ", " #E ")") ? (E) : (E))
	237
9991d78e PE	238	/* Verify requirement R at compile-time, as a declaration without a
	239	trailing ';'. */
	240
6a3e57bb	241	# define verify(R) _GL_VERIFY (R, "verify (" #R ")")
9991d78e	242
6a3e57bb	243	/* @assert.h omit end@ */
a8a2bb29 PE	244
a8a2bb29 PE	245	#endif