Namespaces
Variants

    wcstombs, wcstombs_s

    Von de.cppreference.net
     
    C
     
    Zeichenkettenbibliothek
     
    Nullterminierte Multibyte-Strings
     
    Definiert in Header <stdlib.h> 
    size_t wcstombs( char* dst, const wchar_t* src, size_t len );
    		(1) (bis C99) 
    size_t wcstombs( char* restrict dst, const wchar_t* restrict src, size_t len );
    		(seit C99) 
    errno_t wcstombs_s( size_t* restrict retval, char* restrict dst, rsize_t dstsz,
                    const wchar_t* restrict src, rsize_t len );
    		(2) (seit C11)
    1) Konvertiert eine Folge von Breitzeichen aus dem Array, dessen erstes Element von src zeigt, in seine schmale Multibyte-Darstellung, die im anfänglichen Verschiebungszustand beginnt. Die konvertierten Zeichen werden in den aufeinanderfolgenden Elementen des char-Arrays gespeichert, auf das dst zeigt. Es werden nicht mehr als len Bytes in das Zielarray geschrieben.
    Jedes Zeichen wird wie durch einen Aufruf von wctomb konvertiert, mit der Ausnahme, dass der Konvertierungszustand von wctomb nicht beeinflusst wird. Die Konvertierung wird abgebrochen, wenn:
    • Das Nullzeichen L'\0' konvertiert und gespeichert wurde. Die in diesem Fall gespeicherten Bytes sind die Rückverschiebungssequenz (falls erforderlich) gefolgt von '\0',
    • Ein wchar_t wurde gefunden, das keinem gültigen Zeichen in der aktuellen C-Locale entspricht.
    • Das nächste zu speichernde Multibyte-Zeichen würde len überschreiten.
    Wenn sich src und dst überschneiden, ist das Verhalten undefiniert.
    2) Gleiche wie (1), mit der Ausnahme, dass
    • Die Konvertierung erfolgt wie durch wcrtomb, nicht wctomb
    • Die Funktion gibt ihr Ergebnis als out-Parameter retval
    • zurückWenn die Konvertierung ohne Schreiben eines Nullzeichens stoppt, speichert die Funktion '\0' im nächsten Byte in dst, was dst[len] oder dst[dstsz] sein kann, je nachdem, was zuerst kommt (d.h. es können insgesamt bis zu len+1/dstsz+1 Bytes geschrieben werden). In diesem Fall wird möglicherweise keine Rückverschiebungssequenz vor dem abschließenden Nullzeichen geschrieben.
    • Wenn dst ein Nullzeiger ist, wird die Anzahl der Bytes, die erzeugt würden, in *retval
    • gespeichertDie Funktion überschreibt das Zielarray ab dem abschließenden Nullzeichen bis dstsz
    • Wenn sich src und dst überschneiden, ist das Verhalten undefiniert.
    • Die folgenden Fehler werden zur Laufzeit erkannt und rufen die derzeit installierte Constraint-Handler-Funktion auf:
    • retval oder src ist ein Nullzeiger
    • dstsz oder len ist größer als RSIZE_MAX (außer wenn dst null ist)
    • dstsz ist nicht null (außer wenn dst null ist)
    • len ist größer als dstsz und die Konvertierung trifft bis zum Erreichen von src weder auf ein Nullzeichen noch einen Kodierungsfehler im dstsz-Array (außer wenn dst null ist)
    Wie bei allen bereichsgeprüften Funktionen ist wcstombs_s nur dann garantiert verfügbar, wenn __STDC_LIB_EXT1__ vom Implementierung definiert wird und der Benutzer __STDC_WANT_LIB_EXT1__ auf die Integer-Konstante 1 setzt, bevor er <stdlib.h> einbindet.

    Hinweise

    In den meisten Implementierungen aktualisiert wcstombs ein globales statisches Objekt vom Typ mbstate_t, während es die Zeichenfolge verarbeitet, und kann nicht gleichzeitig von zwei Threads aufgerufen werden. In solchen Fällen sollten wcsrtombs oder wcstombs_s verwendet werden.

    POSIX spezifiziert eine verbreitete Erweiterung: Wenn dst ein Nullzeiger ist, gibt diese Funktion die Anzahl der Bytes zurück, die in dst geschrieben würden, wenn sie konvertiert würden. Ein ähnliches Verhalten ist standardmäßig für wcsrtombs und wcstombs_s.

    Parameter

    dst - Zeiger auf das schmale Zeichenarray, in dem das Multibyte-Zeichen gespeichert wird
    src - Zeiger auf das erste Element einer nullterminierten Breitzeichenfolge, die konvertiert werden soll
    len - Anzahl der Bytes, die im Array, auf das dst zeigt, verfügbar sind
    dstsz - maximale Anzahl an Bytes, die geschrieben werden (Größe des dst-Arrays)
    retval - Zeiger auf ein size_t-Objekt, in dem das Ergebnis gespeichert wird

    Rückgabewert

    1) Bei Erfolg wird die Anzahl der Bytes (einschließlich etwaiger Verschiebungssequenzen, aber ohne das abschließende '\0') zurückgegeben, die in das Zeichenarray geschrieben wurden, dessen erstes Element von dst zeigt. Bei einem Konvertierungsfehler (wenn ein ungültiges Breitzeichen gefunden wurde) wird (size_t)-1 zurückgegeben.
    2) Gibt bei Erfolg null zurück (in diesem Fall wird die Anzahl der Bytes ohne das abschließende Null, die in dst geschrieben wurden oder geschrieben würden, in *retval gespeichert), bei Fehler einen Wert ungleich null. Im Falle einer Laufzeit-Constraint-Verletzung wird (size_t)-1 in *retval gespeichert (außer wenn retval null ist) und dst[0] auf '\0' gesetzt (außer wenn dst null ist oder dstmax null oder größer als RSIZE_MAX ist)

    Beispiel

    Diesen Code ausführen
    #include <locale.h>
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    // 4 wide characters
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // they occupy 10 bytes in UTF-8
    char dst[11];

    setlocale(LC_ALL, "en_US.utf8");
    printf("wide-character string: '%ls'\n",src);
    for (size_t ndx = 0; ndx < sizeof src / sizeof src[0]; ++ndx)
        printf("   src[%2zu] = %#8x\n", ndx, src[ndx]);
    
    int rtn_val = wcstombs(dst, src, sizeof dst);
    printf("rtn_val = %d\n", rtn_val);
    if (rtn_val > 0)
        printf("multibyte string:  '%s'\n",dst);
    for (size_t ndx = 0; ndx < sizeof dst; ++ndx)
        printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
}

    Ausgabe: 

    wide-character string: 'zß水🍌'
   src[ 0] =     0x7a
   src[ 1] =     0xdf
   src[ 2] =   0x6c34
   src[ 3] =  0x1f34c
   src[ 4] =        0
