mbrtowc() - マルチバイト文字のワイド文字への変換

標準

標準/拡張機能	C/C++	依存項目
ISO C 改訂 C99 Single UNIX Specification、バージョン 3	両方

形式

非 XPG4

#include <wchar.h>

size_t mbrtowc(wchar_t * __restrict__pwc, const char * __restrict__s, 
               size_t n, mbstate_t * __restrict__ps);

XPG4

#define _XOPEN_SOURCE
#define _MSE_PROTOS
#include <wchar.h>

size_t mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

機能説明

mbrtowc() 関数は mbrtowc(NULL,"",1,ps) と同じです。

s が NULL ポインターである場合、mbrtowc() 関数は n と pwc を無視し、ps が示すシフト状態を初期シフト状態にリセットします。

s が NULL ポインターでない場合、mbrtowc() は、s が示すバイトから始まる最大 n バイトと ps が示すシフト状態を検査して、有効なマルチバイト文字を完成するのに必要なバイト数を判別します。

マルチバイト文字が完了すると、mbrtowc() は、対応するワイド文字の値を判別し、pwc が NULL ポインターでない限り、pwc が示すオブジェクトにその値を保管します。最後に、mbrtowc() は ps が示すオブジェクトに実際のシフト状態を保管します。ps が NULL ポインターである場合、mbrtowc() は独自の内部オブジェクトを使用してシフト状態をトラッキングします。

mbrtowc() は mbtowc() の再始動可能バージョンです。つまり、シフト状態情報は引数の 1 つとして渡され、終了時に更新されます。mbrtowc() を使用すると、シフト状態情報を保持している場合に、あるマルチバイト・ストリングから別のマルチバイト・ストリングに切り替えることができます。

このワイド文字関数の動作は、現行ロケールの LC_CTYPE カテゴリーの影響を受けます。カテゴリーを変更すると、未定義の結果になることがあります。

XPG4 の特殊な動作

プログラム・ソース・ファイル内の wchar ヘッダーをインクルードするステートメントより前に、XPG4 の動作を指定してフィーチャー・テスト・マクロを定義した場合には、_MSE_PROTOS フィーチャー・テスト・マクロも定義して、プログラムのコンパイル時に使用可能な wchar ヘッダーの mbrtowc() 関数の宣言を行う必要があります。XPG4 と他のフィーチャー・テスト・マクロのリストについては、表 1 を参照してください。

戻り値

s が NULL ポインターである場合、mbrtowc() は、シフト状態を初期シフト状態にリセットして、0 を戻します。

s が NULL ポインターでない場合、mbrtowc() は、次のいずれかの値を、ここに示す順で戻します。

0: 続く n 以下のバイト数によって、NULL ワイド文字に対応する有効なマルチバイト文字が完成する場合。
正整数: 次の n または数バイトが有効なマルチバイト文字を完成する場合。つまり、戻り値はマルチバイト文字を完成するバイト数となります。
-2: 次の n バイトが不完全な (ただし有効である可能性もある) マルチバイト文字を形成し、すべての n バイトが処理された場合。n の値が MB_CUR_MAX マクロの値よりも小さい場合、これが起こるかどうかは指定されていません。
注: -2 の値が戻され、かつ n が MB_CUR_MAX 以上である場合は、そのストリングに冗長のシフトアウトおよびシフトイン文字が含まれます。マルチバイト・ストリングの処理を継続するには、n の値でポインターを増分し、mbrtowc() 関数を呼び出します。
-1: エンコード・エラーが発生した場合 (次の n またはそれよりも少ないバイト数でさえ、完全で有効なマルチバイト文字の作成に使用できないとき)。EILSEQ マクロの値は errno に保管されるが、変換状態は未変更のままになります。

例

CELEBM04

⁄* CELEBM04 *⁄                                   
#include <stdio.h>                                                              
#include <stdlib.h>                                                             
#include <wchar.h>                                                              
                                                                                
int main(void)                                                                  
{                                                                               
   wchar_t   wc;                                                                
   char      mbs[5] = "a";    ⁄* string containing the multibyte char *⁄        
   mbstate_t ss     = 0;      ⁄* set shift state to the initial state *⁄        
   int       length;                                                            
                                                                                
   ⁄* Determine the length of the multibyte character pointed to by   *⁄        
   ⁄* mbs.  Store the multibyte character in the wchar_t object       *⁄        
   ⁄* called wc.                                                      *⁄        
                                                                                
   length = mbrtowc(&wc, mbs, MB_CUR_MAX, &ss);                                 
                                                                                
   printf("    length: %d ¥n", length);                                         
   printf("        wc:'%lc'¥n", wc);                                            
   printf("       mbs:¥"%s¥"¥n", mbs);                                          
   printf("MB_CUR_MAX: %d ¥n", MB_CUR_MAX);                                     
   printf("        ss: %d ¥n", ss);                                             
}

mbrtowc() - マルチバイト文字のワイド文字への変換

標準

形式

機能説明

戻り値

例

関連情報