[mLib] / utils / macros.h

/* -*-c-*-
 *
 * Handy macros
 *
 * (c) 2003 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the mLib utilities library.
 *
 * mLib is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * mLib 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 Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with mLib; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

#ifndef MLIB_MACROS_H
#define MLIB_MACROS_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <assert.h>

#ifndef MLIB_COMPILER_H
#  include "compiler.h"
#endif

/*----- Miscellaneous utility macros --------------------------------------*/

/* --- @N@ --- *
 *
 * Arguments:	@type v[]@ = an actual array, not a pointer
 *
 * Returns:	The number of elements in @v@.
 */

#define N(v) (sizeof(v)/sizeof(*(v)))

/* --- @STR@ --- *
 *
 * Arguments:	@x@ = some tokens
 *
 * Returns:	A string literal containing the macro-expanded text of @x@.
 */

#define MLIB__STR(x) #x
#define STR(x) MLIB__STR(x)

/* --- @GLUE@ --- *
 *
 * Arguments:	@x, y@ = two sequences of tokens
 *
 * Returns:	A single token formed by gluing together the macro-expansions
 *		of @x@ and @y@.
 */

#define MLIB__GLUE(x, y) x##y
#define GLUE(x, y) MLIB__GLUE(x, y)

/* --- @STATIC_ASSERT@ --- *
 *
 * Arguments:	@int cond@ = a condition
 *		@msg@ = a string literal message
 *
 * Returns:	---
 *
 * Use:		Fail at compile time unless @cond@ is nonzero.  The failure
 *		might report @msg@.
 */

#ifdef static_assert
#  define STATIC_ASSERT(cond, msg) static_assert(!!(cond), msg)
#else
#  define STATIC_ASSERT(cond, msg)					\
	IGNORABLE extern char static_assert_failed[1 - 2*!(cond)]
#endif

/* --- @CHECK_TYPE@ ---
 *
 * Arguments:	@expty@ = expected type of @x@
 *		@expty x@ = some object
 *
 * Returns:	Integer zero.
 *
 * Use:		Cause a compile-time failure unless the type of @x@ is
 *		assignment-compatible with @expty@.
 */

#define CHECK_TYPE(expty, x) (!sizeof(*(expty *)0 = (x)))

/* --- @CONVERT_CAREFULLY@ ---
 *
 * Arguments:	@newty@ = new type for the result
 *		@expty@ = expected type of @x@
 *		@expty x@ = some object
 *
 * Returns:	@x@, but coerced to type @newty@.
 *
 * Use:		Like @(newty)x@, except that it checks at compile-time that
 *		@x@ is at least assignment-compatible with type @expty@
 *		before trying.
 */

#define CONVERT_CAREFULLY(newty, expty, x)				\
	(CHECK_TYPE(expty, x) + (/*unconst unvolatile*/ newty)(x))

/* --- @UNCONST@, @UNVOLATILE@, @UNQUALIFY@ --- *
 *
 * Arguments:	@type@ = a type name
 *		@type *p@ = a pointer
 *
 * Returns:	@p@, but without @const@, @volatile@ or both qualifiers.
 *
 * Use:		Strips qualifiers from pointer types.
 *
 *		The @UNCONST@ macro strips @const@.  It checks that @p@
 *		has type `pointer to @type@ or @const type@'; if not, a
 *		compile-time error results.  Otherwise, it returns the value
 *		of @p@, converted to `pointer to (non-constant) @type@'.  It
 *		will not silently strip a @volatile@ qualifier.
 *
 *		The @UNVOLATILE@ macro is similar, except that it strips
 *		@volatile@ instead of @const@.  The @UNQUALIFY@ macro strips
 *		both qualifiers.
 */

#define UNCONST(type, p) CONVERT_CAREFULLY(type *, const type *, p)
#define UNVOLATILE(type, p) CONVERT_CAREFULLY(type *, volatile type *, p)
#define UNQUALIFY(type, p)						\
	CONVERT_CAREFULLY(type *, const volatile type *, p)

/* --- @COMMA@ --- *
 *
 * Arguments:	---
 *
 * Returns:	A `%|,|%' token, which can be usefully passed to macros to
 *		avoid argument splitting.
 */

#define COMMA ,

/*----- String and character hacks ----------------------------------------*/

/* --- @IS...@ --- *
 *
 * Arguments:	@int ch@ = a character code, but not @EOF@
 *
 * Returns:	Nonzero if @ch@ is in the relevant @<ctype.h>@ category.
 *
 * Use:		Classifies characters, but safely even if characters are
 *		signed.
 *
 *		There is a macro for each of the @<ctype.h>@ @is...@
 *		functions.
 */

#define CTYPE_HACK(func, ch) (func((unsigned char)(ch)))

#define ISALNUM(ch) CTYPE_HACK(isalnum, ch)
#define ISALPHA(ch) CTYPE_HACK(isalpha, ch)
#define ISASCII(ch) CTYPE_HACK(isascii, ch)
#define ISBLANK(ch) CTYPE_HACK(isblank, ch)
#define ISCNTRL(ch) CTYPE_HACK(iscntrl, ch)
#define ISDIGIT(ch) CTYPE_HACK(isdigit, ch)
#define ISGRAPH(ch) CTYPE_HACK(isgraph, ch)
#define ISLOWER(ch) CTYPE_HACK(islower, ch)
#define ISPRINT(ch) CTYPE_HACK(isprint, ch)
#define ISPUNCT(ch) CTYPE_HACK(ispunct, ch)
#define ISSPACE(ch) CTYPE_HACK(isspace, ch)
#define ISUPPER(ch) CTYPE_HACK(isupper, ch)
#define ISXDIGIT(ch) CTYPE_HACK(isxdigit, ch)

