Chapter Contents |
Previous |
Next |
mbstowcs |
Portability: | ISO/ANSI C conforming |
SYNOPSIS | |
DESCRIPTION | |
RETURN VALUE | |
CAUTIONS | |
EXAMPLE |
SYNOPSIS |
#include <stdlib.h> size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);
DESCRIPTION |
mbstowcs
converts a sequence of multibyte characters (mixed DBCS sequence)
pointed to by
s
into a
sequence of corresponding wide characters (pure DBCS sequence) and stores
the output sequence in the array pointed to by
pwcs
. The multibyte character sequence is assumed to begin in the initial
shift state.
n
specifies the maximum number of wide characters to be stored.
RETURN VALUE |
If the multibyte character sequence is
valid,
mbstowcs
returns
the number of elements of
pwcs
that were modified, excluding the terminating
0
code, if any. If the sequence of multibyte
characters is invalid,
mbstowcs
returns
-1
.
CAUTIONS |
No multibyte characters that follow a
null character are examined or converted. If the sequence you want to convert
contains such a value in the middle, you should use a loop that calls
mbtowc
.
If copying takes place between objects that overlap,
the behavior of
mbstowcs
is undefined.
A diagnostic is not issued if
mbstowcs
encounters invalid data; a return value
of
-1
is the only indication
of an error.
EXAMPLE |
This example replaces all occurences of
a given character in a mixed DBCS string. The string is assumed to have a
maximum length of 81 characters. This example uses
mbstowcs
and
wcstomb
.
#include <locale.h> #include <limits.h> #include <stdlib.h> #include <stdio.h> #define MAX_CHARACTERS 81 /* "old_string" is the input MIXED DBCS string. "new_string" */ /* is the output MIXED DBCS string. "old_wchar" is the */ /* multibyte character to be replaced. "new_wchar" is the */ /* multibyte character to replace with. */ void mbsrepl(char *old_string, char *new_string, wchar_t old_wchar, wchar_t new_wchar) { wchar_t work[MAX_CHARACTERS]; int nchars; int i; /* Inform library that we will be accepting a DBCS string.*/ /* That is, SO and SI are not regular control characters: */ /* they indicate a change in shift state. */ setlocale(LC_ALL, "dbcs"); nchars = mbstowcs(work, old_string, MAX_CHARACTERS); if (nchars < 0) { fputs("Invalid DBCS string.\n", stderr); fclose(stderr); abort(); } /* Perform the actual substitution. */ for (i = 0; i < nchars; i++) if (work[i] == old_wchar) work[i] = new_wchar; /* Convert back to MIXED format. */ nchars = wcstombs(new_string, work, MAX_CHARACTERS); /* See if the replacement caused the string to overflow. */ if (nchars == MAX_CHARACTERS) { fputs("Replacement string too large.\n", stderr); abort(); fclose(stderr); } }
Chapter Contents |
Previous |
Next |
Top of Page |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.