utils/macros.h: Add <ctype.h> and `foocmp' helper macros.

[mLib] / utils / macros.3

diff --git a/utils/macros.3 b/utils/macros.3
index a2a9003..2d17fa6 100644 (file)
--- a/utils/macros.3
+++ b/utils/macros.3
@@ -5,6 +5,26 @@ macros \- useful macros
 .\" @N
 .\" @STR
 .\" @GLUE
 .\" @N
 .\" @STR
 .\" @GLUE

+.\" @STATIC_ASSERT
+.\" @ISALNUM
+.\" @ISALPHA
+.\" @ISASCII
+.\" @ISBLANK
+.\" @ISCNTRL
+.\" @ISDIGIT
+.\" @ISGRAPH
+.\" @ISLOWER
+.\" @ISPRINT
+.\" @ISPUNCT
+.\" @ISSPACE
+.\" @ISUPPER
+.\" @ISXDIGIT
+.\" @TOASCII
+.\" @TOLOWER
+.\" @TOUPPER
+.\" @MEMCMP
+.\" @STRCMP
+.\" @STRNCMP

 .\" @DISCARD
 .\" @IGNORE
 .\" @DEPRECATED
 .\" @DISCARD
 .\" @IGNORE
 .\" @DEPRECATED


@@ -24,6 +44,28 @@ macros \- useful macros
 .BI "size_t N(" array ");"
 .BI "STR(" tokens\fR... ")"
 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"
 .BI "size_t N(" array ");"
 .BI "STR(" tokens\fR... ")"
 .BI "GLUE(" tokens\fR... ", " tokens\fR... ")"

+.BI "STATIC_ASSERT(" cond ", " msg ");"
+
+.BI "ISALNUM(int " ch ");"
+.BI "ISALPHA(int " ch ");"
+.BI "ISASCII(int " ch ");"
+.BI "ISBLANK(int " ch ");"
+.BI "ISCNTRL(int " ch ");"
+.BI "ISDIGIT(int " ch ");"
+.BI "ISGRAPH(int " ch ");"
+.BI "ISLOWER(int " ch ");"
+.BI "ISPRINT(int " ch ");"
+.BI "ISPUNCT(int " ch ");"
+.BI "ISSPACE(int " ch ");"
+.BI "ISUPPER(int " ch ");"
+.BI "ISXDIGIT(int " ch ");"
+.BI "TOASCII(int " ch ");"
+.BI "TOLOWER(int " ch ");"
+.BI "TOUPPER(int " ch ");"
+
+.BI "MEMCMP(const void *" x ", " op ", const void *" y ", size_t " n ");"
+.BI "STRCMP(const char *" x ", " op ", const char *" y ");"
+.BI "STRNCMP(const char *" x ", " op ", const char *" y ", size_t " n ");"

 
 .BI "void DISCARD(" scalar ");"
 .BI "void IGNORE(" variable ");"
 
 .BI "void DISCARD(" scalar ");"
 .BI "void IGNORE(" variable ");"


@@ -64,6 +106,52 @@ and the result of gluing these tokens together must be valid
 preprocessing token.
 .PP
 The
 preprocessing token.
 .PP
 The

+.B STATIC_ASSERT
+causes compilation to fail if the integer constant expression
+.I cond
+evaluates to zero.  This macro uses the C11
+.B static_assert
+declaration if available, and the
+.I msg
+will be reported in the compiler's diagnostic messsage; otherwise, the macro
+falls back to a somewhat ugly hack which currently ignores the
+.IR msg .
+.PP
+The
+.BR IS ...\&
+and
+.BR TO ...\&
+macros are wrappers around the corresponding standard
+.B <ctype.h>
+macros with the corresponding lowercase names.  They take care of
+forcing the character argument
+.I ch
+to
+.BR "unsigned char" :
+this conversion is necessary on platforms with signed
+.B char
+to avoid passing negative values into the standard macros.
+.PP
+The
+.BR MEMCMP ,
+.BR STRCMP ,
+and
+.B STRNCMP
+macros are wrappers around the standard
+.B <string.h>
+functions with the corresponding lowercase names.  They take an
+additional argument
+.I op
+which is a equality or ordering operator (e.g.,
+.B ==
+or
+.BR > )
+inserted between the two operands.  The standard functions return a
+false value if and only if the operands are equal, which is
+counterintuitive and leads to mistakes; requiring an explicit relational
+operator should reduce the number of such mistakes.
+.PP
+The

 .B DISCARD
 macro discards its argument, which must be of some scalar type.  This
 can be useful in muffling warnings about ignoring return codes in cases
 .B DISCARD
 macro discards its argument, which must be of some scalar type.  This
 can be useful in muffling warnings about ignoring return codes in cases