/* --- @TO...@ --- *
 *
 * Arguments:	@int ch@ = a character code, but not @EOF@
 *
 * Returns:	The converted character code.
 *
 * Use:		Converts characters, but safely even if characters are
 *		signed.
 *
 *		There is a macro for each of the @<ctype.h>@ @to...@
 *		functions.
 */

#define TOASCII(ch) CTYPE_HACK(toascii, ch)
#define TOLOWER(ch) CTYPE_HACK(tolower, ch)
#define TOUPPER(ch) CTYPE_HACK(toupper, ch)

/* --- @MEMCMP@, @STRCMP@, @STRNCMP@ --- *
 *
 * Arguments:	@const type *x, *y@ = pointers to strings
 *		@op@ = a relational operator symbol
 *		@size_t n@ = length of the strings
 *
 * Returns:	Nonzero if the relationship between the strings satisfies the
 *		operator @op@, otherwise zero.
 *
 * Use:		These macros mitigate the author's frequent error of failing
 *		to compare the result of the underlying standard functions
 *		against zero, effectively reversing the sense of an intended
 *		test for equality.
 */

#define MEMCMP(x, op, y, n) (memcmp((x), (y), (n)) op 0)
#define STRCMP(x, op, y) (strcmp((x), (y)) op 0)
#define STRNCMP(x, op, y, n) (strncmp((x), (y), (n)) op 0)

/*----- Compiler-specific definitions -------------------------------------*/

/* The descriptions of these are given below, with the fallback
 * definitions.
 */

#if GCC_VERSION_P(2, 5) || CLANG_VERSION_P(3, 3)
#  define NORETURN __attribute__((__noreturn__))
#  define PRINTF_LIKE(fix, aix) __attribute__((__format__(printf, fix, aix)))
#  define SCANF_LIKE(fix, aix) __attribute__((__format__(scanf, fix, aix)))
#  define IGNORABLE __attribute__((__unused__))
#endif

#if GCC_VERSION_P(3, 4) || CLANG_VERSION_P(3, 3)
#  define MUST_CHECK __attribute__((__warn_unused_result__))
#endif

#if GCC_VERSION_P(4, 5) || CLANG_VERSION_P(3, 3)
#  define DEPRECATED(msg) __attribute__((__deprecated__(msg)))
#elif GCC_VERSION_P(3, 1)
#  define DEPRECATED(msg) __attribute__((__deprecated__))
#endif

#if GCC_VERSION_P(4, 0) || CLANG_VERSION_P(3, 3)
#  define EXECL_LIKE(ntrail) __attribute__((__sentinel__(ntrail)))
#endif

#if GCC_VERSION_P(2, 7) || CLANG_VERSION_P(0, 0)
#  define LAUNDER(x)							\
	({ __typeof__(x) _y; __asm__("" : "=g"(_y) : "0"(x)); _y; })
#  define ADMIRE(x)							\
	({ __asm__("" : : "g"(x)); })
#  define ADMIRE_BUF(p, sz)						\
	({ __asm__("" : : "g"(p), "g"(sz)); })
#  define RELAX do __asm__ __volatile__("" ::: "memory"); while (0)
#endif

#if CLANG_VERSION_P(3, 3)

#  define MLIB__PRAGMA_HACK(x) _Pragma(#x)
#  define MLIB__MUFFLE_WARNINGS(warns, body)				\
	_Pragma("clang diagnostic push")				\
	warns								\
	body								\
	_Pragma("clang diagnostic pop")
#  define CLANG_WARNING(warn)						\
	MLIB__PRAGMA_HACK(clang diagnostic ignored warn)
#  define MUFFLE_WARNINGS_DECL(warns, body)				\
	MLIB__MUFFLE_WARNINGS(warns, body)
#  define MUFFLE_WARNINGS_EXPR(warns, body)				\
	__extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
#  define MUFFLE_WARNINGS_STMT(warns, body)				\
	do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)

#endif

#if GCC_VERSION_P(4, 6)

   /* --- Diagnostic suppression in GCC: a tale of woe --- *
    *
    * This is extremely unpleasant, largely as a result of bugs in the GCC
    * preprocessor's handling of @_Pragma@.  The fundamental problem is
    * that it's the preprocessor, and not the compiler proper, which
    * detects @_Pragma@, emitting @#pragma@ lines into its output; and it
    * does it during macro expansion, even if the macro is being expanded
    * during argument collection.  Since arguments are expanded before
    * replacing the macro's invocation with its body, a pragma in an
    * argument will be emitted %%\emph{before}%% any pragmata in the body,
    * even if they appear before the argument in the body -- and even if
    * the argument doesn't actually appear anywhere at all in the body.
    *
    * Another, rather less significant, problem is that @_Pragma@'s
    * argument is a single string literal, recognized in translation phase
    * 4, before string-literal concatenation in phase 6, so we must build
    * pragma bodies as token lists and then stringify them.
    *
    * As a result, we need some subterfuge here.  The @MLIB__PRAGMA_HACK@
    * macro issues a @_Pragma@ on its argument token list, which it
    * stringifies; this deals with the second problem.  The first is
    * trickier: we must delay expansion of @MLIB__PRAGMA_HACK@ from the
    * argument collection phase to the body rescanning phase, and we do
    * this by splitting the invocations between @GCC_WARNING@ macro calls:
    * the name is left hanging from the previous call (or from
    * @MLIB__MUFFLE_WARNINGS@, in the first case) and the body is supplied
    * by @GCC_WARNING@, which also supplies the next @MLIB__PRAGMA_HACK@.
    * The remaining problem is to make sure we can dispose of the final
    * trailing @MLIB__PRAGMA_HACK@ harmlessly, which we do by introducing
    * an extra argument @emitp@, which may be either @t@ or @nil@; this
    * dispatches to an appropriate helper macro by means of token-pasting.
    *
    * I'm so sorry.
    */

