NLstring
Purpose
Performs operations on strings containing code points.
Library
Standard C Library (libc.a)
Syntax
#include <string.h>
char *NLstrcat (s1, s2) | int NLstrdlen (s)
char *s1, *s2; | char *s;
|
char *NLstrncat (s1, s2, n) | char *NLstrchr (s, x)
char *s1, *s2; | char *s, x;
int n; |
|
int NLstrcmp (s1, s2) | char *NLstrrchr (s, x)
char *s1, *s2; | char *s, x;
|
int NLstrncmp (s1, s2, n) | char *NLstrpbrk (s1, s2)
char *s1, *s2; | char *s1, *s2;
int n; |
|
char *NLstrcpy (s1, s2) | int NLstrspn (s1, s2)
char *s1, *s2; | char *s1, *s2;
|
char *NLstrncpy (s1, s2, n) | int NLstrcspn (s1, s2)
char *s1, *s2; | char *s1, *s2;
int n; |
|
int NLstrlen (s) | char *NLstrtok (s1, s2)
char *s; | char *s1, *s2;
Description
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 string is at most n
bytes; this may represent fewer than n code points. The
NLstrcat 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 envi-
ronment 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, 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
NLstrcpy subroutine returns the value of the s1 param-
eter.
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 param-
eter that consists entirely of code points not from the
string pointed to by the s2 parameter.
The NLstrtok subroutine returns a pointer to an occur-
rence 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 any-
thing 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
In this book: "NCcollate, NCcoluniq, NCeqvmap, _NCxcol,
_NLxcol," "NCstring," "NLchar," and "string."
"Overview of International Character Support" in Managing
the AIX Operating System.