From kido@vnet.IBM.COM Mon Mar 15 04:34:29 1993 Received: from vnet.IBM.COM ([192.239.48.4]) by dkuug.dk with SMTP id AA00287 (5.65c8/IDA-1.4.4j); Mon, 15 Mar 1993 03:06:56 +0100 Message-Id: <199303150206.AA00287@dkuug.dk> Received: from YMTVM8 by vnet.IBM.COM (IBM VM SMTP V2R2) with BSMTP id 4033; Sun, 14 Mar 93 21:06:15 EST Date: Mon, 15 Mar 93 11:06:41 JST From: "Akio Kido" To: sc22wg15@dkuug.dk, sc22wg20@dkuug.dk, XoJIG@xopen.co.uk, sig-international@osf.org, uojlg-bse@uiap.ui.org, efischer@donald.aix.kingston.ibm.com Subject: MSE 4.5.4.2.mm X-Charset: ASCII X-Char-Esc: 29 .SK .H 4 "Wide string copying functions" .P For the functions of this subclause, if copying takes place between objects that overlap, the behavior is undefined. .H 5 "The \*(Cwwcscpy\fP function" .HU Synopsis .Cb #include wchar_t *wcscpy(wchar_t *s1, const wchar_t *s2); .Ce .HU Description .P The .Cf wcscpy function copies the wide string pointed to by .Cf s2 (including the terminating null wide character) into the array pointed to by .Cf s1 . .HU Returns .P The .Cf wcscpy function returns the value of .Cf s1 . .H 5 "The \*(Cwwcsncpy\fP function" .HU Synopsis .Cb #include wchar_t *wcsncpy(wchar_t *s1, const wchar_t *s2, size_t n); .Ce .HU Description .P The .Cf wcsncpy function copies not more than .Cf n wide characters (those that follow a null wide character are not copied) from the array pointed to by .Cf s2 to the array pointed to by .Cf s1 .\*F .FS Thus, if there is no null wide character in the first .Cf n wide characters of the array pointed to by .Cf s2 , the result will not be null-terminated. .FE .P If the array pointed to by .Cf s2 is a wide string that is shorter than .Cf n wide characters, null wide characters are appended to the copy in the array pointed to by .Cf s1 , until .Cf n wide characters in all have been written. .HU Returns .P The .Cf wcsncpy function returns the value of .Cf s1 . .H 4 "Wide string concatenation functions" .P For the functions of this subclause, if copying takes place between objects that overlap, the behavior is undefined. .H 5 "The \*(Cwwcscat\fP function" .HU Synopsis .Cb #include wchar_t *wcscat(wchar_t *s1, const wchar_t *s2); .Ce .HU Description .P The .Cf wcscat function appends a copy of the wide string pointed to by .Cf s2 (including the terminating null wide character) to the end of the wide string pointed to by .Cf s1 . The initial wide character of .Cf s2 overwrites the null wide character at the end of .Cf s1 . .HU Returns .P The .Cf wcscat function returns the value of .Cf s1 . .H 5 "The \*(Cwwcsncat\fP function" .HU Synopsis .Cb #include wchar_t *wcsncat(wchar_t *s1, const wchar_t *s2, size_t n); .Ce .HU Description .P The .Cf wcsncat function appends not more than .Cf n wide characters (a null wide character and those that follow it are not appended) from the array pointed to by .Cf s2 to the end of the wide string pointed to by .Cf s1 . The initial wide character of .Cf s2 overwrites the null wide character at the end of .Cf s1 . A terminating null wide character is always appended to the result.\*F .FS Thus, the maximum number of wide characters that can end up in the array pointed to by .Cf s1 is .Cf wcslen(s1)+n+1 . .FE .HU Returns .P The .Cf wcsncat function returns the value of .Cf s1 . .H 4 "Wide string comparison functions" .H 5 "The \*(Cwwcscmp\fP function" .HU Synopsis .Cb #include int wcscmp(const wchar_t *s1, const wchar_t *s2); .Ce .HU Description .P The .Cf wcscmp function compares the wide string pointed to by .Cf s1 to the wide string pointed to by .Cf s2 . .HU Returns .P The .Cf wcscmp function returns an integer greater than, equal to, or less than zero, accordingly as the wide string pointed to by .Cf s1 is greater than, equal to, or less than the wide string pointed to by .Cf s2 . .H 5 "The \*(Cwwcscoll\fP function" .HU Synopsis .Cb #include int wcscoll(const wchar_t *s1, const wchar_t *s2); .Ce .HU Description The .Cf wcscoll function compares the wide string pointed to by .Cf s1 to the wide string pointed to by .Cf s2 , both interpreted as appropriate to the .Cf LC_COLLATE category of the current locale. .HU Returns .P The .Cf strcoll function returns an integer greater than, equal to, or less than zero, accordingly as the wide string pointed to by .Cf s1 is greater than, equal to, or less than the wide string pointed to by .Cf s2 when both are interpreted as appropriate to the current locale. .H 5 "The \*(Cwwcsncmp\fP function" .HU Synopsis .Cb #include int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n); .Ce .HU Description .P The .Cf wcsncmp function compares not more than .Cf n wide characters (those that follow a null wide character are not compared) from the array pointed to by .Cf s1 to the array pointed to by .Cf s2 . .HU Returns .P The .Cf wcsncmp function returns an integer greater than, equal to, or less than zero, accordingly as the possibly null-terminated array pointed to by .Cf s1 is greater than, equal to, or less than the possibly null-terminated array pointed to by .Cf s2 . .H 5 "The \*(Cwwcsxfrm\fP function" .HU Synopsis .Cb #include size_t wcsxfrm(wchar_t *s1, const wchar_t *s2, size_t n); .Ce .HU Description .P The .Cf wcsxfrm function transforms the wide string pointed to by .Cf s2 and places the resulting wide string into the array pointed to by .Cf s1 . The transformation is such that if the .Cf wcscmp function is applied to two transformed wide strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .Cf wcscoll function applied to the same two original wide strings. No more than .Cf n wide characters are placed into the resulting array pointed to by .Cf s1 , including the terminating null wide character. If .Cf n is zero, .Cf s1 is permitted to be a null pointer. If copying takes place between objects that overlap, the behavior is undefined. .HU Returns .P The .Cf wcsxfrm function returns the length of the transformed wide string (not including the terminating null wide character). If the value returned is .Cf n or more, the contents of the array pointed to by .Cf s1 are indeterminate. .HU Example .P The value of the following expression is the length of the array needed to hold the transformation of the wide string pointed to by .Cf s . .Cb 1 + wcsxfrm(NULL, s, 0) .Ce .H 4 "Wide string search functions" .H 5 "The \*(Cwwcschr\fP function" .HU Synopsis .Cb #include wchar_t *wcschr(const wchar_t *s, wint_t c); .Ce .HU Description .P The .Cf wcschr function locates the first occurrence of .Cf c in the wide string pointed to by .Cf s . The terminating null wide character is considered to be part of the wide string. .HU Returns .P The .Cf wcschr function returns a pointer to the located wide character, or a null pointer if the wide character does not occur in the wide string. .H 5 "The \*(Cwwcscspn\fP function" .HU Synopsis .Cb #include size_t wcscspn(const wchar_t *s1, const wchar_t *s2); .Ce .HU Description .P The .Cf wcscspn function computes the length of the maximum initial segment of the wide string pointed to by .Cf s1 which consists entirely of wide characters .I not from the wide string pointed to by .Cf s2 . .HU Returns .P The .Cf wcscspn function returns the length of the segment. .H 5 "The \*(Cwwcspbrk\fP function" .HU Synopsis .Cb #include wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2); .Ce .HU Description .P The .Cf wcspbrk function locates the first occurrence in the wide string pointed to by .Cf s1 of any wide character from the wide string pointed to by .Cf s2 . .HU Returns .P The .Cf wcspbrk function returns a pointer to the wide character, or a null pointer if no wide character from .Cf s2 occurs in .Cf s1 . .H 5 "The \*(Cwwcsrchr\fP function" .HU Synopsis .Cb #include wchar_t *wcsrchr(const wchar_t *s, wint_t c); .Ce .HU Description .P The .Cf wcsrchr function locates the last occurrence of .Cf c in the wide string pointed to by .Cf s . The terminating null wide character is considered to be part of the wide string. .HU Returns .P The .Cf wcsrchr function returns a pointer to the wide character, or a null pointer if .Cf c does not occur in the wide string. .H 5 "The \*(Cwwcsspn\fP function" .HU Synopsis .Cb #include size_t wcsspn(const wchar_t *s1, const wchar_t *s2); .Ce .HU Description .P The .Cf wcsspn function computes the length of the maximum initial segment of the wide string pointed to by .Cf s1 which consists entirely of wide characters from the wide string pointed to by .Cf s2 . .HU Returns .P The .Cf wcsspn function returns the length of the segment. .H 5 "The \*(Cwwcsstr\fP function" .HU Synopsis .Cb #include wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); .Ce .HU Description .P The .Cf wcsstr function locates the first occurrence in the wide string pointed to by .Cf s1 of the sequence of wide characters (excluding the terminating null wide character) in the wide string pointed to by .Cf s2 .HU Returns .P The .Cf wcsstr function returns a pointer to the located wide string, or a null pointer if the wide string is not found. If .Cf s2 points to a wide string with zero length, the function returns .Cf s1 . .H 5 "The \*(Cwwcstok\fP function" .HU Synopsis .Cb #include wchar_t *wcstok(wchar_t *s1, const wchar_t *s2, wchar_t **ptr); .Ce .HU Description .P A sequence of calls to the .Cf wcstok function breaks the wide string pointed to by .Cf s1 into a sequence of tokens, each of which is delimited by a wide character from the wide string pointed to by .Cf s2 . The third argument points to a caller-provided .Cf wchar_t pointer into which the .Cf wcstok function stores information necessary for it to continue scanning the same wide string. .P For the first call in the sequence, .Cf s1 shall point to a wide string, while in subsequent calls for the same string, .Cf s1 shall be a null pointer. If .Cf s1 is a null pointer, the value pointed to by .Cf ptr shall match that set by the previous call for the same wide string; otherwise its value is ignored. The separator wide string pointed to by .Cf s2 may be different from call to call. .P The first call in the sequence searches the wide string pointed to by .Cf s1 for the first wide character that is .I not contained in the current separator wide string pointed to by .Cf s2 . If no such wide character is found, then there are no tokens in the wide string pointed to by .Cf s1 and the .Cf wcstok function returns a null pointer. If such a wide character is found, it is the start of the first token. .P The .Cf wcstok function then searches from there for a wide character that .I is contained in the current separator wide string. If no such wide character is found, the current token extends to the end of the wide string pointed to by .Cf s1 , and subsequent searches in the same wide string for a token shall return a null pointer. If such a wide character is found, it is overwritten by a null wide character, which terminates the current token. .P In all cases, the .Cf wcstok function stores sufficient information in the pointer pointed to by .Cf ptr so that subsequent calls, with a null pointer for .Cf s1 and the unmodified pointer value for .Cf ptr , shall start searching just past the end of the previously returned token (if any). .HU Returns .P The .Cf wcstok function returns a pointer to the first wide character of a token, or a null pointer if there is no token. .HU Example .Cb #include static wchar_t str1[] = L"?a???b,,,#c"; static wchar_t str2[] = L"\et \et"; wchar_t *t, *ptr1, *ptr2; .sp .5v t = wcstok(str1, L"?", &ptr1); /* t \fIpoints to the token\fP L"a" */ t = wcstok(NULL, L",", &ptr1); /* t \fIpoints to the token\fP L"??b" */ t = wcstok(str2, L" \et", &ptr2); /* t \fIis a null pointer\fP */ t = wcstok(NULL, L"#,", &ptr1); /* t \fIpoints to the token\fP L"c" */ t = wcstok(NULL, L"?", &ptr1); /* t \fIis a null pointer\fP */ .Ce .H 5 "The \*(Cwwcslen\fP function" .HU Synopsis .Cb #include size_t wcslen(const wchar_t *s); .Ce .HU Description .P The .Cf wcslen function computes the length of the wide string pointed to by .Cf s . .HU Returns .P The .Cf wcslen function returns the number of wide characters that precede the terminating null wide character.