#  define MLIB__PRAGMA_HACK_t(x) _Pragma(#x)
#  define MLIB__PRAGMA_HACK_nil(x)
#  define MLIB__PRAGMA_HACK(emitp, x) MLIB__PRAGMA_HACK_##emitp(x)
#  define MLIB__MUFFLE_WARNINGS(warns, body)				\
	_Pragma("GCC diagnostic push") MLIB__PRAGMA_HACK		\
	warns								\
	(nil, nil)							\
	body								\
	_Pragma("GCC diagnostic pop")
#  define GCC_WARNING(warn)						\
	(t, GCC diagnostic ignored warn) MLIB__PRAGMA_HACK
#  define MUFFLE_WARNINGS_DECL(warns, body)				\
	MLIB__MUFFLE_WARNINGS(warns, body)
#  define MUFFLE_WARNINGS_EXPR(warns, body)				\
	__extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
#  define MUFFLE_WARNINGS_STMT(warns, body)				\
	do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)
#endif

/* --- Fallback definitions, mostly trivial --- */

/* --- @DISCARD@ --- *
 *
 * Arguments:	@x@ = a function call
 *
 * Returns:	---
 *
 * Use:		Explicitly discard the result of @x@.  This counteracts a
 *		@MUST_CHECK@ attribute on the called function.
 */

#ifndef DISCARD
#  define DISCARD(x) do if (x); while (0)
#endif

/* --- @IGNORE@ --- *
 *
 * Arguments:	@x@ = any expression
 *
 * Returns:	---
 *
 * Use:		Ignore the value of @x@, overriding compiler warnings.
 */

#ifndef IGNORE
#  define IGNORE(x) ((void)(x))
#endif

/* --- @LAUNDER@ --- *
 *
 * Arguments:	@x@ = some integer expression
 *
 * Returns:	@x@.
 *
 * Use:		Causes a compiler to know nothing about the value of @x@,
 *		even if it looks obvious, e.g., it's a constant.
 */

#ifndef LAUNDER
#  define LAUNDER(x) (x)
#endif

/* --- @ADMIRE@, @ADMIRE_BUF@ --- *
 *
 * Arguments:	@x@ = some scalar expression
 *		@const void *p@, @size_t sz@ = a pointer and length
 *
 * Returns:	---
 *
 * Use:		Ensures that the compiler generates code to compute @x@ or
 *		the contents of the buffer at @p@.
 */

#ifndef ADMIRE
#  define ADMIRE(x) ((void)(x))
#endif
#ifndef ADMIRE_BUF
#  define ADMIRE_BUF(p, sz) ((void)(p), (void)(sz))
#endif

/* --- @RELAX@ --- *
 *
 * Arguments:	---
 *
 * Returns:	---
 *
 * Use:		Does nothing, but the compiler doesn't know that.
 */

#ifndef RELAX
#  define RELAX
#endif

/* --- @DEPRECATED@, @NORETURN@, @IGNORABLE@, @MUST_CHECK@ --- *
 *
 * Use:		These are (mostly) function attributes; write them among the
 *		declaration specifiers for a function definition or
 *		declaration.  These may not do anything, but the intended
 *		behaviour is as follows.
 *
 *		  * @DEPRECATED(msg)@ -- report a warning, quoting the string
 *		    literal @msg@, if the function is called.
 *
 *		  * @NORETURN@ -- promise that the function doesn't return to
 *		    its caller: either it kills the process, or it performs
 *		    some nonlocal transfer.
 *
 *		  * @IGNORABLE@ -- the item (which might be data rather than
 *		    a function) might not be referred to, but that's OK:
 *		    don't warn about it.
 *
 *		  @ @MUST_CHECK@ -- warn if the return value of a function is
 *		    ignored.  Use @DISCARD@ if you really don't care.
 */

#ifndef DEPRECATED
#  define DEPRECATED(msg)
#endif

#ifndef NORETURN
#  define NORETURN
#endif

#ifndef IGNORABLE
#  define IGNORABLE
#endif

#ifndef MUST_CHECK
#  define MUST_CHECK
#endif

/* --- @PRINTF_LIKE@, @SCANF_LIKE@, @EXECL_LIKE@ --- *
 *
 * Arguments:	@int fmtix@ = format string argument index (starting from 1)
 *		@int argix@ = variable format argument tail index (starting
 *			from 1)
 *		@int ntrail@ = number of arguments following terminator
 *
 * Use:		These are function attributes.  Again, they might not do
 *		anything at all.  By intention, they give the compiler
 *		information about a variadic function's arguments, so that it
 *		can warn about misuse.
 *
 *		  * @PRINTF_LIKE@ -- the function takes a @printf@-style
 *		    format string as argument @fmtix@ and an argument tail
 *		    (which may be empty) beginning with argument @argix@.
 *
 *		  * @SCANF_LIKE@ -- the function takes a @scanf@-style
 *		    format string as argument @fmtix@ and an argument tail
 *		    (which may be empty) beginning with argument @argix@.
 *
 *		  * @EXECL_LIKE@ -- the function takes a sequence of pointer
 *		    arguments terminated by a null pointer, followed by
 *		    @ntrail@ further arguments.
 */

