Namespaces
Variants

wcrtomb, wcrtomb_s

From cppreference.net
C
Strings library
Null-terminated 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)

Wandelt ein Breitzeichen in seine schmale Multibyte-Darstellung um.

1) Wenn s kein Nullzeiger ist, bestimmt die Funktion die Anzahl der Bytes, die zur Speicherung der Multibyte-Zeichendarstellung von wc erforderlich sind (einschließlich aller Shift-Sequenzen und unter Berücksichtigung des aktuellen Multibyte-Konvertierungszustands * ps ), und speichert die Multibyte-Zeichendarstellung im Zeichenarray, dessen erstes Element durch s gezeigt wird, wobei * ps bei Bedarf aktualisiert wird. Diese Funktion kann maximal MB_CUR_MAX Bytes schreiben.
Wenn s ein Nullzeiger ist, entspricht der Aufruf wcrtomb ( buf, L ' \0 ' , ps ) für einen internen Puffer buf .
Wenn wc das Null-Breitzeichen L ' \0 ' ist, wird ein Null-Byte gespeichert, vorangestellt von jeder Shift-Sequenz, die notwendig ist, um den initialen Shift-Zustand wiederherzustellen, und der Konvertierungszustandsparameter * ps wird aktualisiert, um den initialen Shift-Zustand darzustellen.
Falls das Umgebungsmakro __STDC_ISO_10646__ definiert ist, entsprechen die Werte des Typs wchar_t den Kurzidentifikatoren der Zeichen im Unicode-Erforderlichen Satz (typischerweise UTF-32-Kodierung); andernfalls ist es implementierungsdefiniert. In jedem Fall wird die von dieser Funktion verwendete Multibyte-Zeichenkodierung durch die aktuell aktive C-Locale spezifiziert.
2) Gleich wie (1) , außer dass
falls s ein Nullzeiger ist, entspricht der Aufruf wcrtomb_s ( & retval, buf, sizeof buf, L ' \0 ' , ps ) mit internen Variablen retval und buf (deren Größe größer ist als MB_CUR_MAX )
das Ergebnis wird im Out-Parameter retval zurückgegeben
Die folgenden Fehler werden zur Laufzeit erkannt und rufen den aktuell installierten Constraint-Handler 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 bounds-checked-Funktionen ist wcrtomb_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf die Integer-Konstante 1 setzt, bevor <wchar.h> eingebunden wird.

Inhaltsverzeichnis

Parameter

s - Zeiger auf ein schmales Zeichenarray, in dem das Multibyte-Zeichen gespeichert wird
wc - das zu konvertierende Breitzeichen
ps - Zeiger auf das Konvertierungszustandsobjekt, das bei der Interpretation der Multibyte-Zeichenkette verwendet wird
ssz - maximale Anzahl der zu schreibenden Bytes (die Größe des Puffers s )
retval - Zeiger auf einen Out-Parameter, in dem das Ergebnis (Anzahl der Bytes in der Multibyte-Zeichenkette einschließlich aller Shift-Sequenzen) gespeichert wird

Rückgabewert

1) Bei Erfolg gibt die Anzahl der Bytes (einschließlich aller Shift-Sequenzen) zurück, die in das Zeichenarray geschrieben wurden, dessen erstes Element durch s gezeigt wird.
Bei Fehler (falls wc kein gültiges Breitzeichen ist), gibt ( size_t ) - 1 zurück, speichert EILSEQ in errno und belässt * ps in einem nicht spezifizierten Zustand.
2) Gibt bei Erfolg Null zurück und bei Fehler einen Wert ungleich Null, wobei in diesem Fall s [ 0 ] auf ' \0 ' gesetzt wird (sofern s nicht null ist oder ssz nicht null oder größer als RSIZE_MAX ist) und * retval auf ( size_t ) - 1 gesetzt wird (sofern retval nicht null ist)

Beispiel

Diesen Code ausführen 
#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 ]

Referenzen

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

Siehe auch

(C11)
wandelt ein Breitzeichen in seine Multibyte-Darstellung um
(Funktion)
(C95)
wandelt das nächste Multibyte-Zeichen in ein Breitzeichen um, unter Berücksichtigung des Zustands
(Funktion)
C++-Dokumentation für wcrtomb