utils/macros.h: Add `MUST_CHECK', so return codes aren't ignored.

[mLib] / utils / macros.3

diff --git a/utils/macros.3 b/utils/macros.3
index a2a9003..d481a47 100644 (file)
--- a/utils/macros.3
+++ b/utils/macros.3
@@ -5,11 +5,32 @@ 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
 .\" @EXECL_LIKE
 .\" @IGNORABLE
 .\" @DISCARD
 .\" @IGNORE
 .\" @DEPRECATED
 .\" @EXECL_LIKE
 .\" @IGNORABLE

+.\" @MUST_CHECK

 .\" @NORETURN
 .\" @PRINTF_LIKE
 .\" @SCANF_LIKE
 .\" @NORETURN
 .\" @PRINTF_LIKE
 .\" @SCANF_LIKE


@@ -17,6 +38,7 @@ macros \- useful macros
 .\" @MUFFLE_WARNINGS_EXPR
 .\" @MUFFLE_WARNINGS_STMT
 .\" @GCC_WARNING
 .\" @MUFFLE_WARNINGS_EXPR
 .\" @MUFFLE_WARNINGS_STMT
 .\" @GCC_WARNING

+.\" @CLANG_WARNING

 .SH SYNOPSIS
 .nf
 .B "#include <mLib/macros.h>"
 .SH SYNOPSIS
 .nf
 .B "#include <mLib/macros.h>"


@@ -24,6 +46,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 ");"


@@ -31,6 +75,7 @@ macros \- useful macros
 .BI "DEPRECATED(" msg ")"
 .BI "EXECL_LIKE(" ntrail ")"
 .BI "IGNORABLE"
 .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 ")"
 .BI "NORETURN"
 .BI "PRINTF_LIKE(" fmt-index ", " arg-index ")"
 .BI "SCANF_LIKE(" fmt-index ", " arg-index ")"


@@ -64,6 +109,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


@@ -104,6 +195,12 @@ need not be used.  This may muffle warnings about leaving the marked
 definition unused.
 .PP
 A function marked as
 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 .
 .B NORETURN
 must not return.  It must have return type
 .BR void .