Namespaces
Variants

wcstombs, wcstombs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Definiert in Header <stdlib.h>
(1)
size_t wcstombs ( char * dst, const wchar_t * src, size_t len ) ;
(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 Sequenz von Breitzeichen aus dem Array, dessen erstes Element durch src gezeigt wird, in ihre schmale Multibyte-Darstellung, die im initialen Schaltzustand beginnt. Konvertierte Zeichen werden in den aufeinanderfolgenden Elementen des char-Arrays gespeichert, auf das durch dst gezeigt wird. Es werden nicht mehr als len Bytes in das Zielarray geschrieben.
Jedes Zeichen wird konvertiert wie durch einen Aufruf von wctomb , außer dass der Konvertierungszustand von wctomb unverändert bleibt. Die Konvertierung stoppt wenn:
* Das Nullzeichen L ' \0 ' wurde konvertiert und gespeichert. Die in diesem Fall gespeicherten Bytes sind die Unshift-Sequenz (falls erforderlich) gefolgt von ' \0 ' ,
* Es wurde ein wchar_t gefunden, der keinem gültigen Zeichen in der aktuellen C-Locale entspricht.
* Das nächste Multibyte-Zeichen, das gespeichert werden soll, würde len überschreiten.
Wenn src und dst sich überlappen, ist das Verhalten nicht spezifiziert.
2) Gleich wie (1) , außer dass
* Konvertierung erfolgt als ob durch wcrtomb , nicht durch wctomb
* die Funktion gibt ihr Ergebnis als Out-Parameter zurück retval
* Falls die Konvertierung ohne Schreiben eines Nullzeichens stoppt, speichert die Funktion ' \0 ' im nächsten Byte in dst , was entweder dst[len] oder dst[dstsz] sein kann, je nachdem was zuerst kommt (was bedeutet, dass bis zu len+1/dstsz+1 Bytes insgesamt geschrieben werden können). In diesem Fall wird möglicherweise keine Unshift-Sequenz vor dem abschließenden Nullzeichen geschrieben.
* wenn dst ein Nullzeiger ist, wird die Anzahl der Bytes, die erzeugt würden, in * retval gespeichert
* die Funktion überschreibt das Zielarray ab dem abschließenden Nullzeichen bis dstsz
* Wenn sich src und dst überlappen, ist das Verhalten nicht spezifiziert.
* Die folgenden Fehler werden zur Laufzeit erkannt und rufen den aktuell installierten Constraint-Handler auf:
  • retval oder src ist ein Nullzeiger
  • dstsz oder len ist größer als RSIZE_MAX (sofern dst nicht null ist)
  • dstsz ist nicht null (sofern dst nicht null ist)
  • len ist größer als dstsz und die Konvertierung trifft vor Erreichen von dstsz weder auf Null noch auf einen Kodierungsfehler im src -Array (sofern dst nicht null ist)
Wie bei allen bounds-checked-Funktionen ist wcstombs_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und der Benutzer __STDC_WANT_LIB_EXT1__ auf den Integer-Konstantenwert 1 setzt, bevor <stdlib.h> eingebunden wird.

Inhaltsverzeichnis

Hinweise

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

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

Parameter

dst - Zeiger auf ein schmales Zeichenarray, in dem das Multibyte-Zeichen gespeichert wird
src - Zeiger auf das erste Element eines nullterminierten Breitzeichen-Strings zur Konvertierung
len - Anzahl der im Array verfügbaren Bytes, auf das dst zeigt
dstsz - maximale Anzahl der zu schreibenden Bytes (Größe des dst Arrays)
retval - Zeiger auf ein size_t-Objekt, in dem das Ergebnis gespeichert wird

Rückgabewert

1) Bei Erfolg gibt die Anzahl der Bytes (einschließlich aller Shift-Sequenzen, aber ausschließlich des abschließenden ' \0 ' ) zurück, die in das Zeichenarray geschrieben wurden, dessen erstes Element durch dst gezeigt wird. Bei Konvertierungsfehler (falls ein ungültiges Breitzeichen angetroffen wurde), gibt ( size_t ) - 1 zurück.
2) Gibt bei Erfolg Null zurück (wobei die Anzahl der Bytes exklusive des abschließenden Nullzeichens, die in dst geschrieben wurden oder geschrieben worden wären, in * retval gespeichert wird), bei Fehler einen Wert ungleich Null. Im Falle einer Runtime Constraint Violation wird ( size_t ) - 1 in * retval gespeichert (sofern retval nicht null ist) und dst [ 0 ] auf ' \0 ' gesetzt (sofern dst nicht null ist oder dstmax nicht null oder größer als RSIZE_MAX ist).

Beispiel

Diesen Code ausführen 
#include <stdio.h>
#include <stdlib.h>
#include <locale.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

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

Siehe auch

(C95) (C11)
wandelt eine Wide-String in einen schmalen Multibyte-Zeichenstring um, mit Zustand
(Funktion)
(C11)
wandelt einen schmalen Multibyte-Zeichenstring in einen Wide-String um
(Funktion)
C++-Dokumentation für wcstombs