std::wcstombs
| Definiert in Header <cstdlib> |
||
| std::size_t wcstombs( char* dst, const wchar_t* src, std::size_t len ); |
||
Konvertiert eine Sequenz von Wide-Zeichen aus dem Array, auf dessen erstes Element src zeigt, in seine schmale Multibyte-Darstellung, die im Anfangs-Shift-Zustand beginnt. Konvertierte Zeichen werden in den aufeinanderfolgenden Elementen des Char-Arrays gespeichert, auf dessen erstes Element dst zeigt. Nicht mehr als len Bytes werden in das Ziel-Array geschrieben.
Jedes Zeichen wird konvertiert, als ob es durch einen Aufruf von std::wctomb erfolgt wäre, mit der Ausnahme, dass der Konvertierungszustand von wctomb unberührt bleibt. Die Konvertierung stoppt, wenn
- Das Nullzeichen konvertiert und gespeichert wurde.
- Ein wchar_t gefunden wurde, das keinem gültigen Zeichen in der aktuellen C-Locale entspricht.
- Das nächste zu speichernde Multibyte-Zeichen len überschreiten würde.
Inhalt |
[bearbeiten] Anmerkungen
In den meisten Implementierungen aktualisiert diese Funktion ein globales statisches Objekt vom Typ std::mbstate_t, während sie die Zeichenkette verarbeitet, und kann nicht gleichzeitig von zwei Threads aufgerufen werden. std::wcsrtombs sollte in solchen Fällen verwendet werden.
POSIX spezifiziert eine häufige Erweiterung: Wenn dst ein Nullzeiger ist, gibt diese Funktion die Anzahl der Bytes zurück, die in dst geschrieben würden, wenn sie konvertiert werden. Ein ähnliches Verhalten ist Standard für std::wcsrtombs.
[bearbeiten] Parameter
| dst | - | Zeiger auf das schmale Zeichenarray, in dem das Multibyte-Zeichen gespeichert wird |
| src | - | Zeiger auf das erste Element einer nullterminierten Wide-Zeichenkette, die konvertiert werden soll |
| len | - | Anzahl der Bytes, die im von dst gezeigten Array verfügbar sind |
[bearbeiten] Rückgabewert
Bei Erfolg wird die Anzahl der Bytes zurückgegeben (einschließlich aller Shift-Sequenzen, aber ausschließlich des terminierenden '\0'), die in das Zeichenarray geschrieben wurden, auf dessen erstes Element dst zeigt.
Bei einem Konvertierungsfehler (wenn ein ungültiges Wide-Zeichen angetroffen wurde) wird static_cast<std::size_t>(-1) zurückgegeben.
[bearbeiten] Beispiel
#include <clocale> #include <cstdlib> #include <iostream> int main() { std::setlocale(LC_ALL, "en_US.utf8"); // UTF-8 narrow multibyte encoding const wchar_t* wstr = L"z\u00df\u6c34\U0001d10b"; // or L"zß水𝄋" char mbstr[11]; std::wcstombs(mbstr, wstr, 11); std::cout << "multibyte string: " << mbstr << '\n'; }
Ausgabe
multibyte string: zß水𝄋
[bearbeiten] Siehe auch
| konvertiert einen Wide-String in einen schmalen Multibyte-Zeichenstring, gegeben den Zustand (Funktion) | |
| konvertiert einen schmalen Multibyte-Zeichenstring in einen Wide-String (Funktion) | |
| [virtuell] |
konvertiert eine Zeichenkette von InternT nach ExternT, z. B. beim Schreiben in eine Datei(virtual protected member function of std::codecvt<InternT,ExternT,StateT>) |
| C-Dokumentation für wcstombs
| |
