Namensräume
Varianten
Aktionen

mbstowcs, mbstowcs_s

Von cppreference.com
< c‎ | string‎ | multibyte
 
C
 
Bibliothek für Zeichenketten
 
Null-terminierte Multibyte-Strings
 
Definiert im 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 Wide-Character-Darstellung. Konvertierte Zeichen werden in den aufeinanderfolgenden Elementen des von dst gezeigten Arrays gespeichert. Es werden nicht mehr als len Wide-Characters in das Zielarray geschrieben.
Jedes Zeichen wird wie bei einem Aufruf von mbtowc konvertiert, mit der Ausnahme, dass der Konvertierungszustand von mbtowc unberührt bleibt. Die Konvertierung stoppt, wenn
* das Multibyte-Nullzeichen konvertiert und gespeichert wurde.
* ein ungültiges (in der aktuellen C-Locale) Multibyte-Zeichen angetroffen wurde.
* das nächste zu speichernde Wide-Character len überschreiten würde.
Wenn sich src und dst überlappen, ist das Verhalten undefiniert.
2) Gleich wie (1), außer dass
* die Konvertierung wie bei mbrtowc erfolgt, nicht wie bei mbtowc
* die Funktion ihr Ergebnis als Out-Parameter retval zurückgibt
* wenn nach dem Schreiben von len Wide-Characters kein Nullzeichen nach dst geschrieben wurde, dann wird L'\0' in dst[len] geschrieben, was insgesamt len+1 Wide-Characters bedeutet
* wenn dst ein Null-Zeiger ist, wird die Anzahl der Wide-Characters, die produziert würden, in *retval gespeichert
* die Funktion überschreibt das Zielarray vom terminierenden Nullzeichen bis dstsz
* Wenn sich src und dst überlappen, ist das Verhalten nicht spezifiziert.
* die folgenden Fehler werden zur Laufzeit erkannt und rufen die aktuell installierte Constraint-Handler-Funktion auf
  • retval oder src ist ein Null-Zeiger
  • dstsz oder len ist größer als RSIZE_MAX/sizeof(wchar_t) (es sei denn, dst ist null)
  • dstsz ist nicht null (es sei denn, dst ist null)
  • Es gibt kein Nullzeichen in den ersten dstsz Multibyte-Zeichen im src-Array und len ist größer als dstsz (es sei denn, dst ist null)
Wie bei allen grenzgeprüften Funktionen ist mbstowcs_s nur dann garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf die ganzzahlige Konstante 1 setzt, bevor <stdlib.h> eingebunden wird.

Inhalt

[edit] Anmerkungen

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. mbsrtowcs sollte in solchen Fällen verwendet werden.

POSIX spezifiziert eine gängige Erweiterung: Wenn dst ein Null-Zeiger ist, gibt diese Funktion die Anzahl der Wide-Characters zurück, die zu dst konvertiert würden. Ein ähnliches Verhalten ist Standard für mbstowcs_s und für mbsrtowcs.

[edit] Parameter

dst - Zeiger auf ein Wide-Character-Array, in dem die Wide-String gespeichert wird
src - Zeiger auf das erste Element einer nullterminierten Multibyte-Zeichenkette, die konvertiert werden soll
len - Anzahl der Wide-Characters, die im von dst gezeigten Array verfügbar sind
dstsz - maximale Anzahl von Wide-Characters, die geschrieben werden (Größe des dst-Arrays)
retval - Zeiger auf ein size_t-Objekt, in dem das Ergebnis gespeichert wird

[edit] Rückgabewert

1) Bei Erfolg wird die Anzahl der Wide-Characters zurückgegeben, exklusive des abschließenden L'\0', die in das Zielarray geschrieben wurden. Bei einem Konvertierungsfehler (wenn ein ungültiges Multibyte-Zeichen angetroffen wurde) wird (size_t)-1 zurückgegeben.
2) Null bei Erfolg (in diesem Fall wird die Anzahl der Wide-Characters, exklusive des abschließenden Nullzeichens, die in dst geschrieben wurden oder würden, in *retval gespeichert), ungleich Null bei Fehler. Im Falle einer Laufzeit-Constraint-Verletzung wird (size_t)-1 in *retval gespeichert (es sei denn, retval ist null) und dst[0] wird auf L'\0' gesetzt (es sei denn, dst ist null oder dstmax ist null oder größer als RSIZE_MAX).

[edit] Beispiel

Führen Sie diesen Code aus
#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ß水🍌

[edit] Referenzen

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

[edit] Siehe auch

(C95)(C11)
 konvertiert einen schmalen Multibyte-Zeichenstring in einen Wide-String, gegeben den Zustand
(Funktion) [bearbeiten]
(C11)
 konvertiert einen Wide-String in einen schmalen Multibyte-Zeichenstring
(Funktion) [bearbeiten]
C++ Dokumentation für mbstowcs
Abgerufen von "https://cppreference.de/mwiki/index.php?title=c/string/multibyte/mbstowcs&oldid=102011"