Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | string‎ | multibyte
m (r2.7.3) (Robot: Adding de, es, fr, it, ja, pt, ru, zh)
m (Shorten template names. Use {{lc}} where appropriate.)
Line 21: Line 21:
  
 
===Parameters===
 
===Parameters===
−
{{param list begin}}
+
{{par begin}}
−
{{param list item | pc16 | pointer to the location where the resulting 16-bit character will be written}}
+
{{par | pc16 | pointer to the location where the resulting 16-bit character will be written}}
−
{{param list item | s | pointer to the multibyte character string used as input}}
+
{{par | s | pointer to the multibyte character string used as input}}
−
{{param list item | n | limit on the number of bytes in s that can be examined}}
+
{{par | n | limit on the number of bytes in s that can be examined}}
−
{{param list item | ps | pointer to the conversion state object used when interpreting the multibyte string }}
+
{{par | ps | pointer to the conversion state object used when interpreting the multibyte string }}
−
{{param list end}}
+
{{par end}}
  
 
===Return value===
 
===Return value===
Line 35: Line 35:
 
* {{c|-3}} if the next {{c|char16_t}} from a multi-{{c|char16_t}} character (e.g. a surrogate pair) has now been written to {{c|*pc16}}. No bytes are processed from the input in this case.
 
* {{c|-3}} if the next {{c|char16_t}} from a multi-{{c|char16_t}} character (e.g. a surrogate pair) has now been written to {{c|*pc16}}. No bytes are processed from the input in this case.
 
* {{c|-2}} if the next {{tt|n}} bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to {{c|*pc16}}.
 
* {{c|-2}} if the next {{tt|n}} bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to {{c|*pc16}}.
−
* {{c|-1}} if encoding error occurs. Nothing is written to {{tt|*pc16}}, the value {{c|EILSEQ}} is stored in {{c|errno}} and the value if {{c|*ps}} is unspecified.
+
* {{c|-1}} if encoding error occurs. Nothing is written to {{tt|*pc16}}, the value {{lc|EILSEQ}} is stored in {{lc|errno}} and the value if {{c|*ps}} is unspecified.
  
 
===See also===
 
===See also===
−
{{dcl list begin}}
+
{{dsc begin}}
−
{{dcl list template | cpp/string/multibyte/dcl list c16rtomb}}
+
{{dsc inc | cpp/string/multibyte/dcl list c16rtomb}}
−
{{dcl list template | cpp/locale/codecvt/dcl list do_in | mem=std::codecvt<char16_t, char, std::mbstate_t>}}
+
{{dsc inc | cpp/locale/codecvt/dcl list do_in | mem=std::codecvt<char16_t, char, std::mbstate_t>}}
−
{{dcl list see c | c/string/multibyte/mbrtoc16}}
+
{{dsc see c | c/string/multibyte/mbrtoc16}}
−
{{dcl list end}}
+
{{dsc end}}
  
 
[[de:cpp/string/multibyte/mbrtoc16]]
 
[[de:cpp/string/multibyte/mbrtoc16]]

Revision as of 19:57, 31 May 2013

 
C++
 
Strings library
 
Null-terminated multibyte strings
Wide/multibyte conversions
(C++20)
mbrtoc16
(C++11)
(C++11)    
Types
 
Defined in header <cuchar>
std::size_t mbrtoc16( char16_t* pc16,

                      const char* s,
                      std::size_t n,

                      std::mbstate_t* ps );
 (since C++11)

Converts a narrow multibyte character to 16-bit character representation (typically, UTF-16).

If s is not a null pointer, inspects at most n bytes of the multibyte character string, beginning with the byte pointed to by s to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences). If the function determines that the next multibyte character in s is complete and valid, converts it to the corresponding 16-bit character and stores it in *pc16 (if pc16 is not null).

If the multibyte character in *s corresponds to a multi-char16_t sequence (e.g. a surrogate pair in UTF-16), then after the first call to this function, *ps is updated in such a way that the next call to mbrtoc16 will write out the additional char16_t, without considering *s.

If s is a null pointer, the values of n and pc16 are ignored and the call is equivalent to std::mbrtoc16(NULL, "", 1, ps).

If the wide character produced is the null character, the conversion state *ps represents the initial shift state.

If the macro __STDC_UTF_16__ is defined, the 16-bit encoding used by this function is UTF-16, otherwise it is implementation-defined.

Parameters

pc16 - pointer to the location where the resulting 16-bit character will be written
s - pointer to the multibyte character string used as input
n - limit on the number of bytes in s that can be examined
ps - pointer to the conversion state object used when interpreting the multibyte string

Return value

The first of the following that applies:

  • ​0​ if the character converted from s (and stored in *pc16 if non-null) was the null character
  • the number of bytes [1...n] of the multibyte character successfully converted from s
  • -3 if the next char16_t from a multi-char16_t character (e.g. a surrogate pair) has now been written to *pc16. No bytes are processed from the input in this case.
  • -2 if the next n bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to *pc16.
  • -1 if encoding error occurs. Nothing is written to *pc16, the value EILSEQ is stored in errno and the value if *ps is unspecified.

See also

Template:cpp/string/multibyte/dcl list c16rtombTemplate:cpp/locale/codecvt/dcl list do in
C documentation for mbrtoc16
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/multibyte/mbrtoc16&oldid=51274"