mbrtowc

 

C

Compiler-Unterstützung

Sprache

Header

Typunterstützung

Programm-Dienstprogramme

Unterstützung für variable Funktionsargumente

Fehlerbehandlung

Dynamische Speicherverwaltung

Bibliothek für Zeichenketten

Algorithmen

Numerik

Datums- und Zeitdienstprogramme

Ein-/Ausgabeunterstützung

Lokalisierungsunterstützung

Unterstützung für Nebenläufigkeit (C11)

Technische Spezifikationen

Symbolindex

 

Bibliothek für Zeichenketten

Null-terminierte Byte-Strings

Null-terminierte Multibyte-Strings

Null-terminierte breite Zeichenketten

 

Null-terminierte Multibyte-Strings

Funktionen
Breit-/Multibyte-Konvertierungen
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)   mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
Typen
mbstate_t (C95) char8_t (C23)	char16_t (C11) char32_t (C11)
Makros
MB_LEN_MAX	MB_CUR_MAX

 

Definiert in Header <wchar.h>
size_t mbrtowc( wchar_t* pwc, const char* s, size_t n, mbstate_t* ps );		(seit C95)
size_t mbrtowc( wchar_t *restrict pwc, const char *restrict s, size_t n,                 mbstate_t *restrict ps );		(seit C99)

Konvertiert ein schmalen Multibyte-Zeichen in seine Wide-Character-Repräsentation.

Wenn s kein Nullzeiger ist, werden höchstens n Bytes der schmalen Multibyte-Zeichenzeichenkette untersucht, beginnend mit dem Byte, auf das s zeigt, um die Anzahl der Bytes zu ermitteln, die zur Vervollständigung des nächsten Multibyte-Zeichens erforderlich sind (einschließlich aller Umschaltsequenzen und unter Berücksichtigung des aktuellen Multibyte-Konvertierungszustands *ps). Wenn die Funktion feststellt, dass das nächste Multibyte-Zeichen in s vollständig und gültig ist, wird es in das entsprechende Wide-Character konvertiert und in *pwc gespeichert (wenn pwc nicht null ist).

Wenn s ein Nullzeiger ist, werden die Werte von n und pwc ignoriert und der Aufruf ist äquivalent zu mbrtowc(NULL, "", 1, ps).

Wenn das erzeugte Wide-Character das Nullzeichen ist, ist der in *ps gespeicherte Konvertierungszustand der anfängliche Umschaltzustand.

Wenn das Makro __STDC_ISO_10646__ definiert ist, sind die Werte des Typs wchar_t identisch mit den Kurzbezeichnern der Zeichen des erforderlichen Unicode-Zeichensatzes (typischerweise UTF-32-Kodierung); andernfalls ist dies implementierungsabhängig. In jedem Fall wird die von dieser Funktion verwendete Multibyte-Zeichenkodierung durch die aktuell aktive C-Locale festgelegt.

Parameter

pwc	-	Zeiger auf die Stelle, an der das resultierende Wide-Character geschrieben werden soll
s	-	Zeiger auf den Mehrbyte-Zeichenstring, der als Eingabe verwendet wird
n	-	Grenze für die Anzahl der Bytes in s, die untersucht werden können
ps	-	Zeiger auf den Konvertierungszustand, der bei der Interpretation der schmalen Multibyte-Zeichenzeichenkette verwendet wird

Rückgabewert

Das erste der folgenden zutreffenden Elemente

• ​0​, wenn das aus s konvertierte Zeichen (und, falls nicht null, in pwc gespeichert) das Nullzeichen war
• die Anzahl der Bytes [1...n] des erfolgreich aus s konvertierten Multibyte-Zeichens
• (size_t)-2, wenn die nächsten n Bytes ein unvollständiges, aber bisher gültiges Multibyte-Zeichen darstellen. Es wird nichts in *pwc geschrieben.
• (size_t)-1, wenn ein Kodierungsfehler auftritt. Es wird nichts in *pwc geschrieben, der Wert EILSEQ wird in errno gespeichert und der Wert von *ps bleibt undefiniert.

Beispiel

Führen Sie diesen Code aus

#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    mbstate_t state;
    memset(&state, 0, sizeof state);
    char in[] = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"
    size_t in_sz = sizeof in / sizeof *in;
 
    printf("Processing %zu UTF-8 code units: [ ", in_sz);
    for(size_t n = 0; n < in_sz; ++n) printf("%#x ", (unsigned char)in[n]);
    puts("]");
 
    wchar_t out[in_sz];
    char *p_in = in, *end = in + in_sz;
    wchar_t *p_out = out;
    int rc;
    while((rc = mbrtowc(p_out, p_in, end - p_in, &state)) > 0)
    {
        p_in += rc;
        p_out += 1;
    }
 
    size_t out_sz = p_out - out + 1;
    printf("into %zu wchar_t units: [ ", out_sz);
    for(size_t x = 0; x < out_sz; ++x) printf("%#x ", out[x]);
    puts("]");
}

Ausgabe

Processing 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]
into 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]

Referenzen

• C11-Standard (ISO/IEC 9899:2011)

• 7.29.6.3.2 Die Funktion mbrtowc (S. 443)

• C99-Standard (ISO/IEC 9899:1999)

• 7.24.6.3.2 Die Funktion mbrtowc (S. 389)

Siehe auch

mbtowc	konvertiert das nächste Multibyte-Zeichen in ein Wide-Zeichen (Funktion)
wcrtombwcrtomb_s (C95)(C11)	konvertiert ein Wide-Zeichen in seine Multibyte-Darstellung, gegeben den Zustand (Funktion)
C++ Dokumentation für mbrtowc