mbstowcs
, _mbstowcs_l
Konwertuje sekwencję znaków wielobajtowych na odpowiednią sekwencję znaków szerokich. Dostępne są bezpieczniejsze wersje tych funkcji; zobacz mbstowcs_s
, _mbstowcs_s_l
.
Składnia
size_t mbstowcs(
wchar_t *wcstr,
const char *mbstr,
size_t count
);
size_t _mbstowcs_l(
wchar_t *wcstr,
const char *mbstr,
size_t count,
_locale_t locale
);
template <size_t size>
size_t mbstowcs(
wchar_t (&wcstr)[size],
const char *mbstr,
size_t count
); // C++ only
template <size_t size>
size_t _mbstowcs_l(
wchar_t (&wcstr)[size],
const char *mbstr,
size_t count,
_locale_t locale
); // C++ only
Parametry
wcstr
Adres sekwencji znaków szerokich.
mbstr
Adres sekwencji znaków wielobajtowych zakończonych o wartości null.
count
Maksymalna liczba znaków wielobajtowych do przekonwertowania.
locale
Ustawienia regionalne do użycia.
Wartość zwracana
Jeśli mbstowcs
ciąg źródłowy zostanie pomyślnie przekonwertowany, zwraca liczbę przekonwertowanych znaków wielobajtowych. wcstr
Jeśli argument to NULL
, funkcja zwraca wymagany rozmiar (w szerokich znakach) ciągu docelowego. Jeśli mbstowcs
napotka nieprawidłowy znak wielobajtowy, zwraca wartość -1. Jeśli zwracana wartość to count
, ciąg o szerokim znaku nie jest zakończony wartością null.
Ważne
Upewnij się, że wcstr
i mbstr
nie nakładają się, i że count
poprawnie odzwierciedla liczbę znaków wielobajtowych do konwersji.
Uwagi
Funkcja mbstowcs
konwertuje maksymalną liczbę count
znaków wielobajtowych wskazywanych przez mbstr
ciąg odpowiadających im znaków szerokich, które są określane przez bieżące ustawienia regionalne. Przechowuje wynikowy ciąg o szerokim znaku na adresie reprezentowanym przez wcstr
element . Wynik jest podobny do serii wywołań funkcji mbtowc
. Jeśli mbstowcs
napotka znak null pojedynczego bajtu (\0) przed lub w przypadku count
wystąpienia, konwertuje znak null na znak null (L'\0'
) i zatrzymuje się. W związku z tym ciąg znaków szeroki w wcstr
obiekcie jest zakończony wartością null tylko wtedy, gdy podczas konwersji napotkano znak null. Jeśli sekwencje wskazywane przez wcstr
i mbstr
nakładają się na siebie, zachowanie jest niezdefiniowane.
wcstr
Jeśli argument ma NULL
wartość , mbstowcs
zwraca liczbę znaków szerokich, które mogłyby wynikać z konwersji, a nie włącznie z terminatorem o wartości null. Aby zwracać prawidłową wartość, ciąg źródłowy musi być zakończony wartością null. Jeśli chcesz, aby wynikowy ciąg znaków był zakończony ciągiem o wartości null, dodaj jeden do zwracanej wartości.
mbstr
Jeśli argument ma NULL
wartość , lub count
, >INT_MAX
wywoływana jest nieprawidłowa procedura obsługi parametrów, zgodnie z opisem w temacie Weryfikacja parametrów. Jeśli wykonywanie jest dozwolone do kontynuowania, jest ustawione na EINVAL
, errno
a funkcja zwraca wartość -1.
mbstowcs
używa bieżących ustawień regionalnych dla dowolnego zachowania zależnego od ustawień regionalnych; _mbstowcs_l
jest identyczna, z tą różnicą, że używa ustawień regionalnych przekazanych w zamian. Aby uzyskać więcej informacji, zobacz Ustawienia regionalne.
W języku C++te funkcje mają przeciążenia szablonu, które wywołują nowsze, bezpieczne odpowiedniki tych funkcji. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.
Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.
Wymagania
Procedura | Wymagany nagłówek |
---|---|
mbstowcs |
<stdlib.h> |
_mbstowcs_l |
<stdlib.h> |
Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.
Przykład
// crt_mbstowcs.c
// compile with: /W3
// illustrates the behavior of the mbstowcs function
#include <stdlib.h>
#include <stdio.h>
#include <locale.h>
int main( void )
{
size_t size;
int nChar = 2; // number of characters to convert
int requiredSize;
unsigned char *pmbnull = NULL;
unsigned char *pmbhello = NULL;
char* localeInfo;
wchar_t *pwchello = L"\x3042\x3043"; // 2 Hiragana characters
wchar_t *pwc;
/* Enable the Japanese locale and codepage */
localeInfo = setlocale(LC_ALL, "Japanese_Japan.932");
printf("Locale information set to %s\n", localeInfo);
printf( "Convert to multibyte string:\n" );
requiredSize = wcstombs( NULL, pwchello, 0); // C4996
// Note: wcstombs is deprecated; consider using wcstombs_s
printf(" Required Size: %d\n", requiredSize);
/* Add one to leave room for the null terminator. */
pmbhello = (unsigned char *)malloc( requiredSize + 1);
if (! pmbhello)
{
printf("Memory allocation failure.\n");
return 1;
}
size = wcstombs( pmbhello, pwchello, requiredSize + 1); // C4996
// Note: wcstombs is deprecated; consider using wcstombs_s
if (size == (size_t) (-1))
{
printf("Couldn't convert string. Code page 932 may"
" not be available.\n");
return 1;
}
printf( " Number of bytes written to multibyte string: %u\n",
(unsigned int) size );
printf( " Hex values of the" );
printf( " multibyte characters: %#.2x %#.2x %#.2x %#.2x\n",
pmbhello[0], pmbhello[1], pmbhello[2], pmbhello[3] );
printf( " Codepage 932 uses 0x81 to 0x9f as lead bytes.\n\n");
printf( "Convert back to wide-character string:\n" );
/* Assume we don't know the length of the multibyte string.
Get the required size in characters, and allocate enough space. */
requiredSize = mbstowcs(NULL, pmbhello, 0); // C4996
/* Add one to leave room for the null terminator */
pwc = (wchar_t *)malloc( (requiredSize + 1) * sizeof( wchar_t ));
if (! pwc)
{
printf("Memory allocation failure.\n");
return 1;
}
size = mbstowcs( pwc, pmbhello, requiredSize + 1); // C4996
if (size == (size_t) (-1))
{
printf("Couldn't convert string--invalid multibyte character.\n");
}
printf( " Characters converted: %u\n", (unsigned int)size );
printf( " Hex value of first 2" );
printf( " wide characters: %#.4x %#.4x\n\n", pwc[0], pwc[1] );
free(pwc);
free(pmbhello);
}
Locale information set to Japanese_Japan.932
Convert to multibyte string:
Required Size: 4
Number of bytes written to multibyte string: 4
Hex values of the multibyte characters: 0x82 0xa0 0x82 0xa1
Codepage 932 uses 0x81 to 0x9f as lead bytes.
Convert back to wide-character string:
Characters converted: 2
Hex value of first 2 wide characters: 0x3042 0x3043
Zobacz też
Konwersja danych
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych
_mbclen
, , mblen
_mblen_l
mbtowc
, _mbtowc_l
wcstombs
, _wcstombs_l
wctomb
, _wctomb_l
MultiByteToWideChar