Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/string/multibyte/mbstowcs"

From cppreference.com
< cpp‎ | string‎ | multibyte
m (Text replace - "{{cpp|" to "{{c|")
m
 
(11 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
{{cpp/title|mbstowcs}}
 
{{cpp/title|mbstowcs}}
−
{{cpp/string/multibyte/sidebar}}
+
{{cpp/string/multibyte/}}
−
{{ddcl | header=cstdlib |
+
{{ddcl|header=cstdlib|
−
std::size_t mbstowcs( wchar_t* dst, const char* src, std::size_t len)
+
std::size_t mbstowcs( wchar_t* dst, const char* src, std::size_t len )
 
}}
 
}}
  
−
Converts a multibyte character string from the array whose first element is pointed to by {{tt|src}} to its wide character representation. Converted characters are stored in the successive elements of the array pointed to by {{tt|dst}}. No more than {{tt|len}} wide characters are written to the destination array.
+
Converts a multibyte character string from the array whose first element is pointed to by {{|src}} to its wide character representation. Converted characters are stored in the successive elements of the array pointed to by {{|dst}}. No more than {{|len}} wide characters are written to the destination array.
−
 
+
−
Each character is converted as if by a call to {{c|std::mbtowc}}, except that the mbtowc conversion state is unaffected. The conversion stops if:
+
  
 +
 
* The multibyte null character was converted and stored.
 
* The multibyte null character was converted and stored.
 
* An invalid (in the current C locale) multibyte character was encountered.
 
* An invalid (in the current C locale) multibyte character was encountered.
−
* The next wide character to be stored would exceed {{tt|len}}.
+
* The next wide character to be stored would exceed {{|len}}.
  
 
===Notes===
 
===Notes===
−
In most implementations, this function updates a global static object of type {{c|std::mbstate_t}} as it processes through the string, and cannot be called simultaneously by two threads, {{c|std::mbsrtowcs should be used in such cases.
+
In most implementations, this function updates a global static object of type {{|std::mbstate_t}} as it processes through the string, and cannot be called simultaneously by two threads, {{|std::mbsrtowcsshould be used in such cases.
  
−
POSIX specifies a common extension: if {{tt|dst}} is a null pointer, this function returns the number of wide characters that would be written to {{tt|dst}}, if converted. Similar behavior is standard for {{c|std::mbsrtowcs}}.
+
POSIX specifies a common extension: if {{|dst}} is a null pointer, this function returns the number of wide characters that would be written to {{|dst}}, if converted. Similar behavior is standard for {{|std::mbsrtowcs}}.
  
 
===Parameters===
 
===Parameters===
−
{{param list begin}}
+
{{begin}}
−
{{param list item | dst | pointer to wide character array where the wide string will be stored}}
+
{{|dst|pointer to wide character array where the wide string will be stored}}
−
{{param list item | src | pointer to the first element of a null-terminated multibyte string to convert}}
+
{{|src|pointer to the first element of a null-terminated multibyte string to convert}}
−
{{param list item | len | number of wide characters available in the array pointed to by dst}}
+
{{|len|number of wide characters available in the array pointed to by dst}}
−
{{param list end}}
+
{{end}}
  
 
===Return value===
 
===Return value===
 
On success, returns the number of wide characters, excluding the terminating {{c|L'\0'}}, written to the destination array.
 
On success, returns the number of wide characters, excluding the terminating {{c|L'\0'}}, written to the destination array.
  
−
On conversion error (if invalid multibyte character was encountered), returns {{c|static_cast<std::size_t>(-1)}}.
+
On conversion error (if invalid multibyte character was encountered), returns {{c|static_cast<std::size_t> (-1)}}.
  
 
===Example===
 
===Example===
 
{{example
 
{{example
−
|
+
|code=
−
| code=
+
−
#include <iostream>
+
 
#include <clocale>
 
#include <clocale>
 
#include <cstdlib>
 
#include <cstdlib>
 +
 +
 
int main()
 
int main()
 
{
 
{
 
     std::setlocale(LC_ALL, "en_US.utf8");
 
     std::setlocale(LC_ALL, "en_US.utf8");
−
     const char* mbstr = u8"z\u00df\u6c34\U0001d10b"; // or u8"zß水𝄋"
+
−
                         // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9d\x84\x8b";
+
     const char* mbstr = "z\u00df\u6c34\"; // or u8"