From 4132a111276f4410b7326559d8235df652b0560b Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Thu, 19 Nov 2015 23:38:02 +0100 Subject: etymology for some functions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- include/alloca.h | 2 ++ include/assert.h | 6 +++++ include/ctype.h | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++--- include/err.h | 16 ++++++++++++ 4 files changed, 95 insertions(+), 3 deletions(-) (limited to 'include') diff --git a/include/alloca.h b/include/alloca.h index 010bb99..a800cf0 100644 --- a/include/alloca.h +++ b/include/alloca.h @@ -37,6 +37,8 @@ * Undefined behaviour is invoked if the memory * cannot be allocated. * + * @etymology (Alloca)te! + * * @param size The number of bytes to allocate. * @return Pointer to the beginning of the allocated * space. Do not free it, it will be freed diff --git a/include/assert.h b/include/assert.h index 12b20eb..4523860 100644 --- a/include/assert.h +++ b/include/assert.h @@ -35,6 +35,8 @@ * POSIX specifies that `assert` shall not evaluate the * expression if `NDEBUG` is defined. This is probably * to save CPU-cycles. + * + * @etymology (Assert)ion. */ #ifdef NDEBUG # define assert(expression) ((void)0) @@ -54,6 +56,8 @@ * * `assert_perror` is a GNU-compliant slibc extension. * + * @etymology (`assert`) version of (`perror`). + * * @param errnum:int The error code, describing the error that occurred. */ # ifdef assert_perror @@ -84,6 +88,8 @@ * A compile-time error should occur if the expression * evaluates to zero. * + * @etymology (Static) (assert)tion. + * * @param expression:scalar The expression to evaluate. * @param message:const char* The message to print on error. */ diff --git a/include/ctype.h b/include/ctype.h index 82f13af..9b6508c 100644 --- a/include/ctype.h +++ b/include/ctype.h @@ -36,6 +36,8 @@ * Check whether a character is an alphabetical * character or a decimal digit. * + * @etymology (Is) character either (al)phabetical or (num)erical [(al)pha(num)erical]? + * * @param c The character. * @return Whether the character is in * ['0', '9'], ['A', 'Z'], or ['a', 'z']. @@ -51,6 +53,8 @@ int (isalnum)(int) /* [0x30, 0x39], [0x41, 0x5A], [0x61, 0x7A] */ /** * Check whether a character is an alphabetical character. * + * @etymology (Is) character (alpha)betical? + * * @param c The character. * @return Whether the character is in * ['A', 'Z'] or ['a', 'z']. @@ -67,6 +71,8 @@ int (isalpha)(int) /* [0x41, 0x5A], [0x61, 0x7A] */ * * This is a GNU extension. * + * @etymology (Is) character a (blank) space? + * * @param c The character. * @return Whether the character is a ' ' or a '\t'. */ @@ -83,6 +89,8 @@ int (isblank)(int) /* ' ', '\t' */ * Check whether a character is a non-printable * ASCII character. * + * @etymology (Is) character a (c)o(ntr)o(l) character? + * * @param c The character. * @return Whether the character is lower than ' ', * or is 0x7F. @@ -98,6 +106,8 @@ int (iscntrl)(int) /* [0x00, 0x1F], 0x7F */ /** * Check whether a character is a decimal digit. * + * @etymology (Is) character a (digit)? + * * @param c The character. * @return Whether the character is in ['0', '9']. */ @@ -109,6 +119,8 @@ int (isdigit)(int) /* [0x30, 0x39] */ /** * Check whether a character is has a printable glyph. * + * @etymology (Is) character (graph)ical? + * * @param c The character. * @return Whether the character is greater * than ' ', but is not 0x7F. @@ -122,6 +134,8 @@ int (isgraph)(int) /* [0x21, 0x7E] */ * Check whether a character is a lowercase * alphabetical character. * + * @etymology (Is) character a (lower)case character? + * * @param c The character. * @return Whether the character is in ['a', 'z']. */ @@ -134,6 +148,8 @@ int (islower)(int) /* [0x61, 0x7A] */ * Check whether a character is has a printable glyph * or a blank space. * + * @etymology (Is) character (print)able? + * * @param c The character. * @return Whether the character is at least * as great as ' ', but is not 0x7F. @@ -148,6 +164,8 @@ int (isprint)(int) /* [0x20, 0x7E] */ * that is, a printable character but a blank space, * numerical or alphabetical. * + * @etymology (Is) character a (punct)uation? + * * @param c The character. * @return Whether the character is a punctuation. */ @@ -162,6 +180,8 @@ int (ispunct)(int) /* isprint && !isalnum && !isspace */ /** * Check whether a character is a whitespace character. * + * @etymology (Is) character white(space)? + * * @param c The character. * @return Whether the character is a ' ', '\f', * '\n', '\r', '\t', or '\v'. @@ -178,6 +198,8 @@ int (isspace)(int) /* 0x20, [0x09, 0x0D] */ * Check whether a character is an uppercase * alphabetical character. * + * @etymology (Is) character a (upper)case character? + * * @param c The character. * @return Whether the character is in ['A', 'Z']. */ @@ -191,6 +213,8 @@ int (isupper)(int) /* [0x41, 0x5A] */ * hexadecimal digit. Both uppercase and * lowercase is supported. * + * @etymology (Is) character a he(x)adecimal digit? + * * @param c The character. * @return Whether the character is in * ['0', '9'], ['A', 'Z'], or ['a', 'z']. @@ -208,11 +232,13 @@ int (isxdigit)(int) /* [0x30, 0x39], [0x41, 0x46], [0x61, 0x66] */ * Convert a uppercase ASCII character to * an lowercase ASCII character. * - * The function's behaviour is unspecifed + * The function's behaviour is unspecified * of the character is not alphabetical. * You should consider running * `(isupper(c) ? tolower(c) : c)` instead. * + * @etymology Convert character (to) (lower)case! + * * @param c The character. * @return The character in lowercase. * Guaranteed to be unchanged if the @@ -226,11 +252,13 @@ int (tolower)(int) /* [0x41, 0x5A] -> [0x61, 0x7A] */ * Convert a lowercase ASCII character to * an uppercase ASCII character. * - * The function's behaviour is unspecifed + * The function's behaviour is unspecified * of the character is not alphabetical. * You should consider running * `(isupper(c) ? tolower(c) : c)` instead. * + * @etymology Convert character (to) (upper)case! + * * @param c The character. * @return The character in uppercase. * Guaranteed to be unchanged if the @@ -245,6 +273,8 @@ int (toupper)(int) /* [0x61, 0x7A] -> [0x41, 0x5A] */ /** * Check whether a character is an ASCII character. * + * @etymology (Is) character an (ASCII) character? + * * @param c The character * @return Whether the character is an ASCII character. */ @@ -258,6 +288,12 @@ int (isascii)(int) /* [0x00, 0x7E] */ * Note that this does not make a proper character set * convertion and the result is virtually arbitrary. * + * Justification for existence: + * The highest bit has historically been used as a + * parity bit. + * + * @etymology Truncate character (to) fit (ASCII) character set! + * * @param c The character. * @return The character with the 8:th bit cleared. */ @@ -290,6 +326,8 @@ int _toupper(int) * Check whether a character is an alphabetical * character or a decimal digit. * + * @etymology (Is) character (alpha)betical, with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character is @@ -302,6 +340,8 @@ int isalnum_l(int, locale_t) /** * Check whether a character is an alphabetical character. * + * @etymology (Is) character (alpha)betical, with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character is alphabetical. @@ -317,6 +357,8 @@ int isalpha_l(int, locale_t) * * This is a GNU extension. * + * @etymology (Is) character a (blank) space, with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character is a ' ' or a '\t'. @@ -330,6 +372,8 @@ int isblank_l(int, locale_t) * Check whether a character is a non-printable * ASCII character. * + * @etymology (Is) character a (c)o(ntr)o(l) character, with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character is non-printable. @@ -341,6 +385,8 @@ int iscntrl_l(int, locale_t) /** * Check whether a character is a decimal digit. * + * @etymology (Is) character a (digit), with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character is numerical. @@ -352,6 +398,8 @@ int isdigit_l(int, locale_t) /** * Check whether a character is has a printable glyph. * + * @etymology (Is) character (graph)ical, with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character has a glyph. @@ -364,6 +412,8 @@ int isgraph_l(int, locale_t) * Check whether a character is a lowercase * alphabetical character. * + * @etymology (Is) character a (lower)case character, with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character is a lowercase letter. @@ -376,6 +426,8 @@ int islower_l(int, locale_t) * Check whether a character is has a printable glyph * or a blank space. * + * @etymology (Is) character (print)able, with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character has a printable @@ -390,6 +442,8 @@ int isprint_l(int, locale_t) * that is, a printable character but a blank space, * numerical or alphabetical. * + * @etymology (Is) character a (punct)uation, with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character is a punctuation. @@ -401,6 +455,8 @@ int ispunct_l(int, locale_t) /** * Check whether a character is a whitespace character. * + * @etymology (Is) character white(space), with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character is a @@ -414,6 +470,8 @@ int isspace_l(int, locale_t) * Check whether a character is an uppercase * alphabetical character. * + * @etymology (Is) character a (upper)case character, with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character is a uppercase letter. @@ -427,6 +485,8 @@ int isupper_l(int, locale_t) * hexadecimal digit. Both uppercase and * lowercase is supported. * + * @etymology (Is) character a he(x)adecimal digit, with consideration for (l)ocale? + * * @param c The character. * @param locale The locale. * @return Whether the character is in @@ -439,12 +499,14 @@ int isxdigit_l(int, locale_t) /** * Check whether a character is an ASCII character. * + * @etymology (Is) character an (ASCII) character, with consideration for (l)ocale? + * * @param c The character * @param locale The locale. * @return Whether the character is an ASCII character. */ int isascii_l(int, locale_t) - __warning("This function is dangerous, use 'isascii_l' instead.") + __warning("This function is dangerous, use 'iswascii_l' instead.") __GCC_ONLY(__attribute__((__const__))); /** @@ -453,6 +515,8 @@ int isascii_l(int, locale_t) * Note that this does not make a proper character set * convertion and the result is virtually arbitrary. * + * @etymology Truncate character (to) fit (ASCII) character set, with consideration for (l)ocale! + * * @param c The character. * @param locale The locale. * @return The character with the 8:th bit cleared. @@ -471,6 +535,8 @@ int toascii_l(int, locale_t) * `(isupper_l(c, l) ? tolower_l(c, l) : c)` * instead. * + * @etymology Convert character (to) (lower)case, with consideration for (l)ocale! + * * @param c The character. * @param locale The locale. * @return The character in lowercase. @@ -491,6 +557,8 @@ int tolower_l(int, locale_t) * `(isupper_l(c, l) ? tolower_l(c, l) : c)` * instead. * + * @etymology Convert character (to) (upper)case, with consideration for (l)ocale! + * * @param c The character. * @param locale The locale. * @return The character in uppercase. diff --git a/include/err.h b/include/err.h index a603cbb..63dcdda 100644 --- a/include/err.h +++ b/include/err.h @@ -37,6 +37,8 @@ * * This is a non-standard BSD extension. * + * @etymology Print (warn)ing! + * * @param format Formatting-string for the warning. * @param ... Formatting-arguments. */ @@ -49,6 +51,8 @@ void warn(const char*, ...) * * This is a non-standard BSD extension. * + * @etymology (V)ariadic version of (`warn`). + * * @param format Formatting-string for the warning. * @param args Formatting-arguments. */ @@ -60,6 +64,8 @@ void vwarn(const char*, va_list); * * This is a non-standard BSD extension. * + * @etymology (`warn`), [x=](lesser variant). + * * @param format Formatting-string for the warning. * @param ... Formatting-arguments. */ @@ -72,6 +78,8 @@ void warnx(const char*, ...) * * This is a non-standard BSD extension. * + * @etymology (V)ariadic version of (`warnx`). + * * @param format Formatting-string for the warning. * @param args Formatting-arguments. */ @@ -83,6 +91,8 @@ void vwarnx(const char*, va_list); * * This is a non-standard BSD extension. * + * @etymology Report (err)or! + * * @parma status The exit status the process should have. * @param format Formatting-string for the warning. * @param ... Formatting-arguments. @@ -96,6 +106,8 @@ __noreturn void err(int, const char*, ...) * * This is a non-standard BSD extension. * + * @etymology (V)ariadic version of (`err`). + * * @parma status The exit status the process should have. * @param format Formatting-string for the warning. * @param args Formatting-arguments. @@ -108,6 +120,8 @@ __noreturn void verr(int, const char*, va_list); * * This is a non-standard BSD extension. * + * @etymology (`err`), [x=](lesser variant). + * * @parma status The exit status the process should have. * @param format Formatting-string for the warning. * @param ... Formatting-arguments. @@ -121,6 +135,8 @@ __noreturn void errx(int, const char*, ...) * * This is a non-standard BSD extension. * + * @etymology (V)ariadic version of (`errx`). + * * @parma status The exit status the process should have. * @param format Formatting-string for the warning. * @param args Formatting-arguments. -- cgit v1.2.3-70-g09d2