NLSTRING(3,L) AIX Technical Reference NLSTRING(3,L)
-------------------------------------------------------------------------------
NLstring
PURPOSE
Performs operations on strings containing code points.
LIBRARY
Standard C Library (libc.a)
SYNTAX
#include <string.h>
unsigned char *NLstrcat (s1, s2) int NLstrdlen (s)
unsigned char *s1, *s2; unsigned char *s;
unsigned char *NLstrncat (s1, s2, n) unsigned char *NLstrchr (s, x)
unsigned char *s1, *s2; unsigned char *s
int n; NLchar x;
int NLstrcmp (s1, s2) unsigned char *NLstrrchr (s, x)
char *s1, *s2; unsigned char *s
NLchar x;
int NLstrncmp (s1, s2, n)
char *s1, *s2; unsigned char *NLstrpbrk (s1, s2)
int n; unsigned char *s1, *s2;
char *NLstrcpy (s1, s2) int NLstrspn (s1, s2)
char *s1, *s2; unsigned char *s1, *s2;
unsigned char *NLstrncpy (s1, s2, n) int NLstrcspn (s1, s2)
unsigned char *s1, *s2; unsigned char *s1,
int n; char *s2;
int NLstrlen (s) char *NLstrtok (s1, s2)
unsigned char *s; unsigned char *s1, *s2;
DESCRIPTION
Note: In the multibyte environment, the NLstring routines listed above are
provided for backward compatibility. These routines are only front-ends
to the mbstring routines, (see "mbstring") and should be avoided if you
need to write portable programs.
Processed November 7, 1990 NLSTRING(3,L) 1
NLSTRING(3,L) AIX Technical Reference NLSTRING(3,L)
The NLstring subroutines copy, compare, and append strings in memory, and
determine such things as location, size, and existence of strings in memory. A
string is an array of code points terminated by a NULL character. The NLstring
subroutines parallel the string subroutines (see "string"), and NLstrcat,
NLstrncat, NLstrcpy, NLstrncpy, and NLstrlen are identical in function to their
string counterparts.
The subroutines NLstrcat, NLstrncat, NLstrcpy, and NLstrncpy all alter s1.
They do not check for overflow of the array pointed to by s1. All string
movement is performed character by character and starts at the left.
Overlapping moves toward the left work as expected, but overlapping moves to
the right may give unexpected results. All of these subroutines are declared
in the string.h header file.
The NLstrcat subroutine appends a copy of the string pointed to by the s2
parameter to the end of the string pointed to by the s1 parameter. The
NLstrcat subroutine returns a pointer to the NULL-terminated result.
The NLstrncat subroutine performs the same function as the NLstrcat subroutine,
but the number of bytes appended to the end of the string pointed to by the s1
parameter is limited to n; this may represent fewer than n code points. The
NLstrncat subroutine returns a pointer to the NULL-terminated result.
The NLstrcmp subroutine lexicographically compares the string pointed to by the
s1 parameter to the string pointed to by the s2 parameter. The NLstrcmp
subroutine returns a value that is:
Less than 0 If s1 is less than s2
Equal to 0 If s1 is equal to s2
Greater than 0 If s1 is greater than s2.
The NLstrncmp subroutine makes the same comparison as NLstrcmp, but it compares
at most n bytes. Characters that have 2-byte representations can cause
NLstrncmp to return 0 for unequal strings. If n divides a 2-byte character,
then the last byte comparison is skipped. If the only difference in the two
strings is in that last byte, an incorrect true is returned.
Both the NLstrcmp and NLstrncmp subroutines use the environment variable NLCTAB
to determine the collating sequence for performing comparisons. (See
"NCcollate, NCcoluniq, NCeqvmap, _NCxcol, _NLxcol" for information on collation
for international character support.) Unless a true collating relationship is
to be tested for, strcmp and strncmp can instead be used for equality
comparisons (see "string"). The bytes will match regardless of code point
representations.
The NLstrcpy subroutine copies the string pointed to by the s2 parameter to the
character array pointed to by the s1 parameter. There must be enough room in
the array pointed to by the s1 parameter for the string pointed to by the s2
parameter, including the trailing NULL character. The NLstrcpy subroutine
returns the value of the s1 parameter.
Processed November 7, 1990 NLSTRING(3,L) 2
NLSTRING(3,L) AIX Technical Reference NLSTRING(3,L)
The NLstrncpy subroutine copies the string pointed to by the s2 parameter to
the character array pointed to by the s1 parameter, copying at most n bytes.
If s2 is shorter than n, a NULL character is added to s1. If the length in
bytes of s2 is greater than n, the result is not NULL-terminated. If byte n is
the first byte of an extended code then byte n is not copied; s1 is n-1 in
length. The NLstrncpy subroutine returns the value of the s1 parameter.
The NLstrlen subroutine returns the number of bytes in the string pointed to by
the s parameter, not including the terminating NULL character.
The NLstrdlen subroutine returns the number of code points in the string
pointed to by s, not including the terminating NULL character.
The NLstrchr subroutine returns a pointer to the first occurrence of the code
point corresponding to the NLchar specified by the x parameter in the string
pointed to by the s parameter. A NULL pointer is returned if the code point
does not occur in the string. The NULL character that terminates a string is
considered to be part of the string.
The NLstrrchr subroutine returns a pointer to the last occurrence of the code
point corresponding to the NLchar specified by the x parameter in the string
pointed to by the s parameter. A NULL pointer is returned if the code point
does not occur in the string. The NULL character that terminates a string is
considered to be part of the string.
The NLstrpbrk subroutine returns a pointer to the first occurrence in the
string pointed to by the s1 parameter of any code point from the string pointed
to by the s2 parameter. A NULL pointer is returned if no character matches.
The NLstrspn subroutine returns the length of the initial segment of the string
pointed to by the s1 parameter that consists entirely of code points from the
string pointed to by the s2 parameter.
The NLstrcspn subroutine returns the length of the initial segment of the
string pointed to by the s1 parameter that consists entirely of code points not
from the string pointed to by the s2 parameter.
The NLstrtok subroutine returns a pointer to an occurrence of text tokens in
the string pointed to by the s1 parameter. The s2 parameter specifies a set of
code points as token delimiters. If the s1 parameter is anything other than
NULL, then the NLstrtok subroutine reads the string pointed to by the s1
parameter until it finds one of the delimiter code points specified by the s2
parameter. It then stores a NULL character into the string, replacing the
delimiter code point, and returns a pointer to the first code point of the text
token. The NLstrtok subroutine keeps track of its position in the string so
that subsequent calls with a NULL s1 parameter step through the string. The
delimiters specified by the s2 parameter can be changed for subsequent calls to
NLstrtok. When no tokens remain in the string pointed to by the s1 parameter,
the NLstrtok subroutine returns a NULL pointer.
RELATED INFORMATION
Processed November 7, 1990 NLSTRING(3,L) 3
NLSTRING(3,L) AIX Technical Reference NLSTRING(3,L)
In this book: "NCcollate, NCcoluniq, NCeqvmap, _NCxcol, _NLxcol," "NCstring,"
"NLchar," "mbstring," and "string."
"Introduction to International Character Support" in Managing the AIX Operating
System.
AIX Guide to Multibyte Character Set (MBCS) Support.
Processed November 7, 1990 NLSTRING(3,L) 4