conv Subroutines

Purpose

Translates characters.

Library

Standard C Library (libc.a)

Syntax

#include <ctype.h>

Description

The toupper and the tolower subroutines have as domain an int, which is representable as an unsigned char or the value of EOF: -1 through 255.

If the parameter of the toupper subroutine represents a lowercase letter and there is a corresponding uppercase letter (as defined by LC_CTYPE), the result is the corresponding uppercase letter. If the parameter of the tolower subroutine represents an uppercase letter, and there is a corresponding lowercase letter (as defined by LC_CTYPE), the result is the corresponding lowercase letter. All other values in the domain are returned unchanged. If case-conversion information is not defined in the current locale, these subroutines determine character case according to the "C" locale.

The _toupper and _tolower subroutines accomplish the same thing as the toupper and tolower subroutines, but they have restricted domains. The _toupper routine requires a lowercase letter as its parameter; its result is the corresponding uppercase letter. The _tolower routine requires an uppercase letter as its parameter; its result is the corresponding lowercase letter. Values outside the domain cause undefined results.

The NCxxxxxx subroutines translate all characters, including extended characters, as code points. The other subroutines translate traditional ASCII characters only. The NCxxxxxx subroutines are obsolete and should not be used if portability and future compatibility are a concern.

The value of the Xcharacter parameter is in the domain of any legal NLchar data type. It can also have a special value of -1, which represents the end of file (EOF).

If the parameter of the NCtoupper subroutine represents a lowercase letter according to the current collating sequence configuration, the result is the corresponding uppercase letter. If the parameter of the NCtolower subroutine represents an uppercase letter according to the current collating sequence configuration, the result is the corresponding lowercase letter. All other values in the domain are returned unchanged.

The _NCtoupper and _NCtolower routines are macros that perform the same function as the NCtoupper and NCtolower subroutines, but have restricted domains and are faster. The _NCtoupper macro requires a lowercase letter as its parameter; its result is the corresponding uppercase letter. The _NCtolower macro requires an uppercase letter as its parameter; its result is the corresponding lowercase letter. Values outside the domain cause undefined results.

The NCtoNLchar subroutine yields the value of its parameter with all bits turned off that are not part of an NLchar data type.

The NCesc subroutine converts the NLchar value of the Pointer parameter into one or more ASCII bytes stored in the character array pointed to by the CharacterPointer parameter. If the NLchar data type represents an extended character, it is converted into a printable ASCII escape sequence that uniquely identifies the extended character. NCesc returns the number of bytes it wrote. The display symbol table lists the escape sequence for each character.

The opposite conversion is performed by the NCunesc macro, which translates an ordinary ASCII byte or escape sequence starting at CharacterPointer into a single NLchar at Pointer. NCunesc returns the number of bytes it read.

The NCflatchr subroutine converts its parameter value into the single ASCII byte that most closely resembles the parameter character in appearance. If no ASCII equivalent exists, it converts the parameter value to a ? (question mark).

Parameters