NL_TOOLS_16(3C)

NAME

firstof2, secof2, byte_status, FIRSTof2, SECof2, BYTE_STATUS, CHARAT, ADVANCE, CHARADV, WCHAR, WCHARADV, PCHAR, PCHARADV − tools to process 16-bit characters

SYNOPSIS

int firstof2(c)
int c;

int secof2(c)
int c;

int byte_status(c, laststatus)
int c, laststatus;

#include <nl_ctype.h>

FIRSTof2(c)
int c;

SECof2(c)
int c;

BYTE_STATUS(c, laststatus)
int c, laststatus;

CHARAT(p)
char ∗p;

ADVANCE(p)
char ∗p;

CHARADV(p)
char ∗p;

WCHAR(c, p)
int c;
char ∗p;

WCHARADV(c, p)
int c;
char ∗p;

PCHAR(c, p)
int c;
char ∗p;

PCHARADV(c, p)
int c;
char ∗p;

DESCRIPTION

The following macros and routines perform their operations based upon the loaded NLS environment (see setlocale(3C)).

FIRSTof2 takes a byte and returns a non-zero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot.

SECof2 takes a byte and returns a non-zero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot.

BYTE_STATUS returns one of the following values based on the value of the current byte in c and the status of the previous byte interpreted in laststatus as returned by the last call to BYTE_STATUS. These are the status values as defined in <nl_ctype.h>:

ONEBYTE single-byte character

SECOF2 second byte of two-byte character

FIRSTOF2 first byte of two-byte character

To validate a two-byte character, both the first and second bytes must be valid. If the value of laststatus is FIRSTOF2 but SECof2(c) returns false, BYTE_STATUS(c, laststatus) will return ONEBYTE.

For the macros FIRSTof2, SECof2, and BYTE_STATUS results are undefined for values of c less than −1 (EOF) or greater than 255.

CHARAT takes as an argument a pointer "p", which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case it evaluates to the unsigned value of the character, and is analogous to "(∗p)".

ADVANCE advances its pointer argument by the width of the character it is pointing at (either one or two bytes), and is analogous to "(p++)".

CHARADV combines the functions of CHARAT and ADVANCE in a single macro that evaluates to the unsigned value of a character and advances a pointer argument beyond the last byte of the character. It is analogous to "(∗p++)".

WCHAR writes one (0<=c<=255) or two (256<=c<=65535) bytes of its integer argument, more significant byte first, at the location specified by "p". It is analogous to "(∗p = c)" and evaluates to unsigned "c".

WCHARADV writes one (0<=c<=255) or two (256<=c<=65535) bytes of its integer argument, more significant byte first, at the location specified by "p", and advances "p" past the last byte. It is analogous to "(∗p++ = c)" and evaluates to unsigned "c".

PCHAR places one (0<=c<=255) or two (0<=c<=65535) bytes of its integer argument, more significant byte first, at the byte location specified by the pointer argument. It is analogous to "{∗p = c;}" and does not evaluate to "c". PCHAR is obsolete; use WCHAR instead.

PCHARADV places one (0<=c<=255) or two (256<=c<=65535) bytes of its integer argument, more significant byte first, at the byte location specified by the pointer argument, and advances the pointer past the last byte. It is analogous to "{∗p++ = c;}" and does not evaluate to "c". PCHARADV is obsolete; use WCHARADV instead.

The functions firstof2(), secof2(), and byte_status(), are subroutine versions of the corresponding macros, and can be called from languages other than C.

WARNINGS

For maximum portibility, the use of the routines specified in multibyte(3C) is recommended for multibyte character processing.

Other nl_tools_16(3C) macros cannot be used as the first argument to WCHAR or WCHARADV. For example, *t++ = *f++ cannot be replaced by WCHARADV(CHARADV(f),t). Use instead, something such as int c; ... c = CHARADV(f), WCHARADV(c,t).

WCHAR and WCHARADV may produce a "null effect" warning from lint(1) if not used as part of another expression or as part of a statement. This will not affect the functionality of either macro.

Note that WCHAR, WCHARADV, PCHAR and PCHARADV are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if WCHAR, WCHARADV, PCHAR or PCHARADV overwrite the first byte of the two-byte character with a single-byte character.

CHARAT, ADVANCE, and CHARADV examine the byte following the location pointed to by the argument to verify its validity as a SECof2 byte. If it is not a SECof2 byte, the preceding byte will always be treated as a single-byte character.

EXTERNAL INFLUENCES

Locale

The LC_CTYPE category determines the interpretation of single and/or multi-byte characters.

AUTHOR

Nl_tools_16 was developed by HP.

Museum

Related Articles