X-Git-Url: https://pd.if.org/git/?a=blobdiff_plain;f=includes%2Fctype.h;h=168900a4545ca98dd773431e162fdf6b573dccbf;hb=d865c4403fc91d1f1ac95ba76febcee9f429bb97;hp=96f288c820e6a91e014e0e7c8f293c1229ec75ed;hpb=1d9d92ba957a0b8307c9a65c35867fde68e6533b;p=pdclib

diff --git a/includes/ctype.h b/includes/ctype.h
index 96f288c..168900a 100644
--- a/includes/ctype.h
+++ b/includes/ctype.h
@@ -1,60 +1,93 @@
-/* ----------------------------------------------------------------------------
- * $Id$
- * ----------------------------------------------------------------------------
- * Public Domain C Library - http://pdclib.sourceforge.net
- * This code is Public Domain. Use, modify, and redistribute at will.
- * ----------------------------------------------------------------------------
- * Character handling
- * --------------------------------------------------------------------------*/
-
-#ifndef _CTYPE_H
-#define _CTYPE_H _CTYPE_H
-
-/* ----------------------------------------------------------------------------
- * FUNCTIONS
- * --------------------------------------------------------------------------*/
-
-/* returns nonzero if c is alphanumeric in the locale. */
+/* Character handling <ctype.h>
+
+   This file is part of the Public Domain C Library (PDCLib).
+   Permission is granted to use, modify, and / or redistribute at will.
+*/
+
+#ifndef _PDCLIB_CTYPE_H
+#define _PDCLIB_CTYPE_H _PDCLIB_CTYPE_H
+
+#include "_PDCLIB_int.h"
+
+/* Character classification functions */
+
+/* Note that there is a difference between "whitespace" (any printing, non-
+   graph character, like horizontal and vertical tab), and "blank" (the literal
+   ' ' space character).
+
+   There will be masking macros for each of these later on, but right now I
+   focus on the functions only.
+*/
+
+/* Returns isalpha( c ) || isdigit( c ) */
 int isalnum( int c );
 
-/* returns nonzero if c is alphabetic character in the locale. */
+/* Returns isupper( c ) || islower( c ) in the "C" locale.
+   In any other locale, also returns true for a locale-specific set of
+   alphabetic characters which are neither control characters, digits,
+   punctation, or whitespace.
+*/
 int isalpha( int c );
 
-/* returns nonzero if c is a horizontal blank in the locale. */
+/* Returns true if the character isspace() and used for seperating words within
+   a line of text. In the "C" locale, only ' ' and '\t' are considered blanks.
+*/
 int isblank( int c );
 
-/* returns nonzero if c is a control character in the locale. */
+/* Returns true if the character is a control character. */
 int iscntrl( int c );
 
-/* returns nonzero if c is a digit in the locale. */
+/* Returns true if the character is a decimal digit. Locale-independent. */
 int isdigit( int c );
 
-/* returns nonzero if c is alphanumeric or a punctuation in the locale. */
+/* Returns true for every printing character except space (' '). */
 int isgraph( int c );
 
-/* returns nonzero if c is a lowercase alphabetic character in the locale. */
+/* Returns true for lowercase letters in the "C" locale.
+   In any other locale, also returns true for a locale-specific set of
+   characters which are neither control characters, digits, punctation, or
+   space (' '). In a locale other than the "C" locale, a character might test
+   true for both islower() and isupper().
+*/
 int islower( int c );
 
-/* returns nonzero if c is a printable character ( isgraph() or isblank() ) in
- * the locale. */
+/* Returns true for every printing character including space (' '). */
 int isprint( int c );
 
-/* returns nonzero if c is a punctuation in the locale. */
+/* Returns true for every printing character that is neither whitespace
+   nor alphanumeric in the "C" locale. In any other locale, there might be
+   characters that are printing characters, but neither whitespace nor
+   alphanumeric.
+*/
 int ispunct( int c );
 
-/* returns nonzero if c is a whitespace in the locale. */
+/* Returns true for every standard whitespace character (' ', '\f', '\n', '\r',
+   '\t', '\v') in the "C" locale. In any other locale, also returns true for a
+   locale-specific set of characters for which isalnum() is false.
+*/
 int isspace( int c );
 
-/* returns nonzero if c is an uppercase alphabetical character in the locale. */
+/* Returns true for uppercase letters in the "C" locale.
+   In any other locale, also returns true for a locale-specific set of
+   characters which are neither control characters, digits, punctation, or
+   space (' '). In a locale other than the "C" locale, a character might test
+   true for both islower() and isupper().
+*/
 int isupper( int c );
 
-/* returns nonzero if c is a hexedecimal digit in the locale. */
+/* Returns true for any hexadecimal-digit character. Locale-independent. */
 int isxdigit( int c );
 
-/* returns lowercase equivalent for c in locale. */
+/* Character case mapping functions */
+
+/* Converts an uppercase letter to a corresponding lowercase letter. Input that
+   is not an uppercase letter remains unchanged.
+*/
 int tolower( int c );
 
-/* returns uppercase equivalent for c in locale. */
+/* Converts a lowercase letter to a corresponding uppercase letter. Input that
+   is not a lowercase letter remains unchanged.
+*/
 int toupper( int c );
 
-#endif /* _CTYPE_H */
+#endif