#ifndef PRINTF_LIKE
#  define PRINF_LIKE(fmtix, argix)
#endif

#ifndef SCANF_LIKE
#  define SCANF_LIKE(fmtix, argix)
#endif

#ifndef EXECL_LIKE
#  define EXECL_LIKE(ntrail)
#endif

/* --- @MUFFLE_WARNINGS_...@ --- *
 *
 * Arguments:	@warns@ = a sequence of @..._WARNING@ calls (see below)
 *		@body@ = some program text
 *
 * Use:		Muffle specific warnings within the program text.
 *
 *		For @MUFFLE_WARNINGS_DECL@, the program text is a
 *		declaration; for @MUFFLE_WARNINGS_EXPR@, it is an expression,
 *		and for @MUFFLE_WARNINGS_STMT@, it is a statement.
 *
 *		The warnings to be muffled are given as a list of
 *		@..._WARNING@ macros, with no separators.  The list can
 *		list warnings from multiple different compilers: entries for
 *		irrelevant compilers will be ignored.
 */

#ifndef MUFFLE_WARNINGS_DECL
#  define MUFFLE_WARNINGS_DECL(warns, body) body
#endif

#ifndef MUFFLE_WARNINGS_EXPR
#  define MUFFLE_WARNINGS_EXPR(warns, body) (body)
#endif

#ifndef MUFFLE_WARNINGS_STMT
#  define MUFFLE_WARNINGS_STMT(warns, body) do { body } while (0)
#endif

/* --- @GCC_WARNING@ --- *
 *
 * Arguments:	@warn@ = a string literal naming a warning, with `%|-W...|%'
 *			prefix
 *
 * Use:		Names a GCC warning: use within @MUFFLE_WARNINGS_...@.
 *
 *		Note that GCC's warning suppression is very buggy.
 */

#ifndef GCC_WARNING
#  define GCC_WARNING(warn)
#endif

/* --- @CLANG_WARNING@ --- *
 *
 * Arguments:	@warn@ = a string literal naming a warning, with `%|-W...|%'
 *			prefix
 *
 * Use:		Names a Clang warning: use within @MUFFLE_WARNINGS_...@.
 */

#ifndef CLANG_WARNING
#  define CLANG_WARNING(warn)
#endif

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif
Commit	Line	Data
14d7100d	1	/* --c--
16139d88	2	*
16139d88	3	* Handy macros
14d7100d	4	*
	5	* (c) 2003 Straylight/Edgeware
	6	*/
	7
d4efbcd9	8	/----- Licensing notice --------------------------------------------------
14d7100d	9	*
	10	* This file is part of the mLib utilities library.
	11	*
	12	* mLib is free software; you can redistribute it and/or modify
	13	* it under the terms of the GNU Library General Public License as
	14	* published by the Free Software Foundation; either version 2 of the
	15	* License, or (at your option) any later version.
d4efbcd9	16	*
14d7100d	17	* mLib is distributed in the hope that it will be useful,
	18	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	19	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	20	* GNU Library General Public License for more details.
d4efbcd9	21	*
14d7100d	22	* You should have received a copy of the GNU Library General Public
	23	* License along with mLib; if not, write to the Free
	24	* Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
	25	* MA 02111-1307, USA.
	26	*/
	27
