wcsrtombs

Konvertieren einer Zeichenfolge mit Breitzeichen zur Mehrbytezeichen zeichenfolgendarstellung.Eine sicherere Version dieser Funktion ist verfügbar. Weitere Informationen finden Sie unter wcsrtombs_s.

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Parameter

[out] mbstr
Der Adressenplatz der resultierenden konvertierten Mehrbytezeichen zeichenkette.
[in] wcstr
Indirekt Punkte auf den Speicherort der zu konvertierenden Zeichenfolge mit Breitzeichen.
[in] count
Die Anzahl der zu konvertierenden Zeichen.
[in] mbstate
Ein Zeiger auf einen mbstate_t Konvertierung zustands Objekt.

Rückgabewert

Gibt die Anzahl der Bytes nicht erfolgreich konvertiert, einschließlich des abschließenden NULL-Zeichens Nullbyte des abschließenden NULL-Zeichens (sofern vorhanden), andernfalls -1 (null) zurück, wenn ein Fehler aufgetreten ist.

Hinweise

Die wcsrtombs-Funktion konvertiert eine Zeichenfolge mit Breitzeichen, wobei im angegebenen Zustand der Konvertierung in mbstate, durch indirekten spitzen Werte in wcstr, in die Adresse von mbstrenthalten ist.Die Konvertierung wird für jedes Zeichen auf Weiter: Breitzeichen, die nach einer Null erreicht ist, beendet, wenn ein nicht übereinstimmendes Zeichen festgestellt wird, oder das nächste Zeichen als der Grenzwert übersteigen würde, die in countenthalten war.Wenn das wcsrtombs NULL-Breitzeichen (L \ 0 ') entweder vor oder auftritt, wenn count auftritt, es zu einem 8-Bit 0 konvertiert und beendet wird.

Daher ist die Mehrbytezeichen zeichenkette unter mbstr auf NULL endende nur, wenn wcsrtombs ein Breitzeichen null-zeichen bei der Konvertierung findet.Wenn die Sequenzen, die über wcstr und mbstr Überlappung, das Verhalten von wcsrtombs dargestellt werden, nicht definiert ist.wcsrtombs wurde durch die LC_TYPE-Kategorie des aktuellen Gebietsschemas betroffen.

Die wcsrtombs-Funktion unterscheidet sich von wcstombs, _wcstombs_l durch seine Neustartfähigkeit.Der Zustand der Konvertierung in mbstate für nachfolgende Aufrufe an derselben oder zu einer anderen restartable Funktionen gespeichert.Ergebnisse werden nicht definiert, wenn die Verwendung restartable und nonrestartable Funktionen kombiniert.Beispielsweise kann eine Anwendung wcsrlen statt wcsnlenverwenden, wenn ein nachfolgender Aufruf von wcsrtombs anstelle wcstombsverwendet wurden.

Wenn das Argument mbstrNULList, gibt wcsrtombs die erforderliche Größe in Bytes der Zielzeichenfolge zurück.Wenn mbstate NULL ist, wird der interne Zustand mbstate_t Konvertierung verwendet.Wenn die Zeichensequenz wchar Mehrbytezeichen keine entsprechende Darstellung verfügt, wird -1 zurückgegeben und errno wird auf EILSEQfestgelegt.

In C++ verfügt diese Funktion keine Vorlagen Überladung, die aufruft, das neueres, speichern Entsprechung für diese Funktion.Weitere Informationen finden Sie unter Speichern Sie Vorlagen-Überladungen.

Ausnahmen

Die wcsrtombs-Funktion ist multithreadsicher, solange keine Funktion im aktuellen Thread setlocale aufgerufen, während diese Funktion ausführt und mbstate nicht NULL ist.

Beispiel

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] = 
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else 
    {
        printf( "The string was successfuly converted.\n" );
    }
}