public inbox for glibc-cvs@sourceware.org help / color / mirror / Atom feed
From: Florian Weimer <fw@sourceware.org> To: glibc-cvs@sourceware.org Subject: [glibc] manual: Enhance documentation of the <ctype.h> functions Date: Mon, 3 Jul 2023 10:40:17 +0000 (GMT) [thread overview] Message-ID: <20230703104017.77D623858D1E@sourceware.org> (raw) https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=9651b06940b79e3a6da3f9fe7dd5a8cfbd5c5d88 commit 9651b06940b79e3a6da3f9fe7dd5a8cfbd5c5d88 Author: Florian Weimer <fweimer@redhat.com> Date: Mon Jul 3 12:36:56 2023 +0200 manual: Enhance documentation of the <ctype.h> functions Describe the problems with signed characters, and the glibc extension to deal with most of them. Mention that the is* functions return zero for the special argument EOF. Reviewed-by: Carlos O'Donell <carlos@redhat.com> Diff: --- manual/ctype.texi | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/manual/ctype.texi b/manual/ctype.texi index 88e3523dc4..d09249c6cf 100644 --- a/manual/ctype.texi +++ b/manual/ctype.texi @@ -40,21 +40,37 @@ one set works on @code{char} type characters, the other one on This section explains the library functions for classifying characters. For example, @code{isalpha} is the function to test for an alphabetic -character. It takes one argument, the character to test, and returns a -nonzero integer if the character is alphabetic, and zero otherwise. You -would use it like this: +character. It takes one argument, the character to test as an +@code{unsigned char} value, and returns a nonzero integer if the +character is alphabetic, and zero otherwise. You would use it like +this: @smallexample -if (isalpha (c)) +if (isalpha ((unsigned char) c)) printf ("The character `%c' is alphabetic.\n", c); @end smallexample Each of the functions in this section tests for membership in a particular class of characters; each has a name starting with @samp{is}. -Each of them takes one argument, which is a character to test, and -returns an @code{int} which is treated as a boolean value. The -character argument is passed as an @code{int}, and it may be the -constant value @code{EOF} instead of a real character. +Each of them takes one argument, which is a character to test. The +character argument must be in the value range of @code{unsigned char} (0 +to 255 for @theglibc{}). On a machine where the @code{char} type is +signed, it may be necessary to cast the argument to @code{unsigned +char}, or mask it with @samp{& 0xff}. (On @code{unsigned char} +machines, this step is harmless, so portable code should always perform +it.) The @samp{is} functions return an @code{int} which is treated as a +boolean value. + +All @samp{is} functions accept the special value @code{EOF} and return +zero. (Note that @code{EOF} must not be cast to @code{unsigned char} +for this to work.) + +As an extension, @theglibc{} accepts signed @code{char} values as +@samp{is} functions arguments in the range -128 to -2, and returns the +result for the corresponding unsigned character. However, as there +might be an actual character corresponding to the @code{EOF} integer +constant, doing so may introduce bugs, and it is recommended to apply +the conversion to the unsigned character range as appropriate. The attributes of any given character can vary between locales. @xref{Locales}, for more information on locales.
reply other threads:[~2023-07-03 10:40 UTC|newest] Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20230703104017.77D623858D1E@sourceware.org \ --to=fw@sourceware.org \ --cc=glibc-cvs@sourceware.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).