wstring(3C) wstring(3C)
NAME
wstring: wcscat, wcsncat, wcschr, wcsrchr, wcscmp, wcsncmp, wcscpy,
wcsncpy, wcsspn, wcscspn, wcslen, wcspbrk, wcstok, wcswcs, wcsstr -
wide character string operations
SYNOPSIS
#include <wchar.h>
wchart *wcscat(wchart *ws1, const wchart *ws2);
wchart *wcsncat(wchart *ws1, const wchart *ws2, sizet n);
wchart *wcschr(const wchart *ws1, wint wc);
wchart *wcsrchr(const wchart *ws, wintt wc);
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 *ws1, const wchart *ws2, sizet n);
sizet wcsspn(const wchart *ws1, const wchart *ws2);
sizet wcscspn(const wchart *ws1, const wchart *ws2);
sizet wcslen(const wchart *ws);
wchart wcspbrk(const wchart *ws1, const wchart *ws2);
wchart *wcstok(wchart *ws1, const wchart *ws2, wchart **ptr);
wchart *wcswcs(const wchart *ws1, const wchart *ws2);
wchart *wcsstr(const wchart *ws1, const wchart *ws2);
DESCRIPTION
The wcscat() function concatenates two wide character strings. In fact
it appends a copy of the wide character string pointed to by ws2
(including the terminating 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.
The wcsncat() function appends 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
Page 1 Reliant UNIX 5.44 Printed 11/98
wstring(3C) wstring(3C)
terminating null wide character code is always appended to the result.
If copying takes place between object that overlap, the behavior is
undefined.
The wcschr() function is a wide character string scanning operation.
It locates the first occurrence of wc in the wide character string
pointed to by ws1. 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 char-
acter code is considered to be part of the wide character string.
The wcsrchr() function locates 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 of wchart and must be a wide character code
corresponding to a valid character in the current locale. The ter-
minating null wide character code is considered to be part of the wide
character string.
The wcscmp() function compares 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.
The wcsncmp() function compares 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.
The wcscpy() function copies 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.
The wcsncpy() function copies 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 there is no null wide character code in the first n
wide character codes of the array pointed to by ws2, the result will
not be null-terminated. If the array pointed to by ws2 is a wide char-
acter 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 n wide character codes in all are written.
The wcsspn() function gets the length of a wide substring. It computes
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.
Page 2 Reliant UNIX 5.44 Printed 11/98
wstring(3C) wstring(3C)
The wcscspn() function gets the length of a complementary wide sub-
string. It computes 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.
The wcslen() function computes the number of wide character codes in
the wide character string to which ws points, not including the ter-
minating null wide character code.
The wcspbrk() function scans wide character strings for wide character
codes. It locates 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.
A sequence of calls to the wcstok() function breaks 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. 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.
The first call in the sequence has ws1 as its first argument, 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 con-
tained 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 the wcstok() function returns a
null pointer. If such a wide character code is found, it is start of
the first token.
The wcstok() function then searches from there 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 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() function saves a pointer to the fol-
lowing wide character code, from which the next search for a token
will start.
Each subsequent call, with a null pointer as the value for the first
argument, starts searching for the saved pointer and behaves as
described above.
The implementation will behave as if no function calls the wcstok()
function.
Page 3 Reliant UNIX 5.44 Printed 11/98
wstring(3C) wstring(3C)
The wcswcs() function locates the first occurrence in the wide charac-
ter string pointed to by ws1 of the sequence of wide character codes
(excluding the terminating null wide character code) in the wide char-
acter string pointed to by ws2.
The wcsstr() function locates the first occurrence in the wide charac-
ter string pointed to by ws1 of the sequence of wide characters codes
(excluding the terminating null wide character code) in the wide char-
acter string pointed to by ws2.
RETURN VALUES
The wcscat() function returns s1; no return value is reserved to indi-
cate an error.
The wcsncat() function returns ws1; no return value is reserved to
indicate an error.
Upon completion, wcschr() returns a pointer to the wide character
code, or a null pointer if the wide character code is not found.
Upon successful completion, wcsrchr() returns a pointer to the wide
character code or a null pointer if wc does not occur in the wide
character string.
Upon completion, wcscmp() returns an integer greater than, equal to or
less than 0, 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 respectively.
Upon successful completion, wcsncmp() returns an integer greater than,
equal to or less than 0, 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 respectively.
The wcscpy() function returns ws1; no return value is reserved to
indicate an error.
The wcsncpy() function returns ws1; no return value is reserved to
indicate an error.
The wcsspn() function returns the length of ws1; no return value is
reserved to indicate an error.
The wcscspn() function returns the length of ws1; no return value is
reserved to indicate an error.
The wcslen() function returns ws; no return value is reserved to indi-
cate an error.
Upon successful completion, wcspbrk() returns a pointer to the wide
character code or a null pointer if no wide character code from ws2
occurs in ws1.
Page 4 Reliant UNIX 5.44 Printed 11/98
wstring(3C) wstring(3C)
Upon successful completion, the wcstok() function returns a pointer to
the first wide character code of a token. Otherwise, if there is no
token, the function returns a null pointer.
Upon successful completion, the wcswcs() function returns a pointer to
the located wide character string, or a null pointer if the wide char-
acter string is not found. If ws2 points to a wide character string
with zero length, the function returns ws1.
Upon successful completion, the wcsstr() function returns a pointer to
the located wide character string, or a null pointer if the wide char-
acter string is not found. If ws2 points to a wide character string
with zero length, the function returns ws1.
SEE ALSO
wchar(5).
Page 5 Reliant UNIX 5.44 Printed 11/98