NCstring
Purpose
Performs operations on strings.
Library
Standard C Library (libc.a)
Syntax
#include <string.h>
NLchar *NCstrcat (xs1, xs2) | NLchar *NCstrchr (xs, x)
NLchar *xs1, *xs2; | NLchar *xs, x;
|
NLchar *NCstrncat (xs1, xs2, n) | NLchar *NCstrrchr (xs, x)
NLchar *xs1, *xs2; | NLchar *xs, x;
int n; |
| NLchar *NCstrpbrk (xs1, s2)
int NCstrcmp (xs1, xs2) | NLchar *xs1;
NLchar *xs1, *xs2; | char *s2;
|
int NCstrncmp (xs1, xs2, n) | int NCstrspn (xs1, s2)
NLchar *xs1, *xs2; | NLchar *xs1;
int n; | char *s2;
|
NLchar *NCstrcpy (xs1, xs2) | int NCstrcspn (xs1, s2)
NLchar *xs1, *xs2; | NLchar *xs1;
| char *s2;
NLchar *NCstrncpy (xs1, xs2, n) |
NLchar *xs1, *xs2; | NLchar *NCstrtok (xs1, s2)
int n; | NLchar *xs1;
| char *s2;
int NCstrlen (xs)
NLchar *xs;
Description
The NCstring subroutines copy, compare, and append
strings in memory, and determine such things as location,
size, and existence of strings in memory. For these sub-
routines, a string is an array of NLchars, terminated by
a null character. The NCstring subroutines parallel the
string subroutines (see "string"), but operate on strings
of type NLchar rather than on type char, except as spe-
cifically noted below.
These subroutines require their parameters (except the s2
parameter) to be explicitly converted to type NLchar, so
they should be used on input that is to be scanned many
times for each time it is converted. Where this perform-
ance concern does not apply, the NLstring subroutines are
easier to use (see "NLstring").
The s2 parameter is a string of type char containing code
point representations of ASCII characters or extended
characters for international character support. This
supports the use of a double-quoted string for this
parameter in calling programs.
The parameters xs1, xs2 and s point to strings of type
NLchar (arrays of NLchars terminated by a null char-
acter). The s2 parameter points to strings of type char.
The subroutines NCstrcat, NCstrncat, NCstrcpy, and
NCstrncpy all alter xs1. They do not check for overflow
of the array pointed to by xs1. 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 NCstrcat subroutine appends a copy of the string
pointed to by the xs2 parameter to the end of the string
pointed to by the xs1 parameter. The NCstrcat subroutine
returns a pointer to the null-terminated result.
The NCstrncat subroutine copies at most n NLchars of xs2
to the end of the string pointed to by the xs1 parameter.
Copying stops before n NLchars if a null character is
encountered in the xs2 string. The NCstrncat subroutine
returns a pointer to the null-terminated result.
The NCstrcmp subroutine lexicographically compares the
string pointed to by the xs1 parameter to the string
pointed to by the xs2 parameter. The NCstrcmp subroutine
returns a value that is:
Less than 0 If xs1 is less than xs2
Equal to 0 If xs1 is equal to xs2
Greater than 0 If xs1 is greater than xs2.
The NCstrncmp subroutine makes the same comparison as
NCstrcmp, but it compares at most n pairs of NLchars.
Both NCstrcmp and NCstrncmp use the environment variable
NLCTAB to determine the collating sequence for performing
comparisons. (See "NCcollate, NCcoluniq, NCeqvmap,
_NCxcol, _NLxcol" for information on collation for inter-
national 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 the NLchars in the
string.
The NCstrcpy subroutine copies the string pointed to by
the xs2 parameter to the character array pointed to by
the xs1 parameter. Copying stops when the null character
is copied. The NCstrcpy subroutine returns the value of
the xs1 parameter.
The NCstrncpy subroutine copies n NLchars from the string
pointed to by the xs2 parameter to the character array
pointed to by the xs1 parameter. If xs2 is less than n
NLchars long, then NCstrncpy pads xs1 with trailing null
characters to fill n NLchars. If xs2 is n or more
NLchars long, then only the first n NLchars are copied;
the result is not terminated with a null character. The
NCstrncpy subroutine returns the value of the xs1 param-
eter.
The NCstrlen subroutine returns the number of NLchars in
the string pointed to by the s parameter, not including
the terminating null character.
The NCstrchr subroutine returns a pointer to the first
occurrence of the NLchar specified by the x parameter in
the string pointed to by the s parameter. A NULL pointer
is returned if the NLchar does not occur in the string.
The null character that terminates a string is considered
to be part of the string.
The NCstrrchr subroutine returns a pointer to the last
occurrence of the character specified by the x parameter
in the string pointed to by the s parameter. A NULL
pointer is returned if the NLchar does not occur in the
string. The null character that terminates a string is
considered to be part of the string.
The NCstrpbrk subroutine returns a pointer to the first
occurrence in the string pointed to by the xs1 parameter
of any code point from the string pointed to by the s2
parameter. A NULL pointer is returned if no character
matches.
The NCstrspn subroutine returns the length of the initial
segment of the string pointed to by the xs1 parameter
that consists entirely of code points from the string
pointed to by the s2 parameter.
The NCstrcspn subroutine returns the length of the
initial segment of the string pointed to by the xs1
parameter that consists entirely of code points not from
the string pointed to by the s2 parameter.
The NCstrtok subroutine returns a pointer to an occur-
rence of a text token in the string pointed to by the xs1
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 NCstrtok subroutine reads
the string pointed to by the xs1 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 NLchar of the text token. The
NCstrtok subroutine keeps track of its position in the
string so that subsequent calls with a NULL xs1 parameter
step through the string. The delimiters specified by the
s2 parameter can be changed for subsequent calls to
NCstrtok. When no tokens remain in the string pointed to
by the xs1 parameter, the NCstrtok subroutine returns a
NULL pointer.
Related Information
In this book: "NCcollate, NCcoluniq, NCeqvmap, _NCxcol,
_NLxcol," "NLchar," "NLstring," "NLstrtime," and
"string."
"Overview of International Character Support" in Managing
the AIX Operating System.