NCSTRING(3,L) AIX Technical Reference NCSTRING(3,L)
-------------------------------------------------------------------------------
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; unsigned char *s2;
NLchar *NCstrcpy (xs1, xs2) int NCstrcspn (xs1, s2)
NLchar *xs1, *xs2; NLchar *xs1;
unsigned char *s2;
NLchar *NCstrncpy (xs1, xs2, n)
NLchar *xs1, *xs2; NLchar *NCstrtok (xs1, s2)
int n; NLchar *xs1;
unsigned char *s2;
int NCstrlen (xs)
NLchar *xs;
DESCRIPTION
Note: In the multibyte environment, the NCstring routines are provided for
backward compatibility. These routines are only front-ends to the
wcstring routines (see "wcstring"). Avoid using them if you wish to
write portable programs.
Processed November 7, 1990 NCSTRING(3,L) 1
NCSTRING(3,L) AIX Technical Reference NCSTRING(3,L)
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 subroutines, 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 specifically 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 performance
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 character). 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 LANG or LC_COLLATE 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
Processed November 7, 1990 NCSTRING(3,L) 2
NCSTRING(3,L) AIX Technical Reference NCSTRING(3,L)
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 parameter.
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 occurrence 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 anything 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
Processed November 7, 1990 NCSTRING(3,L) 3
NCSTRING(3,L) AIX Technical Reference NCSTRING(3,L)
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," "string," and "wcstring."
"Introduction to International Character Support" in Managing the AIX Operating
System.
AIX Guide to Multibyte Character Set (MBCS) Support.
Processed November 7, 1990 NCSTRING(3,L) 4