Namespaces
Variants

mbstowcs, mbstowcs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Definiert in Header <stdlib.h>
(1)
size_t mbstowcs ( wchar_t * dst, const char * src, size_t len )
(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 Array, dessen erstes Element von src gezeigt wird, in ihre Breitzeichen-Darstellung. Konvertierte Zeichen werden in den aufeinanderfolgenden Elementen des Arrays gespeichert, auf das von dst gezeigt wird. Nicht mehr als len Breitzeichen werden in das Zielarray geschrieben.
Jedes Zeichen wird wie durch einen Aufruf von mbtowc konvertiert, außer dass der mbtowc-Konvertierungszustand unverändert bleibt. Die Konvertierung stoppt, wenn:
* Das Multibyte-Nullzeichen wurde konvertiert und gespeichert.
* Es wurde ein ungültiges (im aktuellen C-Locale) Multibyte-Zeichen angetroffen.
* Das nächste zu speichernde Breitzeichen würde len überschreiten.
Wenn src und dst sich überlappen, ist das Verhalten undefiniert
2) Gleich wie (1) , außer dass
* Konvertierung erfolgt wie durch mbrtowc , nicht durch mbtowc
* die Funktion gibt ihr Ergebnis als Out-Parameter zurück retval
* falls kein Nullzeichen nach dem Schreiben von dst nach len Breitzeichen geschrieben wurde, dann wird L ' \0 ' in dst[len] gespeichert, was bedeutet, dass insgesamt len+1 Breitzeichen geschrieben werden
* wenn dst ein Nullzeiger ist, wird die Anzahl der zu erzeugenden Breitzeichen in * retval gespeichert
* die Funktion überschreibt das Zielarray ab dem abschließenden Nullzeichen bis dstsz
* Wenn sich src und dst überlappen, ist das Verhalten nicht spezifiziert.
* Die folgenden Fehler werden zur Laufzeit erkannt und rufen den aktuell installierten Constraint-Handler auf:
  • retval oder src ist ein Nullzeiger
  • dstsz oder len ist größer als RSIZE_MAX/sizeof(wchar_t) (sofern dst nicht null ist)
  • dstsz ist nicht null (sofern dst nicht null ist)
  • Es gibt kein Nullzeichen in den ersten dstsz Multibyte-Zeichen im src -Array und len ist größer als dstsz (sofern dst nicht null ist)
Wie bei allen grenzprüfenden Funktionen ist mbstowcs_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf den Integer-Konstantenwert 1 setzt, bevor <stdlib.h> eingebunden wird.

Inhaltsverzeichnis

Hinweise

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

POSIX spezifiziert eine gemeinsame Erweiterung: falls dst ein Nullzeiger ist, gibt diese Funktion die Anzahl der Breitzeichen zurück, die in dst geschrieben würden, falls konvertiert. Ein ähnliches Verhalten ist standardmäßig für mbstowcs_s und für mbsrtowcs vorgesehen.

Parameter

dst - Zeiger auf das Wide-Character-Array, in dem die Wide-Zeichenkette gespeichert wird
src - Zeiger auf das erste Element einer nullterminierten Multibyte-Zeichenkette zur Konvertierung
len - Anzahl der im Array verfügbaren Wide Characters (auf das dst zeigt)
dstsz - maximale Anzahl der zu schreibenden Wide Characters (Größe des dst Arrays)
retval - Zeiger auf ein size_t-Objekt, in dem das Ergebnis gespeichert wird

Rückgabewert

1) Bei Erfolg gibt die Anzahl der Breitzeichen zurück, ausgenommen des abschließenden L ' \0 ' , die in das Zielarray geschrieben wurden. Bei Konvertierungsfehler (falls ein ungültiges Multibyte-Zeichen angetroffen wurde), gibt ( size_t ) - 1 zurück.
2) Null bei Erfolg (wobei die Anzahl der Breitzeichen ohne abschließende Null, die in dst geschrieben wurden oder geschrieben worden wären, in * retval gespeichert wird), ungleich Null bei Fehler. Im Falle einer Runtime Constraint Violation wird ( size_t ) - 1 in * retval gespeichert (sofern retval nicht null ist) und dst [ 0 ] auf L ' \0 ' gesetzt (sofern dst nicht null ist oder dstmax nicht null oder größer als RSIZE_MAX ist).

Beispiel

Diesen Code ausführen 
#include <stdio.h>
#include <locale.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

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

Siehe auch

(C95) (C11)
wandelt einen schmalen Multibyte-Zeichenstring in einen Wide-String um, mit Zustand
(Funktion)
(C11)
wandelt einen Wide-String in einen schmalen Multibyte-Zeichenstring um
(Funktion)
C++-Dokumentation für mbstowcs