X-Git-Url: https://git.distorted.org.uk/~mdw/mLib/blobdiff_plain/c418910f63a882d53d76f0711fa79eff7387d9e0..8c470f2a28273197fbf0939a7bceb3d0d0a6df7d:/utils/macros.3

diff --git a/utils/macros.3 b/utils/macros.3
index bd8cbb6..d481a47 100644
--- a/utils/macros.3
+++ b/utils/macros.3
@@ -5,19 +5,40 @@ macros \- useful macros
 .\" @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
 .\" @EXECL_LIKE
 .\" @IGNORABLE
+.\" @MUST_CHECK
 .\" @NORETURN
 .\" @PRINTF_LIKE
 .\" @SCANF_LIKE
 .\" @MUFFLE_WARNINGS_DECL
 .\" @MUFFLE_WARNINGS_EXPR
 .\" @MUFFLE_WARNINGS_STMT
-.\" @GCC_VERSION_P
 .\" @GCC_WARNING
+.\" @CLANG_WARNING
 .SH SYNOPSIS
 .nf
 .B "#include <mLib/macros.h>"
@@ -25,6 +46,28 @@ macros \- useful macros
 .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 ");"
@@ -32,6 +75,7 @@ macros \- useful macros
 .BI "DEPRECATED(" msg ")"
 .BI "EXECL_LIKE(" ntrail ")"
 .BI "IGNORABLE"
+.BI "MUST_CHECK"
 .BI "NORETURN"
 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"
@@ -40,7 +84,6 @@ macros \- useful macros
 .BI "MUFFLE_WARNINGS_EXPR(" warns ", " expr ")"
 .BI "MUFFLE_WARNINGS_STMT(" warns ", " stmt ")"
 
-.BI "int GCC_VERSION_P(" maj ", " min ");"
 .BI "GCC_WARNING(" option ")"
 .BI "CLANG_WARNING(" option ")"
 .fi
@@ -66,6 +109,52 @@ and the result of gluing these tokens together must be valid
 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
@@ -106,6 +195,12 @@ need not be used.  This may muffle warnings about leaving the marked
 definition unused.
 .PP
 A function marked as
+.B MUST_CHECK
+returns an important value: a warning may be issued if a caller
+ignores the value.  The return type must not be
+.BR void .
+.PP
+A function marked as
 .B NORETURN
 must not return.  It must have return type
 .BR void .
@@ -168,7 +263,15 @@ naming a GCC warning option, e.g.,
 The
 .B CLANG_WARNING
 is similar, except that it works with the Clang compiler.
+.PP
+Note that including
+.B <mLib/macros.h>
+also defines the compiler-test macros in
+.BR <mLib/compiler.h>;
+see
+.BR compiler (3).
 .SH "SEE ALSO"
-.BR mLib (3).
+.BR mLib (3),
+.BR compiler (3).
 .SH "AUTHOR"
 Mark Wooding, <mdw@distorted.org.uk>