wcsrtombs

Konvertieren von Breitzeichen in die Multibyte-Zeichenfolgendarstellung. Eine sicherere Version dieser Funktion ist verfügbar; siehe wcsrtombs_s.

Syntax

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

mbstr
Der Adressspeicherort der resultierenden konvertierten Multibyte-Zeichenfolge.

wcstr
Indirekter Zeiger auf den Speicherort der Breitzeichenfolge, die konvertiert werden soll.

count
Die Anzahl der zu konvertierenden Zeichen.

mbstate
Ein Zeiger auf ein mbstate_t-Konvertierungszustandsobjekt.

Rückgabewert

Gibt die Anzahl der erfolgreich konvertierten Bytes zurück, wobei das abschließende NULL-Byte (falls vorhanden) nicht eingeschlossen ist. Andernfalls wird bei einem Fehler -1 zurückgegeben.

Hinweise

Die Funktion wcsrtombs konvertiert eine Zeichenfolge aus Breitzeichen, beginnend beim angegebenen Konvertierungsstatus, der in mbstate enthalten ist, von den Werten, auf die in wcstr indirekt gezeigt wird, in die Adresse von mbstr. Die Konvertierung wird für jedes Zeichen fortgeführt, bis ein abschließendes NULL-Breitzeichen gefunden wird, ein nicht übereinstimmendes Zeichen gefunden wird oder das nächste Zeichen den in count enthaltenen Grenzwert übersteigen würde. Wenn wcsrtombs das Breitzeichen NULL (L'\0') erkennt, entweder vor oder bei count, wird es in ein 8-Bit-0-Zeichen konvertiert und beendet.

Folglich endet die Multibyte-Zeichenfolge bei mbstr nur dann auf NULL, wenn wcsrtombs während der Konvertierung ein Breitzeichen NULL findet. Wenn die Sequenzen, auf die von wcstr und mbstr verwiesen wird, überlappen, ist das Verhalten von wcsrtombs nicht definiert. wcsrtombs wird von der LC_TYPE-Kategorie des aktuellen Gebietsschemas beeinflusst.

Die wcsrtombs Funktion unterscheidet sich von wcstombsder _wcstombs_l Neustartbarkeit. Der Konvertierungszustand wird für nachfolgende Aufrufe der gleichen oder anderer Funktionen, die neu gestartet werden können, in mbstate gespeichert. Wenn sowohl Funktionen, die neu gestartet werden können, als auch Funktionen, die nicht neu gestartet werden könnnen, verwendet werden, sind die Ergebnisse undefiniert. Beispiel: Eine Anwendung würde wcsrlen anstelle von wcsnlen verwenden, wenn ein nachfolgender Aufruf von wcsrtombs anstelle von wcstombs verwendet würde.

Wenn das mbstr-Argument NULL ist, gibt wcsrtombs die erforderliche Größe der Zielzeichenfolge in Bytes zurück. Wenn mbstate NULL ist, wird der interne Konvertierungsstatus mbstate_t verwendet. Wenn die Zeichensequenz wchar keine entsprechende Multibyte-Zeichendarstellung enthält, wird ein -1 zurückgegeben, und der errno Wert wird auf EILSEQ. festgelegt.

In C++ hat diese Funktion eine Vorlagenüberladung, mit der die neuere, sichere Entsprechung dieser Funktion aufgerufen wird. Weitere Informationen finden Sie unter Secure Template Overloads.

Standardmäßig gilt der globale Zustand dieser Funktion für die Anwendung. Wie Sie dieses Verhalten ändern, erfahren Sie unter Globaler Status in der CRT.

Ausnahmen

Die wcsrtombs Funktion ist multithreadsicher, solange keine Funktion im aktuellen Thread aufruft setlocale , während diese Funktion ausgeführt wird und die mbstate Null nicht 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" );
    }
}

The string was successfuly converted.

Anforderungen

Siehe auch

Datenkonvertierung
Gebietsschema
Interpretation von Multibytezeichensequenzen
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit