What does `` provide, and where is it documented?

Question

The new C++11 standard mentions a header <cuchar>, presumably in analogy to C99's <uchar.h>.

Now, we know that C++11 brings new character types and literals that are specifically designed for UTF16 and UTF32, but I didn't think the language would actually contain functions to convert the (system-dependent) narrow multibyte encoding to one of the Unicode encodings. However, I just came across the header synopsis for <cuchar> that mentions functions mbrtoc16/c16rtombr and mbrtoc32/c32rtombr that seem to do just that.

Unfortunately, the standard says nothing about those functions beyond the header synopsis. Where are those functions defined, what do they really do and where can I read more about them? Does this mean that one can use proper Unicode entirely with standard C++ now, without the need for any extra libraries?

@R.MartinhoFernandes: I don't have that - do you have any details? Even just web references? — Kerrek SB, Sep 26 '11 at 23:46
oops, I can't seem to find those in the latest C99 draft (N1124). In fact, I can't even find any mention `uchar.h`. — R. Martinho Fernandes, Sep 26 '11 at 23:49
@R.MartinhoFernandes: The latest C99 draft is [N1256](http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf). It has ``, but there's no `'. — Keith Thompson, Sep 27 '11 at 00:29
@KeithThompson Right, thanks. I didn't know there was a C99 TC3. Though being a TC, it wouldn't add a whole new header :) — R. Martinho Fernandes, Sep 27 '11 at 00:38

R. Martinho Fernandes · Accepted Answer · 2011-09-27T00:07:29.843

6

These were described in a WG21 paper from 2005 but the description is not present in the final standard. They are documented in ISO/IEC 19769:2004 (Extensions for the programming language C to support new character data types) (draft), which the C++11 standard refers to.

The text is too long to post here, but these are the signatures:

size_t mbrtoc16(char16_t * pc16, const char * s, size_t n, mbstate_t * ps);
size_t c16rtomb(char * s, char16_t c16, mbstate _t * ps);
size_t mbrtoc32(char32_t * pc32, const char * s, size_t n, mbstate_t * ps);
size_t c32rtomb(char * s, char32_t c32, mbstate_t * ps);

The functions convert between multibyte characters and UTF-16 or UTF-32 characters, respectively, similar to mbrtowc. There are no non-reentrant versions, and honestly, who needs them?

edited Sep 27 '11 at 00:07

answered Sep 26 '11 at 23:52

R. Martinho Fernandes

228,013
71
433
510

Do you have it in the FDIS (table 79)? – Kerrek SB Sep 26 '11 at 23:53
@KerrekSB The FDIS only includes the table with the names. Edit: Found them! – R. Martinho Fernandes Sep 26 '11 at 23:57
Thanks for the update -- any documentation on what they're supposed to do, and how they're operated? Is it exactly like `mbsrtowcs`? (Interesting by the way that there's only the reentrant version.) *Edit:* Oh, no, wait, it's like `mbrtowc`. Not strings, just single characters. – Kerrek SB Sep 26 '11 at 23:59
@KerrekSB Yes, seems like `mbrtowc`. – R. Martinho Fernandes Sep 27 '11 at 00:03

score 1 · Answer 2 · answered Sep 27 '11 at 00:02

1

Probably the best documentation of which I'm aware is in n1326, the proposal to add TR19769 to the C standard library [Edit: though looking at it, the N1010 that R. Martinho Fernandes cited seems to have pretty much the same].

answered Sep 27 '11 at 00:02

Jerry Coffin

476,176
80
629
1,111

Thanks... though now I feel like I understand *less*. What of those macros? Do they affect how the compiler translates encodings? Hmmmm.... – Kerrek SB Sep 27 '11 at 00:07
@R.MartinhoFernandes: Not according to the linked document. It says that **if** the macros are defined, then `char32_t` is UTF32-encoded; *otherwise* the encoding is implementation-defined. Does that mean that if I set the macro, the compiler has to produce UTF32, but otherwise it doesn't? – Kerrek SB Sep 27 '11 at 00:13
2

@KerrekSB Seems like the C++11 standard requires character and string literals of `char16_t` and `char32_t` to be UTF-16 and UTF-32, so in C++ the macros should be defined, I guess. – R. Martinho Fernandes Sep 27 '11 at 00:21

What does `` provide, and where is it documented?

2 Answers2

Linked