wcsrtombs

Artikel
06/09/2015

Konvertiert eine Zeichenfolge mit Breitzeichen zu seiner Mehrbytezeichenzeichenfolgendarstellung. Eine sicherere Version dieser Funktion ist verfügbar; 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 Mehrbytezeichenzeichenfolge.
[in] wcstr
Zeigt indirekt auf den Speicherort der zu konvertierende Zeichenfolge mit Breitzeichen.
[in] count
Die Anzahl für zu konvertierenden Zeichens.
[in] mbstate
Ein Zeiger auf ein mbstate_t Konvertierungszustandsobjekt.

Rückgabewert

Gibt die Anzahl an Bytes konvertiert nicht erfolgreich, einschließlich das ungültige endgültige NULL-Zeichen-Byte (falls vorhanden); andernfalls -1 zurück, wenn ein Fehler aufgetreten ist.

Hinweise

Die wcsrtombs-Funktion konvertiert eine Zeichenfolge mit Breitzeichen und beginnt im angegebenen Konvertierungszustand, der in mbstate, im indirekten spitzen die Werte zu in wcstr, in die Adresse von mbstr enthalten ist. Die Konvertierung wird für jedes Zeichen bis fort: nachdem eine NULL-Zeichenfolge, die beendet Breitzeichen, aufgetreten ist, wenn ein nicht übereinstimmendes Zeichen festgestellt wird, oder das nächste Zeichen als der Grenzwert übersteigt, die in count enthalten war. Wenn wcsrtombs das NULL-Breitzeichen (L"\0") entweder vor trifft oder, wenn count auftritt, wird es zu einem äußerst 0 konvertiert und anhält.

Daher ist die Mehrbytezeichenzeichenfolge bei mbstr auf NULL endende nur, wenn wcsrtombs ein Breitzeichennull-zeichen während der Konvertierung gefunden wird. Wenn die Sequenzen, die von wcstr und mbstr Überlappung, das Verhalten von wcsrtombs dargestellt werden, die definiert. wcsrtombs wird durch die LC_TYPE-Kategorie des aktuellen Gebietsschemas beeinflusst.

Die wcsrtombs-Funktion unterscheidet sich von wcstombs, _wcstombs_l durch ihre Neustartfähigkeit. Der Konvertierungszustand wird in mbstate für nachfolgende Aufrufe an den gleichen oder anderen restartable Funktionen gespeichert. Ergebnisse werden undefiniert, wenn Sie die Verwendung von restartable und nonrestartable Funktionen kombiniert. Beispielsweise würde eine Anwendung wcsrlen statt wcsnlen verwenden, wenn ein nachfolgender Aufruf wcsrtombs statt wcstombs verwendet wurden.

Wenn das Argument mbstrNULL ist, gibt wcsrtombs die erforderlichen Größe in Bytes der Zielzeichenfolge zurück. Wenn mbstate NULL ist, wird der interne mbstate_t Konvertierungszustand verwendet. Wenn die Zeichensequenz wchar keine entsprechende Mehrbytezeichendarstellung hat, wird -1 zurückgegeben und errno ist auf EILSEQ festgelegt.

In C++ ist diese Funktion eine Vorlagenüberladung, die aufgerufen wird, das später, speichern Entsprechung dieser Funktion. Weitere Informationen finden Sie unter Sichere Vorlagenüberladungen.

Ausnahmen

Die Funktion wcsrtombs ist multithreadsicher, solange keine Funktion im aktuellen Thread setlocale aufruft, wenn 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" );
    }
}