Namensräume
Varianten
Aktionen

wcrtomb, wcrtomb_s

Von cppreference.com
< c‎ | string‎ | multibyte
 
C
 
Bibliothek für Zeichenketten
 
Null-terminierte Multibyte-Strings
 
Definiert in Header <wchar.h>
(1)
size_t wcrtomb( char *s, wchar_t wc, mbstate_t *ps);
 (seit C95)
size_t wcrtomb( char *restrict s, wchar_t wc, mbstate_t *restrict ps);
 (seit C99)
errno_t wcrtomb_s(size_t *restrict retval, char *restrict s, rsize_t ssz,
                  wchar_t wc, mbstate_t *restrict ps);
 (2) (seit C11)

Konvertiert ein breites Zeichen in seine schmale Multibyte-Darstellung.

1) Wenn s kein Nullzeiger ist, ermittelt die Funktion die Anzahl der Bytes, die zur Speicherung der Multibyte-Zeichen-Darstellung von wc benötigt werden (einschließlich aller Umschal tsequenzen und unter Berücksichtigung des aktuellen Multibyte-Konvertierungszustands *ps) und speichert die Multibyte-Zeichen-Darstellung im Zeichenarray, dessen erstes Element von s gezeigt wird, und aktualisiert *ps nach Bedarf. Maximal MB_CUR_MAX Bytes können von dieser Funktion geschrieben werden.
Wenn s ein Nullzeiger ist, ist der Aufruf äquivalent zu wcrtomb(buf, L'\0', ps) für einen internen Puffer buf.
Wenn wc das Null-Breitzeichen L'\0' ist, wird ein Null-Byte gespeichert, dem jede Umschal tsequenz vorangestellt ist, die erforderlich ist, um den ursprünglichen Umschal tzustand wiederherzustellen, und der Konvertierungszustandsparameter *ps wird aktualisiert, um den ursprünglichen Umschal tzustand darzustellen.
Wenn das Umgebungsmakro __STDC_ISO_10646__ definiert ist, sind die Werte vom Typ wchar_t die gleichen wie die Kurzbezeichner der Zeichen im erforderlichen Unicode-Satz (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 bestimmt.
2) Gleich wie (1), außer dass
Wenn s ein Nullzeiger ist, ist der Aufruf äquivalent zu wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) mit internen Variablen retval und buf (deren Größe größer als MB_CUR_MAX ist)
Das Ergebnis wird im Ausgabeparameter retval zurückgegeben
Die folgenden Fehler werden zur Laufzeit erkannt und rufen die aktuell installierte Constraint-Handler-Funktion auf
  • retval oder ps ist ein Nullzeiger.
  • ssz ist Null oder größer als RSIZE_MAX (es sei denn, s ist Null)
  • ssz ist kleiner als die Anzahl der zu schreibenden Bytes (es sei denn, s ist Null)
  • s ist ein Nullzeiger, aber ssz ist nicht Null
Wie bei allen grenzgeprüften Funktionen ist wcrtomb_s nur dann garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert wird und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf die ganzzahlige Konstante 1 setzt, bevor <wchar.h> eingebunden wird.

Inhalt

[bearbeiten] Parameter

s - Zeiger auf das schmale Zeichenarray, in dem das Multibyte-Zeichen gespeichert wird
wc - Das zu konvertierende breite Zeichen
ps - Zeiger auf das Konvertierungszustandsobjekt, das bei der Interpretation des Multibyte-Strings verwendet wird
ssz - Maximale Anzahl der zu schreibenden Bytes (die Größe des Puffers s)
retval - Zeiger auf einen Ausgabeparameter, in dem das Ergebnis (Anzahl der Bytes im Multibyte-String einschließlich aller Umschal tsequenzen) gespeichert wird

[bearbeiten] Rückgabewert

1) Bei Erfolg wird die Anzahl der Bytes (einschließlich aller Umschal tsequenzen) zurückgegeben, die in das Zeichenarray geschrieben wurden, dessen erstes Element von s gezeigt wird.
Bei einem Fehler (wenn wc kein gültiges breites Zeichen ist) wird (size_t)-1 zurückgegeben, EILSEQ in errno gespeichert und *ps in einem undefinierten Zustand belassen.
2) Gibt Null bei Erfolg und einen Nicht-Null-Wert bei Fehler zurück. In diesem Fall wird s[0] auf '\0' gesetzt (es sei denn, s ist Null oder ssz ist Null oder größer als RSIZE_MAX) und *retval wird auf (size_t)-1 gesetzt (es sei denn, retval ist Null)

[bearbeiten] Beispiel

Führen Sie diesen Code aus
#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
#include <stdlib.h>
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    mbstate_t state;
    memset(&state, 0, sizeof state);
    wchar_t in[] = L"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    size_t in_sz = sizeof in / sizeof *in;
 
    printf("Processing %zu wchar_t units: [ ", in_sz);
    for(size_t n = 0; n < in_sz; ++n) printf("%#x ", (unsigned int)in[n]);
    puts("]");
 
    char out[MB_CUR_MAX * in_sz];
    char *p = out;
    for(size_t n = 0; n < in_sz; ++n) {
        int rc = wcrtomb(p, in[n], &state); 
        if(rc == -1) break;
        p += rc;
    }
 
    size_t out_sz = p - out;
    printf("into %zu UTF-8 code units: [ ", out_sz);
    for(size_t x = 0; x < out_sz; ++x) printf("%#x ", +(unsigned char)out[x]);
    puts("]");
}

Ausgabe

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

[bearbeiten] Referenzen

  • C11-Standard (ISO/IEC 9899:2011)
  • 7.29.6.3.3 Die Funktion wcrtomb (S. 444)
  • K.3.9.3.1.1 Die Funktion wcrtomb_s (S. 647-648)
  • C99-Standard (ISO/IEC 9899:1999)
  • 7.24.6.3.3 Die Funktion wcrtomb (S. 390)

[bearbeiten] Siehe auch

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