14d7100d	28	#ifndef MLIB_MACROS_H
	29	#define MLIB_MACROS_H
	30
	31	#ifdef __cplusplus
	32	extern "C" {
	33	#endif
	34
33e3ac90 MW	35	/----- Header files ------------------------------------------------------/
33e3ac90 MW	36
f50c1365 MW	37	#include <assert.h>
f50c1365 MW	38
33e3ac90 MW	39	#ifndef MLIB_COMPILER_H
	40	# include "compiler.h"
	41	#endif
	42
3832000d	43	/----- Miscellaneous utility macros --------------------------------------/
14d7100d	44
6e683a79 MW	45	/* --- @N@ --- *
	46	*
	47	* Arguments: @type v[]@ = an actual array, not a pointer
	48	*
	49	* Returns: The number of elements in @v@.
	50	*/
	51
c066b1ff	52	#define N(v) (sizeof(v)/sizeof(*(v)))
14d7100d	53
6e683a79 MW	54	/* --- @STR@ --- *
	55	*
	56	* Arguments: @x@ = some tokens
	57	*
	58	* Returns: A string literal containing the macro-expanded text of @x@.
	59	*/
	60
16139d88	61	#define MLIB__STR(x) #x
	62	#define STR(x) MLIB__STR(x)
	63
6e683a79 MW	64	/* --- @GLUE@ --- *
	65	*
	66	* Arguments: @x, y@ = two sequences of tokens
	67	*
	68	* Returns: A single token formed by gluing together the macro-expansions
	69	* of @x@ and @y@.
	70	*/
	71
16139d88	72	#define MLIB__GLUE(x, y) x##y
	73	#define GLUE(x, y) MLIB__GLUE(x, y)
	74
6e683a79 MW	75	/* --- @STATIC_ASSERT@ --- *
	76	*
	77	* Arguments: @int cond@ = a condition
	78	* @msg@ = a string literal message
	79	*
	80	* Returns: ---
	81	*
	82	* Use: Fail at compile time unless @cond@ is nonzero. The failure
	83	* might report @msg@.
	84	*/
	85
f50c1365	86	#ifdef static_assert
dd65cf2d	87	# define STATIC_ASSERT(cond, msg) static_assert(!!(cond), msg)
f50c1365 MW	88	#else
f50c1365 MW	89	# define STATIC_ASSERT(cond, msg) \
b1a20bee	90	IGNORABLE extern char static_assert_failed[1 - 2*!(cond)]
f50c1365 MW	91	#endif
f50c1365 MW	92
b1a20bee MW	93	/* --- @CHECK_TYPE@ ---
	94	*
	95	* Arguments: @expty@ = expected type of @x@
	96	* @expty x@ = some object
	97	*
	98	* Returns: Integer zero.
	99	*
	100	* Use: Cause a compile-time failure unless the type of @x@ is
	101	* assignment-compatible with @expty@.
	102	*/
	103
	104	#define CHECK_TYPE(expty, x) (!sizeof((expty )0 = (x)))
	105
	106	/* --- @CONVERT_CAREFULLY@ ---
	107	*
	108	* Arguments: @newty@ = new type for the result
	109	* @expty@ = expected type of @x@
	110	* @expty x@ = some object
	111	*
	112	* Returns: @x@, but coerced to type @newty@.
	113	*
	114	* Use: Like @(newty)x@, except that it checks at compile-time that
	115	* @x@ is at least assignment-compatible with type @expty@
	116	* before trying.
	117	*/
	118
	119	#define CONVERT_CAREFULLY(newty, expty, x) \
	120	(CHECK_TYPE(expty, x) + (/unconst unvolatile/ newty)(x))
	121
	122	/* --- @UNCONST@, @UNVOLATILE@, @UNQUALIFY@ --- *
	123	*
	124	* Arguments: @type@ = a type name
	125	* @type *p@ = a pointer
	126	*
	127	* Returns: @p@, but without @const@, @volatile@ or both qualifiers.
	128	*
	129	* Use: Strips qualifiers from pointer types.
	130	*
	131	* The @UNCONST@ macro strips @const@. It checks that @p@
	132	* has type `pointer to @type@ or @const type@'; if not, a
	133	* compile-time error results. Otherwise, it returns the value
	134	* of @p@, converted to `pointer to (non-constant) @type@'. It
	135	* will not silently strip a @volatile@ qualifier.
	136	*
	137	* The @UNVOLATILE@ macro is similar, except that it strips
	138	* @volatile@ instead of @const@. The @UNQUALIFY@ macro strips
	139	* both qualifiers.
	140	*/
	141
	142	#define UNCONST(type, p) CONVERT_CAREFULLY(type , const type , p)
	143	#define UNVOLATILE(type, p) CONVERT_CAREFULLY(type , volatile type , p)
	144	#define UNQUALIFY(type, p) \
	145	CONVERT_CAREFULLY(type , const volatile type , p)
	146
6e683a79 MW	147	/* --- @COMMA@ --- *
	148	*
	149	* Arguments: ---
	150	*
	151	* Returns: A `%\|,\|%' token, which can be usefully passed to macros to
	152	* avoid argument splitting.
	153	*/
	154
e6591bec MW	155	#define COMMA ,
e6591bec MW	156
36188114 MW	157	/----- String and character hacks ----------------------------------------/
36188114 MW	158
6e683a79 MW	159	/* --- @IS...@ --- *
	160	*
	161	* Arguments: @int ch@ = a character code, but not @EOF@
	162	*
	163	* Returns: Nonzero if @ch@ is in the relevant @<ctype.h>@ category.
	164	*
	165	* Use: Classifies characters, but safely even if characters are
	166	* signed.
	167	*
	168	* There is a macro for each of the @<ctype.h>@ @is...@
	169	* functions.
	170	*/
	171
36188114 MW	172	#define CTYPE_HACK(func, ch) (func((unsigned char)(ch)))
	173
	174	#define ISALNUM(ch) CTYPE_HACK(isalnum, ch)
	175	#define ISALPHA(ch) CTYPE_HACK(isalpha, ch)
	176	#define ISASCII(ch) CTYPE_HACK(isascii, ch)
	177	#define ISBLANK(ch) CTYPE_HACK(isblank, ch)
	178	#define ISCNTRL(ch) CTYPE_HACK(iscntrl, ch)
	179	#define ISDIGIT(ch) CTYPE_HACK(isdigit, ch)
	180	#define ISGRAPH(ch) CTYPE_HACK(isgraph, ch)
	181	#define ISLOWER(ch) CTYPE_HACK(islower, ch)
	182	#define ISPRINT(ch) CTYPE_HACK(isprint, ch)
	183	#define ISPUNCT(ch) CTYPE_HACK(ispunct, ch)
	184	#define ISSPACE(ch) CTYPE_HACK(isspace, ch)
	185	#define ISUPPER(ch) CTYPE_HACK(isupper, ch)
	186	#define ISXDIGIT(ch) CTYPE_HACK(isxdigit, ch)
	187
6e683a79 MW	188	/* --- @TO...@ --- *
	189	*
	190	* Arguments: @int ch@ = a character code, but not @EOF@
	191	*
	192	* Returns: The converted character code.
	193	*
	194	* Use: Converts characters, but safely even if characters are
	195	* signed.
	196	*
	197	* There is a macro for each of the @<ctype.h>@ @to...@
	198	* functions.
	199	*/
	200
36188114 MW	201	#define TOASCII(ch) CTYPE_HACK(toascii, ch)
	202	#define TOLOWER(ch) CTYPE_HACK(tolower, ch)
	203	#define TOUPPER(ch) CTYPE_HACK(toupper, ch)
	204
6e683a79 MW	205	/* --- @MEMCMP@, @STRCMP@, @STRNCMP@ --- *
	206	*
	207	* Arguments: @const type x, y@ = pointers to strings
	208	* @op@ = a relational operator symbol
	209	* @size_t n@ = length of the strings
	210	*
	211	* Returns: Nonzero if the relationship between the strings satisfies the
	212	* operator @op@, otherwise zero.
	213	*
	214	* Use: These macros mitigate the author's frequent error of failing
	215	* to compare the result of the underlying standard functions
	216	* against zero, effectively reversing the sense of an intended
	217	* test for equality.
	218	*/
	219
36188114 MW	220	#define MEMCMP(x, op, y, n) (memcmp((x), (y), (n)) op 0)
	221	#define STRCMP(x, op, y) (strcmp((x), (y)) op 0)
	222	#define STRNCMP(x, op, y, n) (strncmp((x), (y), (n)) op 0)
	223
6e683a79	224	/----- Compiler-specific definitions -------------------------------------/
3832000d	225
6e683a79 MW	226	/* The descriptions of these are given below, with the fallback
	227	* definitions.
	228	*/
3832000d	229
ff3d3f01	230	#if GCC_VERSION_P(2, 5) \|\| CLANG_VERSION_P(3, 3)
2eea6973 MW	231	# define NORETURN __attribute__((__noreturn__))
	232	# define PRINTF_LIKE(fix, aix) __attribute__((__format__(printf, fix, aix)))
	233	# define SCANF_LIKE(fix, aix) __attribute__((__format__(scanf, fix, aix)))
	234	# define IGNORABLE __attribute__((__unused__))
d94956b5 MW	235	#endif
d94956b5 MW	236
8c470f2a MW	237	#if GCC_VERSION_P(3, 4) \|\| CLANG_VERSION_P(3, 3)
	238	# define MUST_CHECK __attribute__((__warn_unused_result__))
	239	#endif
	240
ff3d3f01	241	#if GCC_VERSION_P(4, 5) \|\| CLANG_VERSION_P(3, 3)
2eea6973	242	# define DEPRECATED(msg) __attribute__((__deprecated__(msg)))
d94956b5	243	#elif GCC_VERSION_P(3, 1)
2eea6973	244	# define DEPRECATED(msg) __attribute__((__deprecated__))
d94956b5 MW	245	#endif
d94956b5 MW	246
ff3d3f01	247	#if GCC_VERSION_P(4, 0) \|\| CLANG_VERSION_P(3, 3)
2eea6973	248	# define EXECL_LIKE(ntrail) __attribute__((__sentinel__(ntrail)))
d94956b5 MW	249	#endif
d94956b5 MW	250
c91413e6	251	#if GCC_VERSION_P(2, 7) \|\| CLANG_VERSION_P(0, 0)
b64eb60f MW	252	# define LAUNDER(x) \
b64eb60f MW	253	({ __typeof__(x) _y; __asm__("" : "=g"(_y) : "0"(x)); _y; })
b1a20bee MW	254	# define ADMIRE(x) \
	255	({ __asm__("" : : "g"(x)); })
	256	# define ADMIRE_BUF(p, sz) \
	257	({ __asm__("" : : "g"(p), "g"(sz)); })
b64eb60f MW	258	# define RELAX do __asm__ __volatile__("" ::: "memory"); while (0)
	259	#endif
	260
ff3d3f01 MW	261	#if CLANG_VERSION_P(3, 3)
	262
	263	# define MLIB__PRAGMA_HACK(x) _Pragma(#x)
	264	# define MLIB__MUFFLE_WARNINGS(warns, body) \
	265	_Pragma("clang diagnostic push") \
	266	warns \
	267	body \
	268	_Pragma("clang diagnostic pop")
	269	# define CLANG_WARNING(warn) \
	270	MLIB__PRAGMA_HACK(clang diagnostic ignored warn)
	271	# define MUFFLE_WARNINGS_DECL(warns, body) \
	272	MLIB__MUFFLE_WARNINGS(warns, body)
	273	# define MUFFLE_WARNINGS_EXPR(warns, body) \
	274	__extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
	275	# define MUFFLE_WARNINGS_STMT(warns, body) \
	276	do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)
	277
