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 nl_init(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

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. 

AUTHOR

Nl_tools_16 was developed by HP. 

SEE ALSO

nl_init(3C), hpnls(5). 

INTERNATIONAL SUPPORT

8-bit data, 16-bit data. 

Hewlett-Packard Company  —  May 11, 2021