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

/* Compile-time assert-like macros.

   Copyright (C) 2005-2006, 2009-2012 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.

   * 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
caf8a9b2	3	Copyright (C) 2005-2006, 2009-2012 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
	128	-Wredundant_decls is used. GCC 4.3 and later have a builtin
	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
	136	* In C++, any struct definition inside sizeof is invalid.
	137	Use a template type to work around the problem. */
	138
	139	/* Concatenate two preprocessor tokens. */
	140	# define _GL_CONCAT(x, y) _GL_CONCAT0 (x, y)
	141	# define _GL_CONCAT0(x, y) x##y
	142
	143	/* _GL_COUNTER is an integer, preferably one that changes each time we
	144	use it. Use __COUNTER__ if it works, falling back on __LINE__
	145	otherwise. __LINE__ isn't perfect, but it's better than a
	146	constant. */
	147	# if defined __COUNTER__ && __COUNTER__ != __COUNTER__
	148	# define _GL_COUNTER __COUNTER__
	149	# else
	150	# define _GL_COUNTER __LINE__
	151	# endif
	152
	153	/* Generate a symbol with the given prefix, making it unique if
	154	possible. */
	155	# define _GL_GENSYM(prefix) _GL_CONCAT (prefix, _GL_COUNTER)
	156
9991d78e PE	157	/* Verify requirement R at compile-time, as an integer constant expression
	158	that returns 1. If R is false, fail at compile-time, preferably
	159	with a diagnostic that includes the string-literal DIAGNOSTIC. */
	160
	161	# define _GL_VERIFY_TRUE(R, DIAGNOSTIC) \
	162	(!!sizeof (_GL_VERIFY_TYPE (R, DIAGNOSTIC)))
a8a2bb29 PE	163
a8a2bb29 PE	164	# ifdef __cplusplus
6a3e57bb	165	# if !GNULIB_defined_struct__gl_verify_type
a8a2bb29	166	template <int w>
9991d78e PE	167	struct _gl_verify_type {
	168	unsigned int _gl_verify_error_if_negative: w;
	169	};
6a3e57bb PE	170	# define GNULIB_defined_struct__gl_verify_type 1
6a3e57bb PE	171	# endif
9991d78e PE	172	# define _GL_VERIFY_TYPE(R, DIAGNOSTIC) \
	173	_gl_verify_type<(R) ? 1 : -1>
	174	# elif defined _GL_HAVE__STATIC_ASSERT
	175	# define _GL_VERIFY_TYPE(R, DIAGNOSTIC) \
	176	struct { \
	177	_Static_assert (R, DIAGNOSTIC); \
	178	int _gl_dummy; \
	179	}
a8a2bb29	180	# else
9991d78e PE	181	# define _GL_VERIFY_TYPE(R, DIAGNOSTIC) \
9991d78e PE	182	struct { unsigned int _gl_verify_error_if_negative: (R) ? 1 : -1; }
a8a2bb29 PE	183	# endif
	184
	185	/* Verify requirement R at compile-time, as a declaration without a
9991d78e PE	186	trailing ';'. If R is false, fail at compile-time, preferably
	187	with a diagnostic that includes the string-literal DIAGNOSTIC.
	188
caf8a9b2	189	Unfortunately, unlike C11, this implementation must appear as an
9991d78e PE	190	ordinary declaration, and cannot appear inside struct { ... }. */
	191
	192	# ifdef _GL_HAVE__STATIC_ASSERT
	193	# define _GL_VERIFY _Static_assert
	194	# else
	195	# define _GL_VERIFY(R, DIAGNOSTIC) \
	196	extern int (*_GL_GENSYM (_gl_verify_function) (void)) \
	197	[_GL_VERIFY_TRUE (R, DIAGNOSTIC)]
	198	# endif
a8a2bb29	199
9991d78e PE	200	/* _GL_STATIC_ASSERT_H is defined if this code is copied into assert.h. */
	201	# ifdef _GL_STATIC_ASSERT_H
	202	# if !defined _GL_HAVE__STATIC_ASSERT && !defined _Static_assert
	203	# define _Static_assert(R, DIAGNOSTIC) _GL_VERIFY (R, DIAGNOSTIC)
	204	# endif
	205	# if !defined _GL_HAVE_STATIC_ASSERT && !defined static_assert
caf8a9b2	206	# define static_assert _Static_assert /* C11 requires this #define. */
9991d78e	207	# endif
2df215b5 PE	208	# endif
2df215b5 PE	209
6a3e57bb	210	/* @assert.h omit start@ */
9991d78e PE	211
	212	/* Each of these macros verifies that its argument R is nonzero. To
	213	be portable, R should be an integer constant expression. Unlike
	214	assert (R), there is no run-time overhead.
	215
	216	There are two macros, since no single macro can be used in all
	217	contexts in C. verify_true (R) is for scalar contexts, including
	218	integer constant expression contexts. verify (R) is for declaration
	219	contexts, e.g., the top level. */
	220
	221	/* Verify requirement R at compile-time, as an integer constant expression.
8c9b2106 PE	222	Return 1. This is equivalent to verify_expr (R, 1).
	223
	224	verify_true is obsolescent; please use verify_expr instead. */
9991d78e	225
6a3e57bb	226	# define verify_true(R) _GL_VERIFY_TRUE (R, "verify_true (" #R ")")
9991d78e	227
8c9b2106 PE	228	/* Verify requirement R at compile-time. Return the value of the
	229	expression E. */
	230
	231	# define verify_expr(R, E) \
	232	(_GL_VERIFY_TRUE (R, "verify_expr (" #R ", " #E ")") ? (E) : (E))
	233
9991d78e PE	234	/* Verify requirement R at compile-time, as a declaration without a
	235	trailing ';'. */
	236
6a3e57bb	237	# define verify(R) _GL_VERIFY (R, "verify (" #R ")")
9991d78e	238
6a3e57bb	239	/* @assert.h omit end@ */
a8a2bb29 PE	240
a8a2bb29 PE	241	#endif