rtn_val = 10
multibyte string:  'zß水🍌'
   dst[ 0] = 0x7a
   dst[ 1] = 0xc3
   dst[ 2] = 0x9f
   dst[ 3] = 0xe6
   dst[ 4] = 0xb0
   dst[ 5] = 0xb4
   dst[ 6] = 0xf0
   dst[ 7] = 0x9f
   dst[ 8] = 0x8d
   dst[ 9] = 0x8c
   dst[10] =  0

    Referenzen

    • C23 Standard (ISO/IEC 9899:2024):
    • 7.22.8.2 Die Funktion wcstombs (S.: TBD)
    • K.3.6.5.2 Die Funktion wcstombs_s (S.: TBD)
    • C17 Standard (ISO/IEC 9899:2018):
    • 7.22.8.2 Die Funktion wcstombs (S.: TBD)
    • K.3.6.5.2 Die Funktion wcstombs_s (S.: TBD)
    • C11 Standard (ISO/IEC 9899:2011):
    • 7.22.8.2 Die Funktion wcstombs (S.: 360)
    • K.3.6.5.2 Die Funktion wcstombs_s (S.: 612-614)
    • C99 Standard (ISO/IEC 9899:1999):
    • 7.20.8.2 Die Funktion wcstombs (S.: 324)
    • C89/C90 Standard (ISO/IEC 9899:1990):
    • 4.10.8.2 Die Funktion wcstombs

    Siehe auch

    (C95)(C11)
    		 konvertiert eine Breitzeichenfolge in eine schmale Multibyte-Zeichenfolge, unter Angabe des Zustands
    (Funktion)
    (C11)
    		 konvertiert eine schmale Multibyte-Zeichenfolge in eine Breitzeichenfolge
    (Funktion)
    C++-Dokumentation für wcstombs