Compaq C
Compaq C
Run-Time Library Reference Manual for
OpenVMS Systems
wcstombs
Converts a sequence of wide-character codes to a sequence of multibyte
characters.
Format
#include <stdlib.h>
size_t wcstombs (char *s, const wchar_t *pwcs, size_t
n);
Arguments
s
A pointer to the array containing the resulting multibyte characters.
pwcs
A pointer to the array containing the sequence of wide-character codes.
n
The maximum number of bytes to be stored in the array pointed to by
s.
Description
This function converts a sequence of codes corresponding to multibyte
characters from the array pointed to by pwcs to a sequence of
multibyte characters that are stored into the array pointed to by
s, up to a maximum of n bytes. The value returned is
equal to the number of characters converted or a --1 if an error
occurred.
This function is affected by the LC_CTYPE category of the program's
current locale. See also
wctomb
in this section.
If s is NULL, this function call is a counting operation and
n is ignored.
Return Values
|
x
|
The number of bytes stored in
s, not including the null terminating byte. If
s is NULL,
wcstombs returns the number of bytes required for the
multibyte character array.
|
|
(
size_t
) --1
|
Indicates an error occurred. The function sets
errno
to EILSEQ -- invalid character sequence, or a wide-character code does
not correspond to a valid character.
|
wcstoul
Converts the initial portion of the wide-character string pointed to by
nptr to an
unsigned long
integer.
Format
#include <wchar.h>
unsigned long int wcstoul (const wchar_t *nptr, wchar_t
**endptr, int base);
Function Variants This function also has variants named
_wcstoul32
and
_wcstoul64
for use with 32-bit and 64-bit pointer sizes, respectively. See
Section 1.10 for more information on using pointer-size-specific
functions.
Arguments
nptr
A pointer to the wide-character string to be converted to an
unsigned long
.
endptr
The address of an object where the function can store the address of
the first unrecognized character encountered in the conversion process
(The character that follows the last character in the string being
converted). If endptr is a NULL pointer, the address of the
first unrecognized character is not retained.
base
The value, 2 through 36, to use as the base for the conversion.
If base is 16, leading zeros after the optional sign are
ignored, and 0x or 0X is ignored.
If base is 0, the sequence of characters is interpreted by the
same rules used to interpret an integer constant: after the optional
sign, a leading 0 indicates octal conversion, a leading 0x or 0X
indicates hexadecimal conversion, and any other combination of leading
characters indicates decimal conversion.
Description
This function recognizes strings in various formats, depending on the
value of the base. It ignores any leading white-space characters (as
defined by the
iswspace
function) in the string. It recognizes an optional plus or minus sign,
then a sequence of digits or letters that may represent an integer
constant according to the value of the base. The first unrecognized
wide character ends the conversion.
Return Values
|
x
|
The converted value.
|
|
0
|
Indicates that the string starts with an unrecognized wide character or
that the value for
base is invalid. If the string starts with an unrecognized
wide character, *
endptr is set to
nptr. The function sets
errno
to EINVAL.
|
|
ULONG_MAX
|
Indicates that the converted value would cause an overflow. The
function sets
errno
to ERANGE.
|
Example
#include <stdlib.h>
#include <stdio.h>
#include <wchar.h>
#include <errno.h>
#include <limits.h>
/* This test calls wcstoul() to convert a string to an */
/* unsigned long integer. wcstoul outputs the resulting */
/* integer and any characters that could not be converted. */
#define MAX_STRING 128
main()
{
int base = 10,
errno;
char *input_string = "1234.56";
wchar_t string_array[MAX_STRING],
*ptr;
size_t size;
unsigned long int val;
printf("base = [%d]\n", base);
printf("String to convert = %s\n", input_string);
if ((size = mbstowcs(string_array, input_string, MAX_STRING)) ==
(size_t)-1) {
perror("mbstowcs");
exit(EXIT_FAILURE);
}
printf("wchar_t string is = [%S]\n", string_array);
errno = 0;
val = wcstoul(string_array, &ptr, base);
if (errno == 0) {
printf("returned unsigned long int from wcstoul = [%u]\n", val);
printf("wide char terminating scan(ptr) = [%S]\n\n", ptr);
}
if (errno == ERANGE) {
perror("error value is :");
printf("ULONG_MAX = [%u]\n", ULONG_MAX);
printf("wcstoul failed, val = [%d]\n\n", val);
}
}
|
Running the example program produces the following result:
base = [10]
String to convert = 1234.56
wchar_t string is = [1234.56]
returned unsigned long int from wcstoul = [1234]
wide char terminating scan(ptr) = [.56]
|
wcswcs
Locates the first occurrence in the string pointed to by wstr1
of the sequence of wide characters in the string pointed to by
wstr2.
Format
#include <wchar.h>
wchar_t *wcswcs (const wchar_t *wstr1, const wchar_t
*wstr2);
Function Variants This function also has variants named
_wcswcs32
and
_wcswcs64
for use with 32-bit and 64-bit pointer sizes, respectively. See
Section 1.10 for more information on using pointer-size-specific
functions.
Arguments
wstr1, wstr2
Pointers to null-terminated wide-character strings.
Return Values
|
Pointer
|
A pointer to the located wide-character string.
|
|
NULL
|
Indicates that the wide-character string was not found.
|
Example
#include <stdlib.h>
#include <stdio.h>
#include <wchar.h>
/* This test uses wcswcs() to find the occurrence of each */
/* sub wide-character string, string1 and string2, within */
/* the main wide-character string, lookin. */
#define BUF_SIZE 50
main()
{
static char lookin[] = "that this is a test was at the end";
char string1[] = "this",
string2[] = "the end";
wchar_t buffer[BUF_SIZE],
input_buffer[BUF_SIZE];
/* Convert lookin to wide-character format. */
/* Buffer and print it out. */
if (mbstowcs(buffer, lookin, BUF_SIZE) == (size_t)-1) {
perror("mbstowcs");
exit(EXIT_FAILURE);
}
printf("Buffer to look in: %S\n", buffer);
/* Convert string1 to wide-character format and use */
/* wcswcs() to locate it within buffer */
if (mbstowcs(input_buffer, string1, BUF_SIZE) == (size_t)-1) {
perror("mbstowcs");
exit(EXIT_FAILURE);
}
printf("this: %S\n", wcswcs(buffer, input_buffer));
/* Convert string2 to wide-character format and use */
/* wcswcs() to locate it within buffer */
if (mbstowcs(input_buffer, string2, BUF_SIZE) == (size_t)-1) {
perror("mbstowcs");
exit(EXIT_FAILURE);
}
printf("the end: %S\n", wcswcs(buffer, input_buffer));
exit(1);
}
|
Running this example produces the following results:
Buffer to look in: that this is a test was at the end
this: this is a test was at the end
the end: the end
|
wcswidth
Determines the number of printing positions on a display device that
are required for a wide-character string.
Format
#include <wchar.h>
int wcswidth (const wchar_t *pwcs, size_t n);
Arguments
pwcs
A pointer to a wide-character string.
n
The maximum number of characters in the string.
Description
This function returns the number of printing positions required to
display the first n characters of the string pointed to by
pwcs. If there are less than n wide characters in the
string, the function returns the number of positions required for the
whole string.
Return Values
|
x
|
The number of printing positions required.
|
|
0
|
If
pwcs is a null character.
|
|
--1
|
Indicates that one (or more) of the wide characters in the string
pointed to by
pwcs is not a printable character.
|
wcsxfrm
Changes a wide-character string such that the changed string can be
passed to the
wcscmp
function and produce the same result as passing the unchanged string to
the
wcscoll
function.
Format
#include <wchar.h>
size_t wcsxfrm (wchar_t *ws1, const wchar_t *ws2,
size_t maxchar);
Arguments
ws1, ws2
Pointers to wide-character strings.
maxchar
The maximum number of wide-characters, including the null
wide-character terminator, allowed to be stored in s1.
Description
This function transforms the string pointed to by ws2 and
stores the resulting string in the array pointed to by ws1. No
more than maxchar wide characters, including the null wide
terminator, are placed into the array pointed to by ws1.
If the value of maxchar is less than the required size to
store the transformed string (including the terminating null), the
contents of the array pointed to by ws1 is indeterminate. In
such a case, the function returns the size of the transformed string.
If maxchar is zero, then, ws1 is allowed to be a NULL
pointer, and the function returns the required size of the ws1
array before making the transformation.
The wide-character string comparison functions,
wcscoll
and
wcscmp
, can produce different results given the same two wide-character
strings to compare. This is because
wcscmp
does a straightforward comparison of the code point values of the
characters in the strings, whereas
wcscoll
uses the locale information to do the comparison. Depending on the
locale, the
wcscoll
comparison can be a multi-pass operation, which is slower than
wcscmp
.
The
wcsxfrm
function transforms wide character strings in such a way that if you
pass two transformed strings to the
wcscmp
function, the result is the same as passing the two original strings to
the
wcscoll
function. The
wcsxfrm
function is useful in applications that need to do a large number of
comparisons on the same wide-character strings using
wcscoll
. In this case, it may be more efficient (depending on the locale) to
transform the strings once using
wcsxfrm
and then use the
wcscmp
function to do comparisons.
Return Values
|
x
|
Length of the resulting string pointed to by
ws1, not including the terminating null character.
|
|
(
size_t
) --1
|
Indicates an error occurred. The function sets
errno
to EINVAL -- The string pointed to by
ws2 contains characters outside the domain of the collating
sequence.
|
Example
#include <wchar.h>
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
/* This program verifies that two transformed strings, */
/* when passed through wcsxfrm and then compared, provide */
/* the same result as if passed through wcscoll without */
/* any transformation. */
#define BUFF_SIZE 20
main()
{
wchar_t w_string1[BUFF_SIZE];
wchar_t w_string2[BUFF_SIZE];
wchar_t w_string3[BUFF_SIZE];
wchar_t w_string4[BUFF_SIZE];
int errno;
int coll_result;
int wcscmp_result;
size_t wcsxfrm_result1;
size_t wcsxfrm_result2;
/* setlocale to French locale */
if (setlocale(LC_ALL, "fr_FR.ISO8859-1") == NULL) {
perror("setlocale");
exit(EXIT_FAILURE);
}
/* Convert each of the strings into wide-character format. */
if (mbstowcs(w_string1, "<a`>bcd", BUFF_SIZE) == (size_t)-1) {
perror("mbstowcs");
exit(EXIT_FAILURE);
}
if (mbstowcs(w_string2, "abcz", BUFF_SIZE) == (size_t)-1) {
perror("mbstowcs");
exit(EXIT_FAILURE);
}
/* Collate string 1 and string 2 and store the result. */
errno = 0;
coll_result = wcscoll(w_string1, w_string2);
if (errno) {
perror("wcscoll");
exit(EXIT_FAILURE);
}
else {
/* Transform the strings (using wcsxfrm) into */
/* w_string3 and w_string4. */
wcsxfrm_result1 = wcsxfrm(w_string3, w_string1, BUFF_SIZE);
if (wcsxfrm_result1 == ((size_t) - 1))
perror("wcsxfrm");
else if (wcsxfrm_result1 > BUFF_SIZE) {
perror("\n** String is too long **\n");
exit(EXIT_FAILURE);
}
else {
wcsxfrm_result2 = wcsxfrm(w_string4, w_string2, BUFF_SIZE);
if (wcsxfrm_result2 == ((size_t) - 1)) {
perror("wcsxfrm");
exit(EXIT_FAILURE);
}
else if (wcsxfrm_result2 > BUFF_SIZE) {
perror("\n** String is too long **\n");
exit(EXIT_FAILURE);
}
/* Compare the two transformed strings and verify that */
/* the result is the same as the result from wcscoll on */
/* the original strings. */
else {
wcscmp_result = wcscmp(w_string3, w_string4);
if (wcscmp_result == 0 && (coll_result == 0)) {
printf("\nReturn value from wcscoll() and return value"
" from wcscmp() are both zero.");
printf("\nThe program was successful\n\n");
}
else if ((wcscmp_result < 0) && (coll_result < 0)) {
printf("\nReturn value from wcscoll() and return value"
" from wcscmp() are less than zero.");
printf("\nThe program was successful\n\n");
}
else if ((wcscmp_result > 0) && (coll_result > 0)) {
printf("\nReturn value from wcscoll() and return value"
" from wcscmp() are greater than zero.");
printf("\nThe program was successful\n\n");
}
else {
printf("** Error **\n");
printf("\nReturn values are not of the same type");
}
}
}
}
}
|
Running the example program produces the following result:
Return value from wcscoll() and return value
from wcscmp() are less than zero.
The program was successful
|
wctob
Determines if a wide character corresponds to a single-byte multibyte
character and returns its multibyte character representation.
Format
#include <stdio.h>
#include <wchar.h>
int wctob (wint_t c);
Arguments
c
The wide character to be converted to a single-byte multibyte character.
Description
This function determines whether the specified wide character
corresponds to a single-byte multibyte character when in the initial
shift state and, if so, returns its multibyte character representation.
Return Values
|
x
|
The single-byte representation of the wide character specified.
|
|
EOF
|
Indicates an error. The wide character specified does not correspond to
a single-byte multibyte character.
|
wctomb
Converts a wide character to its multibyte character representation.
Format
#include <stdlib.h>
int wctomb (char *s, wchar_t wchar);
Arguments
s
A pointer to the resulting multibyte character.
wchar
The code for the wide character.
Description
This function converts the wide character specified by wchar
to its multibyte character representation. If s is NULL, then
0 is returned. Otherwise, the number of bytes comprising the multibyte
character is returned. At most, MB_CUR_MAX bytes are stored in the
array object pointed to by s.
This function is affected by the LC_CTYPE category of the program's
current locale.
Return Values
|
x
|
The number of bytes comprising the multibyte character corresponding to
wchar.
|
|
0
|
If
s is NULL.
|
|
--1
|
If
wchar is not a valid character.
|
wctrans
Returns the description of a mapping, corresponding to specified
property, that can later be used in a call to
towctrans
.
Format
#include <wctype.h>
wctrans_t wctrans (const char *property);
Arguments
property
The name of the mapping. The following property names are defined for
all locales:
Additional property names may also be defined in the LC_CTYPE category
of the current locale.
Description
This function constructs a value with type
wctrans_t
that describes a mapping between wide characters identified by the
property argument.
See also
towctrans
in this section.
Return Values
|
nonzero
|
According to the LC_CTYPE category of the current program locale, the
string specified as a property argument is the name of an existing
character mapping. The value returned can be used in a call to the
towctrans
function.
|
|
0
|
Indicates an error. The property argument does not identify a character
mapping in the current program's locale.
|
wctype
Used for defining a character class. The value returned by this
function is used in calls to the
iswctype
function.
Format
#include <wctype.h> (ISO C)
#include <wchar.h> (XPG4)
wctype_t wctype (const char *char_class);
Arguments
char_class
A pointer to a valid character class name.
Description
This function converts a valid character class defined for the current
locale to an object of type
wctype_t
. The following character class names are defined for all locales:
alnum cntrl lower space
alpha digit print upper
blank graph punct xdigit
|
Additional character class names may also be defined in the LC_CTYPE
category of the current locale.
See also
iswctype
in this section.
Return Values
|
x
|
An object of type
wctype_t
that can be used in calls to the
iswctype
function.
|
|
0
|
If the character class name is not valid for the current locale.
|
Example
#include <locale.h>
#include <wchar.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>
/* This test will set up a number of character class using wctype() */
/* and then verify whether calls to iswctype() using these classes */
/* produce the same results as calls to the is**** routines. */
main()
{
wchar_t w_char;
wctype_t ret_val;
char *character = "A";
/* Convert character to wide character format - w_char */
if (mbtowc(&w_char, character, 1) == -1) {
perror("mbtowc");
exit(EXIT_FAILURE);
}
/* Check if results from iswalnum() matches check on */
/* alnum character class */
if ((iswalnum((wint_t) w_char)) &&
(iswctype((wint_t) w_char, wctype("alnum"))))
printf("[%C] is a member of the character class alnum\n", w_char);
else
printf("[%C] is not a member of the character class alnum\n", w_char);
/* Check if results from iswalpha() matches check on */
/* alpha character class */
if ((iswalpha((wint_t) w_char)) &&
(iswctype((wint_t) w_char, wctype("alpha"))))
printf("[%C] is a member of the character class alpha\n", w_char);
else
printf("[%C] is not a member of the character class alpha\n", w_char);
/* Check if results from iswcntrl() matches check on */
/* cntrl character class */
if ((iswcntrl((wint_t) w_char)) &&
(iswctype((wint_t) w_char, wctype("cntrl"))))
printf("[%C] is a member of the character class cntrl\n", w_char);
else
printf("[%C] is not a member of the character class cntrl\n", w_char);
/* Check if results from iswdigit() matches check on */
/* digit character class */
if ((iswdigit((wint_t) w_char)) &&
(iswctype((wint_t) w_char, wctype("digit"))))
printf("[%C] is a member of the character class digit\n", w_char);
else
printf("[%C] is not a member of the character class digit\n", w_char);
/* Check if results from iswgraph() matches check on */
/* graph character class */
if ((iswgraph((wint_t) w_char)) &&
(iswctype((wint_t) w_char, wctype("graph"))))
printf("[%C] is a member of the character class graph\n", w_char);
else
printf("[%C] is not a member of the character class graph\n", w_char);
/* Check if results from iswlower() matches check on */
/* lower character class */
if ((iswlower((wint_t) w_char)) &&
(iswctype((wint_t) w_char, wctype("lower"))))
printf("[%C] is a member of the character class lower\n", w_char);
else
printf("[%C] is not a member of the character class lower\n", w_char);
/* Check if results from iswprint() matches check on */
/* print character class */
if ((iswprint((wint_t) w_char)) &&
(iswctype((wint_t) w_char, wctype("print"))))
printf("[%C] is a member of the character class print\n", w_char);
else
printf("[%C] is not a member of the character class print\n", w_char);
/* Check if results from iswpunct() matches check on */
/* punct character class */
if ((iswpunct((wint_t) w_char)) &&
(iswctype((wint_t) w_char, wctype("punct"))))
printf("[%C] is a member of the character class punct\n", w_char);
else
printf("[%C] is not a member of the character class punct\n", w_char);
/* Check if results from iswspace() matches check on */
/* space character class */
if ((iswspace((wint_t) w_char)) &&
(iswctype((wint_t) w_char, wctype("space"))))
printf("[%C] is a member of the character class space\n", w_char);
else
printf("[%C] is not a member of the character class space\n", w_char);
/* Check if results from iswupper() matches check on */
/* upper character class */
if ((iswupper((wint_t) w_char)) &&
(iswctype((wint_t) w_char, wctype("upper"))))
printf("[%C] is a member of the character class upper\n", w_char);
else
printf("[%C] is not a member of the character class upper\n", w_char);
/* Check if results from iswxdigit() matches check on */
/* xdigit character class */
if ((iswxdigit((wint_t) w_char)) &&
(iswctype((wint_t) w_char, wctype("xdigit"))))
printf("[%C] is a member of the character class xdigit\n", w_char);
else
printf("[%C] is not a member of the character class xdigit\n", w_char);
}
|
|
