4. c16rtomb

最終更新日時:
が更新

履歴 編集

function
<cuchar>

std::c16rtomb(C++11)

namespace std {
  size_t c16rtomb(char* s, char16_t c16, mbstate_t* ps);
}

概要

UTF-16文字 (char16_t) を、マルチバイト文字へ変換する。

c16をマルチバイト文字へ変換し、sが指す配列へ書き込む。書き込まれるバイト数は最大でMB_CUR_MAXである。変換状態はpsが指すオブジェクトに保持されるため、複数のスレッドから安全に使用できる。

サロゲートペアの上位サロゲートを渡した場合、そのコード単位だけでは文字が確定しないため、なにも書き込まれず0が返る。続けて下位サロゲートを渡すと、両者を組み合わせた文字がマルチバイト文字へ変換される。

sがヌルポインタの場合、c16rtomb(buf, u'\0', ps)の呼び出しと等価であり（bufは内部のバッファ）、変換状態を初期状態に戻す動作となる。

戻り値

  • 書き込んだバイト数を返す
  • 上位サロゲートのみを渡すなど、文字が確定しない場合は0を返す
  • c16が有効な文字ではない場合、(size_t)-1を返し、errnoにEILSEQを設定する

備考

  • psがヌルポインタの場合、処理系が用意した内部のオブジェクトが変換状態として使用される
  • 書き込み先の配列は、MB_CUR_MAXバイト以上の大きさをもたなければならない
  • マルチバイト文字への変換は、現在のロケールカテゴリLC_CTYPEに依存する

例

基本的な使い方

#include <cuchar>
#include <clocale>
#include <cstdlib>
#include <cstdio>

int main()
{
  std::setlocale(LC_ALL, "C.UTF-8");

  char buffer[MB_CUR_MAX];
  std::mbstate_t state{};

  // 'あ' はUTF-8では3バイトへ変換される
  std::size_t n = std::c16rtomb(buffer, 0x3042, &state);

  std::printf("%zu\n", n);
}

出力例

3

サロゲートペアを変換する

#include <cuchar>
#include <clocale>
#include <cstdlib>
#include <cstdio>

int main()
{
  std::setlocale(LC_ALL, "C.UTF-8");

  char buffer[MB_CUR_MAX];
  std::mbstate_t state{};

  // 上位サロゲートだけでは文字が確定しないため、なにも書き込まれず0が返る
  std::size_t n1 = std::c16rtomb(buffer, 0xD83D, &state);

  // 下位サロゲートを渡すと、😀 (U+1F600) がUTF-8の4バイトへ変換される
  std::size_t n2 = std::c16rtomb(buffer, 0xDE00, &state);

  std::printf("%zu %zu\n", n1, n2);
}

出力例

0 4

バージョン

言語

  • C++11

関連項目

参照