c91413e6 MW	278	#endif
	279
	280	#if GCC_VERSION_P(4, 6)
d94956b5 MW	281
	282	/* --- Diagnostic suppression in GCC: a tale of woe --- *
	283	*
	284	* This is extremely unpleasant, largely as a result of bugs in the GCC
	285	* preprocessor's handling of @_Pragma@. The fundamental problem is
	286	* that it's the preprocessor, and not the compiler proper, which
	287	* detects @_Pragma@, emitting @#pragma@ lines into its output; and it
	288	* does it during macro expansion, even if the macro is being expanded
	289	* during argument collection. Since arguments are expanded before
	290	* replacing the macro's invocation with its body, a pragma in an
	291	* argument will be emitted %%\emph{before}%% any pragmata in the body,
	292	* even if they appear before the argument in the body -- and even if
	293	* the argument doesn't actually appear anywhere at all in the body.
	294	*
	295	* Another, rather less significant, problem is that @_Pragma@'s
	296	* argument is a single string literal, recognized in translation phase
	297	* 4, before string-literal concatenation in phase 6, so we must build
	298	* pragma bodies as token lists and then stringify them.
	299	*
	300	* As a result, we need some subterfuge here. The @MLIB__PRAGMA_HACK@
	301	* macro issues a @_Pragma@ on its argument token list, which it
	302	* stringifies; this deals with the second problem. The first is
	303	* trickier: we must delay expansion of @MLIB__PRAGMA_HACK@ from the
	304	* argument collection phase to the body rescanning phase, and we do
	305	* this by splitting the invocations between @GCC_WARNING@ macro calls:
	306	* the name is left hanging from the previous call (or from
	307	* @MLIB__MUFFLE_WARNINGS@, in the first case) and the body is supplied
	308	* by @GCC_WARNING@, which also supplies the next @MLIB__PRAGMA_HACK@.
	309	* The remaining problem is to make sure we can dispose of the final
	310	* trailing @MLIB__PRAGMA_HACK@ harmlessly, which we do by introducing
	311	* an extra argument @emitp@, which may be either @t@ or @nil@; this
	312	* dispatches to an appropriate helper macro by means of token-pasting.
	313	*
	314	* I'm so sorry.
	315	*/
	316
	317	# define MLIB__PRAGMA_HACK_t(x) _Pragma(#x)
	318	# define MLIB__PRAGMA_HACK_nil(x)
	319	# define MLIB__PRAGMA_HACK(emitp, x) MLIB__PRAGMA_HACK_##emitp(x)
	320	# define MLIB__MUFFLE_WARNINGS(warns, body) \
