[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

wcscat, wcschr, wcscmp, wcscpy, or wcscspn Subroutine

Purpose

Performs operations on wide-character strings.

Library

Standard C Library (libc.a)

Syntax

#include <string.h>
wchar_t *wcscat(WcString1WcString2)
wchar_t *WcString1;
const wchar_t *WcString2;
wchar_t *wcschr(WcStringWideCharacter)
const wchar_t *WcString;
wchar_t WideCharacter;
int *wcscmp (WcString1WcString2)
const wchar_t *WcString1, *WcString2;
wchar_t *wcscpy(WcString1WcString2)
wchar_t *WcString1;
const wchar_t 
*
WcString2;
size_t wcscspn(WcString1WcString2)
const wchar_t *WcString1, *WcString2;

Description

The wcscat, wcschr, wcscmp, wcscpy, or wcscspn subroutine operates on null-terminated wchar_t strings. These subroutines expect the string arguments to contain a wchar_t null character marking the end of the string. A copy or concatenation operation does not perform boundary checking.

The wcscat subroutine appends a copy of the wide-character string pointed to by the WcString2 parameter (including the terminating null wide-character code) to the end of the wide-character string pointed to by the WcString1 parameter. The initial wide-character code of the WcString2 parameter overwrites the null wide-character code at the end of the WcString1 parameter. If successful, the wcscat subroutine returns the WcString1 parameter.

The wcschr subroutine returns a pointer to the first occurrence of the WideCharacter parameter in the WcString parameter. The character value may be a wchar_t null character. The wchar_t null character at the end of the string is included in the search. The wcschr subroutine returns a pointer to the wide character code, if found, or returns a null pointer if the wide character is not found.

The wcscmp subroutine compares two wchar_t strings. It returns an integer greater than 0 if the WcString1 parameter is greater than the WcString2 parameter. It returns 0 if the two strings are equivalent. It returns a number less than 0 if the WcString1 parameter is less than the WcString2 parameter. The sign of the difference in value between the first pair of wide-character codes that differ in the objects being compared determines the sign of a nonzero return value.

The wcscpy subroutine copies the contents of the WcString2 parameter (including the ending wchar_t null character) into the WcString1 parameter. If successful, the wcscpy subroutine returns the WcString1 parameter. If the wcscpy subroutine copies between overlapping objects, the result is undefined.

The wcscspn subroutine computes the number of wchar_t characters in the initial segment of the string pointed to by the WcString1 parameter that do not appear in the string pointed to by the WcString2 parameter. If successful, the wcscspn subroutine returns the number of wchar_t characters in the segment.

Parameters

WcString1 Points to a wide-character string.
WcString2 Points to a wide-character string.
WideCharacter Specifies a wide character for location.

Return Values

Upon successful completion, the wcscat and wcscpy subroutines return a value of ws1. The wcschr subroutine returns a pointer to the wide character code. Otherwise, a null pointer is returned.

The wcscmp subroutine returns an integer greater than, equal to, or less than 0, if the wide character string pointed to by the WcString1 parameter is greater than, equal to, or less than the wide character string pointed to by the WcString2 parameter.

The wcscspn subroutine returns the length of the segment.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The mbscat subroutine, mbschr subroutine, mbscmp subroutine, mbscpy subroutine, mbsrchr subroutine, wcsncat subroutine, wcsncmp subroutine, wcsncpy subroutine, wcsrchr subroutine.

National Language Support Overview for Programming, Subroutines Overview, Understanding Wide Character String Comparison Subroutines, Understanding Wide Character String Copy Subroutines, Understanding Wide Character String Search Subroutines in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Contents | Glossary | Home | Search ]