Namensräume
Varianten
Aktionen

mbsrtowcs, mbsrtowcs_s

Von cppreference.com
< c‎ | string‎ | multibyte
 
C
 
Bibliothek für Zeichenketten
 
Null-terminierte Multibyte-Strings
 
Definiert in Header <wchar.h>
(1)
size_t mbsrtowcs( wchar_t* dst, const char** src, size_t len, mbstate_t* ps );
 (seit C95)
(bis C99)
size_t mbsrtowcs( wchar_t *restrict dst, const char **restrict src, size_t len,
                  mbstate_t *restrict ps );
 (seit C99)
errno_t mbsrtowcs_s( size_t *restrict retval,

                     wchar_t *restrict dst, rsize_t dstsz,
                     const char **restrict src, rsize_t len,

                     mbstate_t *restrict ps );
 (2) (seit C11)
1) Konvertiert eine nullterminierte Multibyte-Zeichensequenz, die im durch *ps beschriebenen Konvertierungszustand beginnt, aus dem Array, dessen erstes Element auf *src zeigt, in ihre Wide-Character-Repräsentation. Wenn dst nicht null ist, werden konvertierte Zeichen in den aufeinanderfolgenden Elementen des von dst zeigenden wchar_t-Arrays gespeichert. Es werden nicht mehr als len Wide Characters in das Zielarray geschrieben. Jedes Multibyte-Zeichen wird so konvertiert, als ob ein Aufruf von mbrtowc durchgeführt worden wäre. Die Konvertierung stoppt, wenn
  • Das Multibyte-Nullzeichen wurde konvertiert und gespeichert. *src wird auf den Nullzeigerwert gesetzt und *ps repräsentiert den initialen Shift-Zustand.
  • Ein ungültiges Multibyte-Zeichen (gemäß der aktuellen C-Locale) wurde angetroffen. *src wird so gesetzt, dass es auf den Anfang des ersten nicht konvertierten Multibyte-Zeichens zeigt.
  • das nächste zu speichernde Wide Character len überschreiten würde. *src wird so gesetzt, dass es auf den Anfang des ersten nicht konvertierten Multibyte-Zeichens zeigt. Diese Bedingung wird nicht geprüft, wenn dst ein Nullzeiger ist.
2) Gleich wie (1), außer dass
  • die Funktion gibt ihr Ergebnis als Out-Parameter retval zurück
  • wenn nach dem Schreiben von len Wide Characters kein Nullzeichen nach len in dst geschrieben wurde, dann wird L'\0' in dst[len] gespeichert, was bedeutet, dass insgesamt len+1 Wide Characters geschrieben werden.
  • die Funktion überschreibt das Zielarray vom terminierenden Nullzeichen an bis zu dstsz
  • Wenn sich src und dst überschneiden, ist das Verhalten undefiniert.
  • die folgenden Fehler werden zur Laufzeit erkannt und rufen die aktuell installierte Constraint-Handler-Funktion auf
  • retval, ps, src oder *src ist ein Nullzeiger
  • 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 Array *src und len ist größer als dstsz (es sei denn, dst ist null)
Wie bei allen grenzgeprüften Funktionen ist mbsrtowcs_s nur dann garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert wird und wenn der Benutzer __STDC_WANT_LIB_EXT1__ vor dem Einbinden von <wchar.h> auf die Ganzzahlkonstante 1 setzt.

Inhalt

[edit] Parameter

dst - Zeiger auf ein Wide-Character-Array, in dem die Ergebnisse gespeichert werden
src - Zeiger auf einen Zeiger auf das erste Element eines nullterminierten Multibyte-Strings
len - Anzahl der Wide-Characters, die im von dst gezeigten Array verfügbar sind
ps - Zeiger auf das Konvertierungszustandsobjekt
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 Zeichenarray geschrieben wurden. Wenn dst ein Nullzeiger ist, wird die Anzahl der Wide Characters zurückgegeben, die bei unbegrenzter Länge geschrieben worden wären. Bei einem Konvertierungsfehler (wenn ein ungültiges Multibyte-Zeichen angetroffen wurde) wird (size_t)-1 zurückgegeben, EILSEQ wird in errno gespeichert und *ps bleibt in einem undefinierten Zustand.
2) null bei Erfolg (in diesem Fall wird die Anzahl der Wide Characters, exklusive des abschließenden Nullzeichens, die in dst geschrieben wurden oder geschrieben worden wären, in *retval gespeichert), nicht 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 <wchar.h>
#include <string.h>
 
void print_as_wide(const char* mbstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + mbsrtowcs(NULL, &mbstr, 0, &state);
    wchar_t wstr[len];
    mbsrtowcs(&wstr[0], &mbstr, len, &state);
    wprintf(L"Wide string: %ls \n", wstr);
    wprintf(L"The length, including L'\\0': %zu\n", len);
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_as_wide(u8"z\u00df\u6c34\U0001f34c"); // u8"zß水🍌"
}

Ausgabe

Wide string: zß水🍌
The length, including L'\0': 5

[edit] Referenzen

  • C11-Standard (ISO/IEC 9899:2011)
  • 7.29.6.4.1 Die Funktion mbsrtowcs (S. 445)
  • K.3.9.3.2.1 Die Funktion mbsrtowcs_s (S. 648-649)
  • C99-Standard (ISO/IEC 9899:1999)
  • 7.24.6.4.1 Die Funktion mbsrtowcs (S. 391)

[edit] Siehe auch

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