3832000d MW	321	_Pragma("GCC diagnostic push") MLIB__PRAGMA_HACK \
	322	warns \
	323	(nil, nil) \
	324	body \
	325	_Pragma("GCC diagnostic pop")
d94956b5	326	# define GCC_WARNING(warn) \
3832000d	327	(t, GCC diagnostic ignored warn) MLIB__PRAGMA_HACK
d94956b5	328	# define MUFFLE_WARNINGS_DECL(warns, body) \
3832000d	329	MLIB__MUFFLE_WARNINGS(warns, body)
d94956b5	330	# define MUFFLE_WARNINGS_EXPR(warns, body) \
3832000d	331	__extension__ ({ MLIB__MUFFLE_WARNINGS(warns, (body);) })
d94956b5	332	# define MUFFLE_WARNINGS_STMT(warns, body) \
3832000d	333	do { MLIB__MUFFLE_WARNINGS(warns, body) } while (0)
3832000d MW	334	#endif
	335
	336	/* --- Fallback definitions, mostly trivial --- */
	337
6e683a79 MW	338	/* --- @DISCARD@ --- *
	339	*
	340	* Arguments: @x@ = a function call
	341	*
	342	* Returns: ---
	343	*
	344	* Use: Explicitly discard the result of @x@. This counteracts a
	345	* @MUST_CHECK@ attribute on the called function.
	346	*/
3832000d MW	347
	348	#ifndef DISCARD
	349	# define DISCARD(x) do if (x); while (0)
	350	#endif
	351
6e683a79 MW	352	/* --- @IGNORE@ --- *
	353	*
	354	* Arguments: @x@ = any expression
	355	*
	356	* Returns: ---
	357	*
	358	* Use: Ignore the value of @x@, overriding compiler warnings.
	359	*/
	360
3832000d MW	361	#ifndef IGNORE
	362	# define IGNORE(x) ((void)(x))
	363	#endif
	364
6e683a79 MW	365	/* --- @LAUNDER@ --- *
	366	*
	367	* Arguments: @x@ = some integer expression
	368	*
	369	* Returns: @x@.
	370	*
	371	* Use: Causes a compiler to know nothing about the value of @x@,
	372	* even if it looks obvious, e.g., it's a constant.
	373	*/
3832000d	374
6e683a79 MW	375	#ifndef LAUNDER
6e683a79 MW	376	# define LAUNDER(x) (x)
3832000d MW	377	#endif
3832000d MW	378
b1a20bee MW	379	/* --- @ADMIRE@, @ADMIRE_BUF@ --- *
	380	*
	381	* Arguments: @x@ = some scalar expression
	382	* @const void *p@, @size_t sz@ = a pointer and length
	383	*
	384	* Returns: ---
	385	*
	386	* Use: Ensures that the compiler generates code to compute @x@ or
	387	* the contents of the buffer at @p@.
	388	*/
	389
	390	#ifndef ADMIRE
	391	# define ADMIRE(x) ((void)(x))
	392	#endif
	393	#ifndef ADMIRE_BUF
	394	# define ADMIRE_BUF(p, sz) ((void)(p), (void)(sz))
	395	#endif
	396
6e683a79 MW	397	/* --- @RELAX@ --- *
	398	*
	399	* Arguments: ---
	400	*
	401	* Returns: ---
	402	*
	403	* Use: Does nothing, but the compiler doesn't know that.
	404	*/
