NAME

nl_tools_16 − tools to process 16-bit characters

SYNOPSIS

int langinit(langname)
char *langname;

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;

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

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

DESCRIPTION

Langinit initializes a table according to the specified language name.  This table is used by the other 16-bit tools described herein to determine whether a byte may be the first or second byte of a 16-bit character.  This same table is also used by the 8-bit nl_ctype(3C) routines for character classification.  The nl_ctype(3C) routines implicitly call langinit if the table has not yet been loaded or if the language specified is different from the language currently loaded in the table.  The 16-bit tools do not automatically call langinit: you must explicitly call langinit as appropriate. 

The argument to langinit, which is langname, must be a pointer to a null terminated string containing a language name as defined in langid(5). If langname is NULL or points to a zero-length string, langname defaults to "n-computer".  Langinit returns zero if the table for the specified language is loaded without error.  If the table for the specified language cannot be loaded, langinit loads the table with "n-computer" language data and returns a non-zero value. 

FIRSTof2 takes a byte and returns a non-zero value if it may be the first byte of a two-byte character according to the currently loaded langinit table, and zero if it is not. 

SECof2 takes a byte and returns a non-zero value if it may be the second byte of a two-byte character according to the currently loaded langinit table, and zero if it is not. 

BYTE_STATUS returns one of the following values based on the value of the byte and the status of the (presumably) last byte passed in as a parameter.  These are the status values as defined in <nl_ctype.h>:

ONEBYTE single byte character

SECOF2 second byte of 2-byte

FIRSTOF2 first byte of 2-byte

Note that in order to validate a two-byte character, both the first and second bytes must be judged individually to 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 zero 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 returns the value of the character; analogous to "*p". 

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

CHARADV combines the functions of CHARAT and ADVANCE in a single subroutine that returns a character and advances a pointer argument beyond the last byte of the character; analogous to "*p++". 

PCHAR places one (c<256) or two (c>255) bytes of its integer argument, more significant byte first, at the byte location specified by the pointer argument; analogous to "*p = c". 

PCHARADV places one (c<256) or two (c>255) 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; analogous to "*p++ = c". 

Note that PCHAR and PCHARADV should not be considered "replace_char" macros.  For example, they take no steps to ensure that the second byte of a two-byte character is not left dangling if they over-write the first byte with a single-byte character. 

CHARAT, ADVANCE, and CHARADV examine the byte following the location pointed to by the argument in order to check that it is a valid SECof2 byte. If it is not a valid SECof2 byte, the preceding byte will always be treated as a single-byte character. 

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

AUTHOR

Nl_tools_16 was developed by HP. 

SEE ALSO

langinfo(3C), nl_ctype(3C), hpnls(5), langid(5). 

Hewlett-Packard Company  —  Version B.1,  May 11, 2021