wstring(3) — Subroutines
OSF
NAME
wstrcat, wstrchr, wstrcmp, wstrcpy, wstrcspn, wstrdup, wstrlen, wstrncat, wstrncmp, wstrncpy, wstrpbrk, wstrrchr, wstrspn, wstrtok − Performs operations on wide character strings
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <wstring.h>
wchar_t ∗wstrcat (
wchar_t ∗ws1,
wchar_t ∗ws2 );
wchar_t ∗wstrncat (
wchar_t ∗ws1,
wchar_t ∗ws2,
int n );
int wstrcmp (
wchar_t ∗ws1,
wchar_t ∗ws2 );
int wstrncmp (
wchar_t ∗ws1,
wchar_t ∗ws2,
int n );
wchar_t ∗wstrcpy (
wchar_t ∗ws1,
wchar_t ∗ws2 );
wchar_t ∗wstrncpy (
wchar_t ∗ws1,
wchar_t ∗ws2,
int n );
size_t wstrlen (
wchar_t ∗ws );
wchar_t ∗wstrchr (
wchar_t ∗ws,
int n );
wchar_t ∗wstrrchr (
wchar_t ∗ws,
int n );
wchar_t ∗wstrpbrk (
wchar_t ∗ws1,
wchar_t ws2;
size_t wstrspn (
wchar_t ∗ws1,
wchar_t ws2 );
size_t wstrcspn (
wchar_t ∗ws1,
wchar_t ws2 );
wchar_t ∗wstrtok (
wchar_t ∗ws1,
wchar_t ws2 );
wchar_t ∗wstrdup (
wchar_t ∗ws1 );
PARAMETERS
ws, ws1, ws2
Pointers to strings of type wchar_t (arrays of wide characters terminated by a wchar_t null character).
DESCRIPTION
The wstring functions copy, compare, and append strings in memory, and determine such things as location, size, and existence of strings in memory. For these functions, a string is an array of wide characters, terminated by a null character. The wstring functions parallel the string functions, but operate on strings of type wchar_t rather than on type char, except as noted below.
These functions require their parameters to be explicitly converted to type wchar_t, so they should be used on input that will be scanned many times for each time it is converted.
The ws1, ws2, and ws parameters point to strings of type wchar_t.
The wstrcat(), wstrncat(), wstrcpy(), and wstrncpy() functions all alter the ws1 parameter. They do not check for overflow of the array pointed to by ws1. All string movement is performed character by character and starts at the left. Overlapping moves toward the left work as expected, but overlapping moves toward the right may give unexpected results. All of these functions are declared in the wstring.h header file.
The wstrcat() function appends a copy of the ws2 string to the end of the ws1 string. The wstrcat() function returns a pointer to the null-terminated result.
The wstrncat() function copies, at most, n wchar_ts in the ws2 parameter to the end of the string pointed to by the ws1 parameter. Copying stops before n wchar_ts if a null character is encountered in the string pointed to by the ws2 parameter. The wstrncat() function returns a pointer to the null-terminated result.
The wstrcmp() function lexicographically compares the ws1 string to the ws2 string. The wstrcmp() function returns a value that is less than 0 (zero) if ws1 is less than ws2, equal to 0 if ws1 is equal to ws2, and greater than 0 if ws1 is greater than ws2.
The wstrncmp() function makes the same comparison as the wstrcmp() function, but it compares, at most, the value of the n parameter of pairs of wchars. Both wstrcmp() and wstrncmp() use the environment variable NLCTAB to determine the collating sequence for performing comparisons.
The wstrcpy() function copies the ws2 string to the ws1 string. Copying stops when the wchar_t null character is copied. The wstrcpy() function returns the value of the ws1 parameter.
The wstrncpy() function copies the value of the n parameter of wchar_ts from the ws2 string to the ws1 string. If ws2 is less than n wchar_ts long, then wstrncpy() pads ws1 with trailing null characters to fill n wchar_ts. If ws2 is n or more wchar_ts long, then only the first n wchar_ts are copied; the result is not terminated with a null character. The wstrncpy() function returns the value of the ws1 parameter.
The wstrlen() function returns the number of wchar_ts in the string pointed to by the ws parameter, not including the terminating wchar_t null character.
The wstrchr() function returns a pointer to the first occurrence of the wchar_t specified by the n parameter in the ws string. A null pointer is returned if the wchar_t specified by n does not occur in the ws string. The wchar_t null character that terminates a string is considered to be part of the ws string.
The wstrrchr() function returns a pointer to the last occurrence of the wchar_t specified by the n parameter in the ws string. A null pointer is returned if the wchar_t does not occur in the ws string. The wchar_t null character that terminates a string is considered to be part of the wchar_t string.
The wstrpbrk() function returns a pointer to the first occurrence in the ws1 string of any code point from the ws2 string. A null pointer is returned if no character matches.
The wstrspn() function returns the length of the initial segment of the ws1 string that consists entirely of code points from the ws2 string.
The wstrcspn() function returns the length of the initial segment of the ws1 string that consists entirely of code points not from the ws2 string.
The wstrtok() function returns a pointer to an occurrence of a text token in the ws1 string. The ws2 parameter specifies a set of code points as token delimiters. If the ws1 parameter is anything other than null, then the wstrtok() function reads the string pointed to by the ws1 parameter until it finds one of the delimiter code points specified by the ws2 parameter. It then stores a wchar_t null character in the wchar_t string, replacing the delimiter code point, and returns a pointer to the first wchar_t of the text token. The wstrtok() function keeps track of its position in the wchar_t string so that subsequent calls with a null ws1 parameter step through the wchar_t string. The delimiters specified by the ws2 parameter can be changed for subsequent calls to wstrtok(). When no tokens remain in the wchar_t string pointed to by the ws1 parameter, the wstrtok() function returns a null pointer.
The wstrdup() function returns a pointer to a wchar_t string that is a duplicate of the wchar_t string to which the ws1 parameter points. Space for the new string is allocated using the malloc() function. When a new string cannot be created, a null pointer is returned.