Standard C Library Functions wcstring(3C)
NAME
wcstring, wcscat, wscat, wcsncat, wsncat, wcscmp, wscmp,
wcsncmp, wsncmp, wcscpy, wscpy, wcsncpy, wsncpy, wcslen,
wslen, wcschr, wschr, wcsrchr, wsrchr, windex, wrindex,
wcspbrk, wspbrk, wcswcs, wcsspn, wsspn, wcscspn, wscspn,
wcstok, wstok - wide-character string operations
SYNOPSIS
#include
wchart *wcscat(wchart *ws1, const wchart *ws2);
wchart *wcsncat(wchart *restrict ws1, const wchart *restrict ws2,
sizet n);
int wcscmp(const wchart *ws1, const wchart *ws2);
int wcsncmp(const wchart *ws1, const wchart *ws2, sizet n);
wchart *wcscpy(wchart *ws1, const wchart *ws2);
wchart *wcsncpy(wchart *restrict ws1, const wchart *restrict ws2,
sizet n);
sizet wcslen(const wchart *ws);
wchart *wcschr(const wchart *ws, wchart wc);
wchart *wcsrchr(const wchart *ws, wchart wc);
wchart *wcspbrk(const wchart *ws1, const wchart *ws2);
wchart *wcswcs(const wchart *ws1, const wchart *ws2);
sizet wcsspn(const wchart *ws1, const wchart *ws2);
sizet wcscspn(const wchart *ws1, const wchart *ws2);
SunOS 5.11 Last change: 14 Aug 2002 1
Standard C Library Functions wcstring(3C)
XPG4, SUS, SUSv2, SUSv3
wchart *wcstok(wchart *restrict ws1, const wchart *restrict ws2);
Default and other standards
wchart *wcstok(wchart *ws1, const wchart *ws2, wchart **ptr);
#include
wchart *wscat(wchart *ws1, const wchart *ws2);
wchart *wsncat(wchart *ws1, const wchart *ws2, sizet n);
int wscmp(const wchart *ws1, const wchart *ws2);
int wsncmp(const wchart *ws1, const wchart *ws2, sizet n);
wchart *wscpy(wchart *ws1, const wchart *ws2);
wchart *wsncpy(wchart *ws1, const wchart *ws2, sizet n);
sizet wslen(const wchart *ws);
wchart *wschr(const wchart *ws, wchatt wc);
wchart *wsrchr(const wchart *ws, wchatt wc);
wchart *wspbrk(const wchart *ws1, const wchart *ws2);
sizet wsspn(const wchart *ws1, const wchart *ws2);
sizet wscspn(const wchart *ws1, const wchart *ws2);
wchart *wstok(wchart *ws1, const wchart *ws2);
wchart *windex(const wchart *ws, wchart wc);
SunOS 5.11 Last change: 14 Aug 2002 2
Standard C Library Functions wcstring(3C)
wchart *wrindex(const wchart *ws, wchart wc);
ISO C]
#include
const wchart *wcschr(const wchart *ws, wchart wc);
const wchart *wcspbrk(const wchart *ws1, const wchart *ws2);
const wchart *wcsrchr(const wchart *ws, wchart wc);
#include
wchart *std::wcschr(wchart *ws, wchart wc);
wchart *std::wcspbrk(wchart *ws1, const wchart *ws2);
wchart *std::wcsrchr(wchart *ws, wchart wc);
DESCRIPTION
These functions operate on wide-character strings terminated
by wchart NUL characters. During appending or copying,
these routines do not check for an overflow condition of the
receiving string. In the following, ws, ws1, and ws2 point
to wide-character strings terminated by a wchart NUL.
wcscat(), wscat()
The wcscat() and wscat() functions append a copy of the
wide-character string pointed to by ws2 (including the ter-
minating null wide-character code) to the end of the wide-
character string pointed to by ws1. The initial wide-
character code of ws2 overwrites the null wide-character
code at the end of ws1. If copying takes place between
objects that overlap, the behavior is undefined. Both func-
tions return s1; no return value is reserved to indicate an
error.
wcsncat(), wsncat()
The wcsncat() and wsncat() functions append not more than n
wide-character codes (a null wide-character code and wide-
character codes that follow it are not appended) from the
array pointed to by ws2 to the end of the wide-character
string pointed to by ws1. The initial wide-character code of
ws2 overwrites the null wide-character code at the end of
ws1. A terminating null wide-character code is always
SunOS 5.11 Last change: 14 Aug 2002 3
Standard C Library Functions wcstring(3C)
appended to the result. Both functions return ws1; no return
value is reserved to indicate an error.
wcscmp(), wscmp()
The wcscmp() and wscmp() functions compare the wide-
character string pointed to by ws1 to the wide-character
string pointed to by ws2. The sign of a non-zero return
value is determined by the sign of the difference between
the values of the first pair of wide-character codes that
differ in the objects being compared. Upon completion, both
functions return an integer greater than, equal to, or less
than zero, if the wide-character string pointed to by ws1 is
greater than, equal to, or less than the wide-character
string pointed to by ws2.
wcsncmp(), wsncmp()
The wcsncmp() and wsncmp() functions compare not more than n
wide-character codes (wide-character codes that follow a
null wide character code are not compared) from the array
pointed to by ws1 to the array pointed to by ws2. The sign
of a non-zero return value is determined by the sign of the
difference between the values of the first pair of wide-
character codes that differ in the objects being compared.
Upon successful completion, both functions return an integer
greater than, equal to, or less than zero, if the possibly
null-terminated array pointed to by ws1 is greater than,
equal to, or less than the possibly null-terminated array
pointed to by ws2.
wcscpy(), wscpy()
The wcscpy() and wscpy() functions copy the wide-character
string pointed to by ws2 (including the terminating null
wide-character code) into the array pointed to by ws1. If
copying takes place between objects that overlap, the
behavior is undefined. Both functions return ws1; no return
value is reserved to indicate an error.
wcsncpy(), wsncpy()
The wcsncpy() and wsncpy() functions copy not more than n
wide-character codes (wide-character codes that follow a
null wide character code are not copied) from the array
pointed to by ws2 to the array pointed to by ws1. If copying
takes place between objects that overlap, the behavior is
undefined. If the array pointed to by ws2 is a wide-
character string that is shorter than n wide-character
codes, null wide-character codes are appended to the copy in
the array pointed to by ws1, until a total n wide-character
codes are written. Both functions return ws1; no return
value is reserved to indicate an error.
wcslen(), wslen()
SunOS 5.11 Last change: 14 Aug 2002 4
Standard C Library Functions wcstring(3C)
The wcslen() and wslen() functions compute the number of
wide-character codes in the wide-character string to which
ws points, not including the terminating null wide-character
code. Both functions return ws; no return value is reserved
to indicate an error.
wcschr(), wschr()
The wcschr() and wschr() functions locate the first
occurrence of wc in the wide-character string pointed to by
ws. The value of wc must be a character representable as a
type wchart and must be a wide-character code corresponding
to a valid character in the current locale. The terminating
null wide-character code is considered to be part of the
wide-character string. Upon completion, both functions
return a pointer to the wide-character code, or a null
pointer if the wide-character code is not found.
wcsrchr(), wsrchr()
The wcsrchr() and wsrchr() functions locate the last
occurrence of wc in the wide-character string pointed to by
ws. The value of wc must be a character representable as a
type wchart and must be a wide-character code corresponding
to a valid character in the current locale. The terminating
null wide-character code is considered to be part of the
wide-character string. Upon successful completion, both
functions return a pointer to the wide-character code, or a
null pointer if wc does not occur in the wide-character
string.
windex(), wrindex()
The windex() and wrindex() functions behave the same as
wschr() and wsrchr(), respectively.
wcspbrk(), wspbrk()
The wcspbrk() and wspbrk() functions locate the first
occurrence in the wide character string pointed to by ws1 of
any wide-character code from the wide-character string
pointed to by ws2. Upon successful completion, the function
returns a pointer to the wide-character code, or a null
pointer if no wide-character code from ws2 occurs in ws1.
wcswcs()
The wcswcs() function locates the first occurrence in the
wide-character string pointed to by ws1 of the sequence of
wide-character codes (excluding the terminating null wide-
character code) in the wide-character string pointed to by
ws2. Upon successful completion, the function returns a
pointer to the located wide-character string, or a null
pointer if the wide-character string is not found. If ws2
points to a wide-character string with zero length, the
function returns ws1.
SunOS 5.11 Last change: 14 Aug 2002 5
Standard C Library Functions wcstring(3C)
wcsspn(), wsspn()
The wcsspn() and wsspn() functions compute the length of the
maximum initial segment of the wide-character string pointed
to by ws1 which consists entirely of wide-character codes
from the wide-character string pointed to by ws2. Both func-
tions return the length ws1; no return value is reserved to
indicate an error.
wcscspn(), wscspn()
The wcscspn() and wscspn() functions compute the length of
the maximum initial segment of the wide-character string
pointed to by ws1 which consists entirely of wide-character
codes not from the wide-character string pointed to by ws2.
Both functions return the length of the initial substring of
ws1; no return value is reserved to indicate an error.
wcstok(), wstok()
A sequence of calls to the wcstok() and wstok() functions
break the wide-character string pointed to by ws1 into a
sequence of tokens, each of which is delimited by a wide-
character code from the wide-character string pointed to by
ws2.
Default and other standards
The third argument points to a caller-provided wchart
pointer into which the wcstok() function stores information
necessary for it to continue scanning the same wide-
character string. This argument is not available with the
XPG4 and SUS versions of wcstok(), nor is it available with
the wstok() function. See standards(5).
The first call in the sequence has ws1 as its first argu-
ment, and is followed by calls with a null pointer as their
first argument. The separator string pointed to by ws2 may
be different from call to call.
The first call in the sequence searches the wide-character
string pointed to by ws1 for the first wide-character code
that is not contained in the current separator string
pointed to by ws2. If no such wide-character code is found,
then there are no tokens in the wide-character string
pointed to by ws1, and wcstok() and wstok() return a null
pointer. If such a wide-character code is found, it is the
start of the first token.
The wcstok() and wstok() functions then search from that
point for a wide-character code that is contained in the
current separator string. If no such wide-character code is
found, the current token extends to the end of the wide-
SunOS 5.11 Last change: 14 Aug 2002 6
Standard C Library Functions wcstring(3C)
character string pointed to by ws1, and subsequent searches
for a token will return a null pointer. If such a wide-
character code is found, it is overwritten by a null wide
character, which terminates the current token. The wcstok()
and wstok() functions save a pointer to the following wide-
character code, from which the next search for a token will
start.
Each subsequent call, with a null pointer as the value of
the first argument, starts searching from the saved pointer
and behaves as described above.
Upon successful completion, both functions return a pointer
to the first wide-character code of a token. Otherwise, if
there is no token, a null pointer is returned.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
CSI Enabled
Interface Stability See NOTES.
MT-Level MT-Safe
SEE ALSO
malloc(3C), string(3C), wcswidth(3C), wcwidth(3C), attri-
butes(5), standards(5)
NOTES
The wcscat(), wcsncat(), wcscmp(), wcsncmp(), wcscpy(),
wcsncpy(), wcslen(), wcschr(), wcsrchr(), wcspbrk(),
wcswcs(), wcsspn(), wcscspn(), and wcstok() functions are
Standard. The wscat(), wsncat(), wscmp(), wsncmp(), wscpy(),
wsncpy(), wslen(), wschr(), wsrchr(), wspbrk(), wsspn(),
wstok(), windex(), and wrindex() functions are Stable.
SunOS 5.11 Last change: 14 Aug 2002 7
|
