Namespaces
Variants

    mbstowcs, mbstowcs_s

    Von de.cppreference.net
     
    C
     
    Zeichenkettenbibliothek
     
    Nullterminierte Multibyte-Zeichenketten
     
    Definiert in Header <stdlib.h> 
    size_t mbstowcs( wchar_t* dst, const char* src, size_t len)
    		(1) (bis C99) 
    size_t mbstowcs( wchar_t* restrict dst, const char* restrict src, size_t len)
    		(seit C99) 
    errno_t mbstowcs_s(size_t* restrict retval, wchar_t* restrict dst,
                  rsize_t dstsz, const char* restrict src, rsize_t len);
    		(2) (seit C11)
    1) Konvertiert eine Multibyte-Zeichenkette aus dem Feld, auf dessen erstes Element src zeigt, in ihre Weitzeichendarstellung. Die konvertierten Zeichen werden in den aufeinanderfolgenden Elementen des Feldes gespeichert, auf das dst zeigt. Es werden maximal len Weitzeichen in das Zielfeld geschrieben.
    Jedes Zeichen wird wie durch einen Aufruf von mbtowc konvertiert, mit der Ausnahme, dass der mbtowc-Konvertierungszustand nicht beeinflusst wird. Die Konvertierung stoppt, wenn:
    • Das Multibyte-Nullzeichen konvertiert und gespeichert wurde.
    • Ein ungültiges (in der aktuellen C-Locale) Multibyte-Zeichen gefunden wurde.
    • Das nächste zu speichernde Weitzeichen len überschreiten würde.
    Wenn src und dst überlappen, ist das Verhalten undefiniert
    2) Wie (1), mit dem Unterschied, dass
    • die Konvertierung wie durch mbrtowc erfolgt, nicht durch mbtowc
    • die Funktion ihr Ergebnis als Ausgabeparameter retval
    • zurückgibtwenn kein Nullzeichen in dst geschrieben wurde, nachdem len Weitzeichen geschrieben wurden, dann wird L'\0' in dst[len] gespeichert, also insgesamt len+1 Weitzeichen geschrieben
    • wenn dst ein Nullzeiger ist, wird die Anzahl der Weitzeichen, die erzeugt worden wären, in *retval
    • gespeichertdie Funktion überschreibt das Zielfeld vom abschließenden Nullzeichen bis dstsz
    • Wenn src und dst überlappen, ist das Verhalten unspezifiziert.
    • die folgenden Fehler werden zur Laufzeit erkannt und rufen die aktuell installierte Einschränkungshandler-Funktion auf:
    • retval oder src ist ein Nullzeiger
    • dstsz oder len ist größer als RSIZE_MAX / sizeof(wchar_t) (außer wenn dst null ist)
    • dstsz ist nicht Null (außer wenn dst null ist)
    • Es gibt kein Nullzeichen in den ersten dstsz Multibyte-Zeichen im src-Feld und len ist größer als dstsz (außer wenn dst null ist)
    Wie bei allen geprüften Funktionen ist mbstowcs_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert ist und der Benutzer __STDC_WANT_LIB_EXT1__ als Integer-Konstante 1 vor dem Einbinden von <stdlib.h> definiert.

    Anmerkungen

    In den meisten Implementierungen aktualisiert mbstowcs ein globales statisches Objekt vom Typ mbstate_t, während es die Zeichenkette verarbeitet, und kann nicht gleichzeitig von zwei Threads aufgerufen werden. In solchen Fällen sollte mbsrtowcs verwendet werden.

    POSIX spezifiziert eine verbreitete Erweiterung: Wenn dst ein Nullzeiger ist, gibt diese Funktion die Anzahl der Weitzeichen zurück, die in dst geschrieben worden wären, wenn konvertiert. Ähnliches Verhalten ist Standard für mbstowcs_s und für mbsrtowcs.

    Parameter

    dst - Zeiger auf das Weitzeichenfeld, in dem die Weitzeichenkette gespeichert wird
    src - Zeiger auf das erste Element einer nullterminierten Multibyte-Zeichenkette, die konvertiert werden soll
    len - Anzahl der im Feld, auf das dst zeigt, verfügbaren Weitzeichen
    dstsz - maximale Anzahl der Weitzeichen, die geschrieben werden (Größe des dst-Feldes)
    retval - Zeiger auf ein size_t-Objekt, in dem das Ergebnis gespeichert wird

    Rückgabewert

    1) Bei Erfolg wird die Anzahl der Weitzeichen (ohne das abschließende L'\0') zurückgegeben, die in das Zielfeld geschrieben wurden. Bei Konvertierungsfehler (falls ein ungültiges Multibyte-Zeichen gefunden wurde) wird (size_t)-1 zurückgegeben.
    2) Null bei Erfolg (in diesem Fall wird die Anzahl der Weitzeichen ohne abschließende Null, die in dst geschrieben wurden oder geschrieben worden wären, in *retval gespeichert), bei Fehler ungleich Null. Im Falle einer Laufzeit-Einschränkungsverletzung wird (size_t)-1 in *retval gespeichert (außer wenn retval null ist) und dst[0] auf L'\0' gesetzt (außer wenn dst null ist oder dstmax Null oder größer als RSIZE_MAX ist)

    Beispiel

    Diesen Code ausführen
    #include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"
    wchar_t wstr[5];
    mbstowcs(wstr, mbstr, 5);
    wprintf(L"MB string: %s\n", mbstr);
    wprintf(L"Wide string: %ls\n", wstr);
}

    Ausgabe: 

    MB string: zß水🍌
Wide string: zß水🍌

    Referenzen

    • C23-Standard (ISO/IEC 9899:2024):
    • 7.22.8.1 Die Funktion mbstowcs (S. TBD)
    • K.3.6.5.1 Die Funktion mbstowcs_s (S. TBD)
    • C17-Standard (ISO/IEC 9899:2018):
    • 7.22.8.1 Die Funktion mbstowcs (S. TBD)
    • K.3.6.5.1 Die Funktion mbstowcs_s (S. TBD)
    • C11-Standard (ISO/IEC 9899:2011):
    • 7.22.8.1 Die Funktion mbstowcs (S. 359)
    • K.3.6.5.1 Die Funktion mbstowcs_s (S. 611-612)
    • C99-Standard (ISO/IEC 9899:1999):
    • 7.20.8.1 Die Funktion mbstowcs (S. 323)
    • C89/C90-Standard (ISO/IEC 9899:1990):
    • 4.10.8.1 Die Funktion mbstowcs

    Siehe auch

    (C95)(C11)
    		 konvertiert eine schmale Multibyte-Zeichenkette in eine Weitzeichenkette, unter Berücksichtigung des Zustands
    (Funktion)
    (C11)
    		 konvertiert eine Weitzeichenkette in eine schmale Multibyte-Zeichenkette
    (Funktion)
    C++-Dokumentation für mbstowcs