3832000d	405
6e683a79 MW	406	#ifndef RELAX
6e683a79 MW	407	# define RELAX
3832000d MW	408	#endif
3832000d MW	409
6e683a79 MW	410	/* --- @DEPRECATED@, @NORETURN@, @IGNORABLE@, @MUST_CHECK@ --- *
	411	*
	412	* Use: These are (mostly) function attributes; write them among the
	413	* declaration specifiers for a function definition or
	414	* declaration. These may not do anything, but the intended
	415	* behaviour is as follows.
	416	*
	417	* * @DEPRECATED(msg)@ -- report a warning, quoting the string
	418	* literal @msg@, if the function is called.
	419	*
	420	* * @NORETURN@ -- promise that the function doesn't return to
	421	* its caller: either it kills the process, or it performs
	422	* some nonlocal transfer.
	423	*
	424	* * @IGNORABLE@ -- the item (which might be data rather than
	425	* a function) might not be referred to, but that's OK:
	426	* don't warn about it.
	427	*
	428	* @ @MUST_CHECK@ -- warn if the return value of a function is
	429	* ignored. Use @DISCARD@ if you really don't care.
	430	*/
	431
	432	#ifndef DEPRECATED
	433	# define DEPRECATED(msg)
3832000d MW	434	#endif
3832000d MW	435
59eae7fd MW	436	#ifndef NORETURN
	437	# define NORETURN
	438	#endif
	439
3832000d MW	440	#ifndef IGNORABLE
	441	# define IGNORABLE
	442	#endif
	443
8c470f2a MW	444	#ifndef MUST_CHECK
	445	# define MUST_CHECK
	446	#endif
	447
6e683a79 MW	448	/* --- @PRINTF_LIKE@, @SCANF_LIKE@, @EXECL_LIKE@ --- *
	449	*
	450	* Arguments: @int fmtix@ = format string argument index (starting from 1)
	451	* @int argix@ = variable format argument tail index (starting
	452	* from 1)
	453	* @int ntrail@ = number of arguments following terminator
	454	*
	455	* Use: These are function attributes. Again, they might not do
	456	* anything at all. By intention, they give the compiler
	457	* information about a variadic function's arguments, so that it
	458	* can warn about misuse.
	459	*
	460	* * @PRINTF_LIKE@ -- the function takes a @printf@-style
	461	* format string as argument @fmtix@ and an argument tail
	462	* (which may be empty) beginning with argument @argix@.
	463	*
	464	* * @SCANF_LIKE@ -- the function takes a @scanf@-style
	465	* format string as argument @fmtix@ and an argument tail
	466	* (which may be empty) beginning with argument @argix@.
	467	*
	468	* * @EXECL_LIKE@ -- the function takes a sequence of pointer
	469	* arguments terminated by a null pointer, followed by
	470	* @ntrail@ further arguments.
	471	*/
	472
	473	#ifndef PRINTF_LIKE
	474	# define PRINF_LIKE(fmtix, argix)
b64eb60f MW	475	#endif
b64eb60f MW	476
6e683a79 MW	477	#ifndef SCANF_LIKE
6e683a79 MW	478	# define SCANF_LIKE(fmtix, argix)
b64eb60f MW	479	#endif
b64eb60f MW	480
6e683a79 MW	481	#ifndef EXECL_LIKE
	482	# define EXECL_LIKE(ntrail)
	483	#endif
	484
	485	/* --- @MUFFLE_WARNINGS_...@ --- *
	486	*
	487	* Arguments: @warns@ = a sequence of @..._WARNING@ calls (see below)
	488	* @body@ = some program text
	489	*
	490	* Use: Muffle specific warnings within the program text.
	491	*
	492	* For @MUFFLE_WARNINGS_DECL@, the program text is a
	493	* declaration; for @MUFFLE_WARNINGS_EXPR@, it is an expression,
	494	* and for @MUFFLE_WARNINGS_STMT@, it is a statement.
	495	*
	496	* The warnings to be muffled are given as a list of
	497	* @..._WARNING@ macros, with no separators. The list can
	498	* list warnings from multiple different compilers: entries for
	499	* irrelevant compilers will be ignored.
	500	*/
	501
	502	#ifndef MUFFLE_WARNINGS_DECL
	503	# define MUFFLE_WARNINGS_DECL(warns, body) body
	504	#endif
	505
	506	#ifndef MUFFLE_WARNINGS_EXPR
	507	# define MUFFLE_WARNINGS_EXPR(warns, body) (body)
	508	#endif
	509
	510	#ifndef MUFFLE_WARNINGS_STMT
	511	# define MUFFLE_WARNINGS_STMT(warns, body) do { body } while (0)
	512	#endif
	513
	514	/* --- @GCC_WARNING@ --- *
	515	*
	516	* Arguments: @warn@ = a string literal naming a warning, with `%\|-W...\|%'
	517	* prefix
	518	*
	519	* Use: Names a GCC warning: use within @MUFFLE_WARNINGS_...@.
	520	*
	521	* Note that GCC's warning suppression is very buggy.
	522	*/
	523
3832000d MW	524	#ifndef GCC_WARNING
	525	# define GCC_WARNING(warn)
	526	#endif
	527
6e683a79 MW	528	/* --- @CLANG_WARNING@ --- *
	529	*
	530	* Arguments: @warn@ = a string literal naming a warning, with `%\|-W...\|%'
	531	* prefix
	532	*
	533	* Use: Names a Clang warning: use within @MUFFLE_WARNINGS_...@.
	534	*/
	535
ff3d3f01 MW	536	#ifndef CLANG_WARNING
	537	# define CLANG_WARNING(warn)
	538	#endif
	539
14d7100d	540	/----- That's all, folks -------------------------------------------------/
	541
	542	#ifdef __cplusplus
	543	}
	544	#endif
	545
	546	#endif