wstring Subroutine

Purpose

Perform operations on wide character strings.

Library

Standard C Library (libc.a)

Syntax

Description

The wstring subroutines copy, compare, and append strings in memory, and determine location, size, and existence of strings in memory. For these subroutines, a string is an array of wchar_t characters, terminated by a null character. The wstring subroutines parallel the string subroutines, but operate on strings of type wchar_t rather than on type char, except as specifically noted below.

The parameters XString1, XString2, and XString point to strings of type wchar_t (arrays of wchar characters terminated by a wchar_t null character).

The subroutines wstrcat, wstrncat, wstrcpy, and wstrncpy all alter the XString1 parameter. They do not check for overflow of the array pointed to by XString1. All string movement is performed wide character by wide character. 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 wstring.h file.

The wstrcat subroutine appends a copy of the wchar_t string pointed to by the XString2 parameter to the end of the wchar_t string pointed to by the XString1 parameter. The wstrcat subroutine returns a pointer to the null-terminated result.

The wstrncat subroutine copies, at most, the value of the Number parameter of wchar_ t characters in the XString2 parameter to the end of the wchar_t string pointed to by the XString1 parameter. Copying stops before Number wchar_t character if a null character is encountered in the string pointed to by the XString2 parameter. The wstrncat subroutine returns a pointer to the null-terminated result.

The wstrcmp subroutine lexicographically compares the wchar_t string pointed to by the XString1 parameter to the wchar_t string pointed to by the XString2 parameter. The wstrcmp subroutine returns a value that is:

• Less than 0 if XString1 is less than XString2
• Equal to 0 if XString1 is equal to XString2
• Greater than 0 if XString1 is greater than XString2

The wstrncmp subroutine makes the same comparison as wstrcmp, but it compares, at most, the value of the Number parameter of pairs of wchar characters. The comparisons are based on collation values as determined by the locale category LC_COLLATE and the LANG variable.

The wstrcpy subroutine copies the string pointed to by the XString2 parameter to the array pointed to by the XString1 parameter. Copying stops when the wchar_t null is copied. The wstrcpy subroutine returns the value of the XString1 parameter.

The wstrncpy subroutine copies the value of the Number parameter of wchar_t characters from the string pointed to by the XString2 parameter to the wchar_t array pointed to by the XString1 parameter. If XString2 is less than Number wchar_t characters long, then wstrncpy pads XString1 with trailing null characters to fill Number wchar_t characters. If XString2 is Number or more wchar_t characters long, only the first Number wchar_t characters are copied; the result is not terminated with a null character. The wstrncpy subroutine returns the value of the XString1 parameter.

The wstrlen subroutine returns the number of wchar_t characters in the string pointed to by the XString parameter, not including the terminating wchar_t null.

The wstrchr subroutine returns a pointer to the first occurrence of the wchar_t specified by the Number parameter in the wchar_t string pointed to by the XString parameter. A null pointer is returned if the wchar_t does not occur in the wchar_t string. The wchar_t null that terminates a string is considered to be part of the wchar_t string.

The wstrrchr subroutine returns a pointer to the last occurrence of the character specified by the Number parameter in the wchar_t string pointed to by the XString parameter. A null pointer is returned if the wchar_t does not occur in the wchar_t string. The wchar_t null that terminates a string is considered to be part of the wchar_t string.

The wstrpbrk subroutine returns a pointer to the first occurrence in the wchar_t string pointed to by the XString1 parameter of any code point from the string pointed to by the XString2 parameter. A null pointer is returned if no character matches.

The wstrspn subroutine returns the length of the initial segment of the string pointed to by the XString1 parameter that consists entirely of code points from the wchar_t string pointed to by the XString2 parameter.

The wstrcspn subroutine returns the length of the initial segment of the wchar_t string pointed to by the XString1 parameter that consists entirely of code points not from the wchar_t string pointed to by the XString2 parameter.

The wstrtok subroutine returns a pointer to an occurrence of a text token in the string pointed to by the XString1 parameter. The XString2 parameter specifies a set of code points as token delimiters. If the XString1 parameter is anything other than null, then the wstrtok subroutine reads the string pointed to by the XString1 parameter until it finds one of the delimiter code points specified by the XString2 parameter. It then stores a wchar_t null into the wchar_t string, replacing the delimiter code point, and returns a pointer to the first wchar_t of the text token. The wstrtok subroutine keeps track of its position in the wchar_t string so that subsequent calls with a null XString1 parameter step through the wchar_t string. The delimiters specified by the XString2 parameter can be changed for subsequent calls to wstrtok. When no tokens remain in the wchar_t string pointed to by the XString1 parameter, the wstrtok subroutine returns a null pointer.

The wstrdup subroutine returns a pointer to a wchar_t string that is a duplicate of the wchar_t string to which the XString1 parameter points. Space for the new string is allocated using the malloc subroutine. When a new string cannot be created, a null pointer is returned.