utfcpp
Release 4.0.6
C ++開発者は、Unicodeエンコードされた文字列を処理する簡単でポータブルな方法をまだ見逃しています。元のC ++標準（C ++ 98またはC ++ 03として知られている）は、Unicode不可知論です。標準の後期版ではいくつかの進捗がありましたが、標準施設のみを使用してUnicodeで作業することはまだ困難です。
UTF-8エンコードされた文字列を処理するために、小さなC ++ 98互換性のあるジェネリックライブラリを思いつきました。 STLアルゴリズムとイテレーターを使用していた人にとっては、使用するのが簡単で自然なはずです。コードは、あらゆる目的で自由に利用できます - ライセンスをチェックしてください。この図書館は、2006年のコマーシャルプロジェクトとオープンソースプロジェクトの両方で最初のリリース以来、多くの使用を行い、安定して有用であることが証明されています。
これはヘッダーのみのライブラリであり、それを展開するサポートされている方法は次のとおりです。
cmakelist.txtファイルはもともとテスト目的でのみ作成されていましたが、残念ながら、インストールターゲットを追加した寄付を受け入れました。これは、UTFCPPライブラリをインストールするサポートされている方法ではなく、将来のリリースでcmakelist.txtを削除することを検討しています。
ライブラリの使用を説明するために、UTF-8エンコードされたテキストを含むファイルを開き、線ごとに読み取り、各行を無効なUTF-8バイトシーケンスのチェックし、UTF-16エンコードに変換してUTF-8に戻し、戻って戻ってUTF-8に戻ります。
# include < fstream >
# include < iostream >
# include < string >
# include < vector >
# include " utf8.h "
using namespace std ;
int main ( int argc, char ** argv)
{
if (argc != 2 ) {
cout << " n Usage: docsample filename n " ;
return 0 ;
}
const char * test_file_path = argv[ 1 ];
// Open the test file (must be UTF-8 encoded)
ifstream fs8 (test_file_path);
if (!fs8. is_open ()) {
cout << " Could not open " << test_file_path << endl;
return 0 ;
}
unsigned line_count = 1 ;
string line;
// Play with all the lines in the file
while ( getline (fs8, line)) {
// check for invalid utf-8 (for a simple yes/no check, there is also utf8::is_valid function)
# if __cplusplus >= 201103L // C++ 11 or later
auto end_it = utf8::find_invalid (line. begin (), line. end ());
# else
string::iterator end_it = utf8::find_invalid (line. begin (), line. end ());
# endif // C++ 11
if (end_it != line. end ()) {
cout << " Invalid UTF-8 encoding detected at line " << line_count << " n " ;
cout << " This part is fine: " << string (line. begin (), end_it) << " n " ;
}
// Get the line length (at least for the valid part)
int length = utf8::distance (line. begin (), end_it);
cout << " Length of line " << line_count << " is " << length << " n " ;
// Convert it to utf-16
# if __cplusplus >= 201103L // C++ 11 or later
u16string utf16line = utf8::utf8to16 (line);
# else
vector< unsigned short > utf16line;
utf8::utf8to16 (line. begin (), end_it, back_inserter (utf16line));
# endif // C++ 11
// And back to utf-8;
# if __cplusplus >= 201103L // C++ 11 or later
string utf8line = utf8::utf16to8 (utf16line);
# else
string utf8line;
utf8::utf16to8 (utf16line. begin (), utf16line. end (), back_inserter (utf8line));
# endif // C++ 11
// Confirm that the conversion went OK:
if (utf8line != string (line. begin (), end_it))
cout << " Error in UTF-16 conversion at line: " << line_count << " n " ;
line_count++;
}
return 0 ;
}前のコードサンプルでは、各ラインについて、 find_invalidを使用して無効なUTF-8シーケンスの検出を実行しました。各ラインの文字の数（より正確には - 行の終了を含むユニコードコードポイントの数、さらには存在する場合、bomの数）はutf8::distanceを使用して決定されました。最後に、各ラインをutf8to16を使用してUTF-16エンコードに変換し、 utf16to8を使用してUTF-8に戻りました。
古いコンパイラの使用パターンの使用パターンに注意してください。たとえば、これは、UTF-8エンコードされた文字列をPre-C ++ 11コンパイラでEncodedの文字列に変換する方法です。
vector< unsigned short > utf16line;
utf8::utf8to16 (line.begin(), end_it, back_inserter(utf16line));よりモダンなコンパイラを使用すると、同じ操作が次のようになります。
u16string utf16line = utf8::utf8to16(line); __cplusplusマクロがC ++ 11以降を指している場合、ライブラリはC ++標準ユニコード文字列を考慮してセマンティクスを移動するAPIを公開します。古いコンパイラを使用すると、もう少し便利な方法で同じ機能を使用することが可能です
__cplusplusマクロを信頼していない場合、またはたとえば、最新のコンパイラを使用してもC ++ 11ヘルパー関数を含めたくない場合は、 utf8.hを含める前にUTF_CPP_CPLUSPLUSマクロを定義し、使用する標準の値を割り当てます - 値は__cplusplusの場合と同じです。これは、最近の標準版を適切にサポートしている場合でも、 __cplusplusマクロを設定する際に保守的なコンパイラーでも役立ちます。MicrosoftのVisual C ++はその一例です。
これは、ファイルのコンテンツがメモリにコンテンツを読み取らずに有効なUTF-8エンコードテキストであるかどうかをチェックする関数です。
bool valid_utf8_file ( const char * file_name)
{
ifstream ifs (file_name);
if (!ifs)
return false ; // even better, throw here
istreambuf_iterator< char > it (ifs. rdbuf ());
istreambuf_iterator< char > eos;
return utf8::is_valid (it, eos);
}関数utf8::is_valid()入力Iteratorsで動作するため、 istreambuf_iteratorをitことができ、最初にメモリにロードせずにファイルのコンテンツを直接読み取ることができました。
入力イテレーター引数を取得する他の関数は、同様の方法で使用できることに注意してください。たとえば、UTF-8エンコードされたテキストファイルのコンテンツを読み、テキストをUTF-16に変換するには、次のようなことを行います。
utf8::utf8to16 (it, eos, back_inserter(u16string));「おそらく」にUTF-8エンコードされたテキストが含まれており、無効なUTF-8シーケンスを置換文字に置き換えるテキストがある場合、次の関数のようなものを使用することができます。
void fix_utf8_string (std::string& str)
{
std::string temp;
utf8::replace_invalid (str. begin (), str. end (), back_inserter (temp));
str = temp;
}この関数は、無効なUTF-8シーケンスをユニコード置換文字に置き換えます。発信者が独自の交換キャラクターを提供できるようにする過負荷機能があります。
図書館は次のように設計されていました。
代替案と比較については、次の記事をお勧めします。JeanheydMeneideによる、CおよびC ++エンコードAPI（錆を伴う）の素晴らしく恐ろしい世界をお勧めします。記事では、このライブラリは以下と比較されます。
この記事では、API設計の品質に関する著者の見解だけでなく、いくつかの速度ベンチマークも提示します。
バージョン1.0以降で利用できます。
32ビットコードポイントをオクテットのUTF-8シーケンスとしてエンコードし、シーケンスをUTF-8文字列に追加します。
template < typename octet_iterator>
octet_iterator append ( utfchar32_t cp, octet_iterator result); octet_iterator ：出力イテレーター。
cp ：シーケンスに追加するコードポイントを表す32ビット整数。
result ：コードポイントを追加するシーケンス内の場所への出力イテレータ。
戻り値：新しく追加されたシーケンスの後に場所を指しているイテレーター。
使用例：
unsigned char u[ 5 ] = { 0 , 0 , 0 , 0 , 0 };
unsigned char * end = append( 0x0448 , u);
assert (u[ 0 ] == 0xd1 && u[ 1 ] == 0x88 && u[ 2 ] == 0 && u[ 3 ] == 0 && u[ 4 ] == 0 ); appendメモリを割り当てないことに注意してください - 操作に十分なメモリが割り当てられていることを確認するのは、発信者の負担です。物事をより面白くするために、 appendシーケンスに1〜4オクテットのどこかを追加できます。実際には、ほとんどの場合、 std::back_inserter使用して、必要なメモリが割り当てられるようにしたいと思うでしょう。
無効なコードポイントの場合、 utf8::invalid_code_point例外がスローされます。
バージョン3.0以降で利用できます。 4.0の前に、C ++ 11コンパイラが必要でした。要件は4.0で解除されます。
32ビットコードポイントをオクテットのUTF-8シーケンスとしてエンコードし、シーケンスをUTF-8文字列に追加します。
void append ( utfchar32_t cp, std::string& s); cp ：文字列に追加するコードポイント。
s ：UTF-8エンコードされた文字列にコードポイントを追加します。
使用例：
std::string u;
append ( 0x0448 , u);
assert (u[ 0 ] == char ( 0xd1 ) && u[1] == char( 0x88 ) && u.length() == 2);無効なコードポイントの場合、 utf8::invalid_code_point例外がスローされます。
バージョン4.0以降で利用できます。
32ビットコードポイントをUTF-16シーケンスの単語としてエンコードし、シーケンスをUTF-16文字列に追加します。
template < typename word_iterator>
word_iterator append16 ( utfchar32_t cp, word_iterator result); word_iterator ：出力イテレーター。
cp ：シーケンスに追加するコードポイントを表す32ビット整数。
result ：コードポイントを追加するシーケンス内の場所への出力イテレータ。
戻り値：新しく追加されたシーケンスの後に場所を指しているイテレーター。
使用例：
unsigned short u[ 2 ] = { 0 , 0 };
unsigned short * end = append16( 0x0448 , u);
assert (u[ 0 ] == 0x0448 && u[ 1 ] == 0 ); append16メモリを割り当てないことに注意してください - 操作に十分なメモリが割り当てられていることを確認するのは、発信者の負担です。物事をより面白くするために、 append16シーケンスに1つまたは2つの単語を追加できます。実際には、ほとんどの場合、 std::back_inserter使用して、必要なメモリが割り当てられるようにしたいと思うでしょう。
無効なコードポイントの場合、 utf8::invalid_code_point例外がスローされます。
バージョン4.0以降で利用できます。 C ++ 11準拠コンパイラが必要です。
32ビットコードポイントをUTF-16シーケンスの単語としてエンコードし、シーケンスをUTF-16文字列に追加します。
void append ( utfchar32_t cp, std::u16string& s); cp ：文字列に追加するコードポイント。
s ：UTF-16エンコードされた文字列をエンコードして、コードポイントを追加します。
使用例：
std::u16string u;
append ( 0x0448 , u);
assert (u[ 0 ] == 0x0448 && u.length() == 1);無効なコードポイントの場合、 utf8::invalid_code_point例外がスローされます。
バージョン1.0以降で利用できます。
UTF-8シーケンスの開始までのイテレーターを考えると、コードポイントを返し、イテレーターを次の位置に移動します。
template < typename octet_iterator>
utfchar32_t next (octet_iterator& it, octet_iterator end); octet_iterator ：入力イテレーター。
it ：UTF-8エンコードコードポイントの開始を指すイテレーターへの参照。関数が戻った後、次のコードポイントの開始をポイントするように増加します。
end ：処理されるUTF-8シーケンスの終了。コードポイントの抽出中にendとitなると、 utf8::not_enough_room例外がスローされます。
返品値：処理されたUTF-8コードポイントの32ビット表現。
使用例：
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = next(w, twochars + 6 );
assert (cp == 0x65e5 );
assert (w == twochars + 3 );この関数は通常、UTF-8エンコードされた文字列を介して反復するために使用されます。
無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。
バージョン4.0以降で利用できます。
UTF-16シーケンスの開始までのイテレーターを考えると、コードポイントを返し、イテレーターを次の位置に移動します。
template < typename word_iterator>
utfchar32_t next16 (word_iterator& it, word_iterator end); word_iterator ：入力イテレーター。
it ：UTF-16エンコードされたコードポイントの開始を指すイテレーターへの参照。関数が戻った後、次のコードポイントの開始をポイントするように増加します。
end ：処理されるUTF-16シーケンスの終了。コードポイントの抽出中にendとitなると、 utf8::not_enough_room例外がスローされます。
返品値：処理されたUTF-16コードポイントの32ビット表現。
使用例：
const unsigned short u[ 3 ] = { 0x65e5 , 0xd800 , 0xdf46 };
const unsigned short * w = u;
int cp = next16(w, w + 3 );
assert (cp, 0x65e5 );
assert (w, u + 1 );この関数は通常、UTF-16エンコードされた文字列を介して反復するために使用されます。
無効なUTF-16シーケンスの場合、 utf8::invalid_utf8例外がスローされます。
バージョン2.1以降で利用可能です。
UTF-8シーケンスの開始までのイテレーターを考えると、イテレーターの値を変更せずに、次のシーケンスのコードポイントを返します。
template < typename octet_iterator>
utfchar32_t peek_next (octet_iterator it, octet_iterator end); octet_iterator ：入力イテレーター。
it ：UTF-8エンコードされたコードポイントの開始を指しているイテレーター。
end ：処理されるUTF-8シーケンスの終了。コードポイントの抽出中にendとitなると、 utf8::not_enough_room例外がスローされます。
返品値：処理されたUTF-8コードポイントの32ビット表現。
使用例：
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = peek_next(w, twochars + 6 );
assert (cp == 0x65e5 );
assert (w == twochars);無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。
バージョン1.02以降で利用可能です。
UTF-8シーケンスのオクテットを指すイテレーターへの参照を考えると、以前のUTF-8エンコードコードポイントの開始にヒットし、コードポイントの32ビット表現を返すまでイテレーターが減少します。
template < typename octet_iterator>
utfchar32_t prior (octet_iterator& it, octet_iterator start); octet_iterator ：双方向のイテレーター。
it ：UTF-8エンコードされた文字列内のオクテットを指す基準。関数が戻った後、前のコードポイントの開始をポイントするように減少します。
start ：コードポイントの開始の検索が実行されるシーケンスの先頭へのイテレーター。これは、UTF-8のリードオクテットを検索する際に、文字列の始まりを渡すのを防ぐための安全尺度です。
戻り値：前のコードポイントの32ビット表現。
使用例：
char * twochars = " xe6x97xa5xd1x88 " ;
unsigned char * w = twochars + 3 ;
int cp = prior (w, twochars);
assert (cp == 0x65e5 );
assert (w == twochars);この関数には2つの目的があります。1つは、UTF-8エンコードされた文字列を介して2つの反復逆方向です。 utf8::nextより速いので、代わりに前方に反復する方が良いアイデアであることに注意してください。 2番目の目的は、文字列内にランダムな位置がある場合、UTF-8シーケンスの始まりを見つけることです。その場合utf8::prior 、いくつかのシナリオで無効なUTF-8シーケンスを検出しない場合があります。たとえば、余分なトレイルオクテットがある場合、それはそれらをスキップするだけです。
通常、コードポイントの始まりをit 、 start文字列の始まりを指して、後退しすぎないようにします。リードUTF-8オクテットを指すまでitし、その後、そのオクテットが32ビット表現にデコードされて戻ってくるUTF-8シーケンスが返されます。
UTF-8のリードOctetがヒットする前にstartに到達するか、無効なUTF-8シーケンスがリードOctetによって開始された場合、 invalid_utf8例外がスローされます。
start it等しい場合、 not_enough_room例外がスローされます。
バージョン1.0以降で利用できます。
UTF-8シーケンス内の指定されたコードポイントの数によってイテレーターを進めます。
template < typename octet_iterator, typename distance_type>
void advance (octet_iterator& it, distance_type n, octet_iterator end); octet_iterator ：入力イテレーター。
distance_type ： octet_iteratorの違いタイプにコンバーチブルにコンバーチブル。
it ：UTF-8エンコードコードポイントの開始を指すイテレーターへの参照。関数が戻った後、コードポイントに次のn番目のポイントをポイントするように増加します。
n ：コードポイント数は高度にする必要がありit 。負の値は、減少を意味します。
end ：処理されるUTF-8シーケンスの制限。 nが陽性であり、コードポイントの抽出中にendとitなると、 utf8::not_enough_room例外がスローされます。 nが負で、UTF-8シーケンスのTAトレイルバイトを指してit間にendにitと、 utf8::invalid_code_point例外がスローされます。
使用例：
char * twochars = " xe6x97xa5xd1x88 " ;
unsigned char * w = twochars;
advance (w, 2 , twochars + 6 );
assert (w == twochars + 5 );
advance (w, - 2 , twochars);
assert (w == twochars);無効なコードポイントの場合、 utf8::invalid_code_point例外がスローされます。
バージョン1.0以降で利用できます。
2つのUTF-8エンコードされたコードポイントへのイテレーターがシーケンスで与えられると、それらの間のコードポイントの数を返します。
template < typename octet_iterator>
typename std::iterator_traits<octet_iterator>::difference_type distance (octet_iterator first, octet_iterator last); octet_iterator ：入力イテレーター。
first ：UTF-8エンコードされたコードポイントの始まりへのイテレーター。
last ：長さを決定しようとしているシーケンスの最後のUTF-8エンコードされたコードポイントの「ポストエンド」へのイテレーター。それは新しいコードポイントの始まりであるか、そうでない場合があります。
コードポイント内の反復器間の距離を返す値。
使用例：
char * twochars = " xe6x97xa5xd1x88 " ;
size_t dist = utf8::distance(twochars, twochars + 5 );
assert (dist == 2 );この関数は、UTF-8エンコードされた文字列の長さ（コードポイント）を見つけるために使用されます。たとえば長さではなく、距離と呼ばれる理由は、主に開発者が使用されるためであるため、長さがO（1）関数であるためです。 UTF-8文字列の長さを計算することは線形動作であり、 std::distanceアルゴリズムの後にモデル化する方が良いように見えました。
無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。 last UTF-8シーケンスの過去を指していない場合、 utf8::not_enough_room例外がスローされます。
バージョン1.0以降で利用できます。
UTF-16エンコードされた文字列をUTF-8に変換します。
template < typename u16bit_iterator, typename octet_iterator>
octet_iterator utf16to8 (u16bit_iterator start, u16bit_iterator end, octet_iterator result); u16bit_iterator ：入力イテレーター。
octet_iterator ：出力イテレーター。
start ：UTF-16エンコードされた文字列の先頭を指して、変換します。
end ：UTF-16エンコードされた文字列のパスエンドを指して、変換します。
result ：変換の結果を追加するUTF-8文字列の場所への出力イテレータ。
返品値：Appled UTF-8文字列を後にした場所を指しているイテレーター。
使用例：
unsigned short utf16string[] = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
vector< unsigned char > utf8result;
utf16to8 (utf16string, utf16string + 5 , back_inserter(utf8result));
assert (utf8result.size() == 10); UTF-16シーケンスが無効な場合、 utf8::invalid_utf16例外がスローされます。
バージョン3.0以降で利用できます。 C ++ 11準拠コンパイラが必要です。
UTF-16エンコードされた文字列をUTF-8に変換します。
std::string utf16to8 ( const std::u16string& s); s ：UTF-16エンコードされた文字列。戻り値：UTF-8エンコードされた文字列。
使用例：
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
string u = utf16to8(utf16string);
assert (u.size() == 10); UTF-16シーケンスが無効な場合、 utf8::invalid_utf16例外がスローされます。
バージョン3.2以降で利用可能です。 C ++ 17準拠コンパイラが必要です。
UTF-16エンコードされた文字列をUTF-8に変換します。
std::string utf16to8 (std::u16string_view s); s ：UTF-16エンコードされた文字列。戻り値：UTF-8エンコードされた文字列。
使用例：
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u16string_view utf16stringview (u16string);
string u = utf16to8(utf16string);
assert (u.size() == 10); UTF-16シーケンスが無効な場合、 utf8::invalid_utf16例外がスローされます。
バージョン4.0以降で利用できます。 C ++ 20準拠コンパイラが必要です。
UTF-16エンコードされた文字列をUTF-8に変換します。
std::u8string utf16tou8 ( const std::u16string& s); s ：UTF-16エンコードされた文字列。戻り値：UTF-8エンコードされた文字列。
使用例：
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u8string u = utf16tou8(utf16string);
assert (u.size() == 10); UTF-16シーケンスが無効な場合、 utf8::invalid_utf16例外がスローされます。
バージョン4.0以降で利用できます。 C ++ 20準拠コンパイラが必要です。
UTF-16エンコードされた文字列をUTF-8に変換します。
std::u8string utf16tou8 ( const std::u16string_view& s); s ：UTF-16エンコードされた文字列。戻り値：UTF-8エンコードされた文字列。
使用例：
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u16string_view utf16stringview (u16string);
u8string u = utf16tou8(utf16string);
assert (u.size() == 10); UTF-16シーケンスが無効な場合、 utf8::invalid_utf16例外がスローされます。
バージョン1.0以降で利用できます。
UTF-8エンコードされた文字列をUTF-16に変換します
template < typename u16bit_iterator, typename octet_iterator>
u16bit_iterator utf8to16 (octet_iterator start, octet_iterator end, u16bit_iterator result); octet_iterator ：入力イテレーター。
u16bit_iterator ：出力イテレーター。
start ：UTF-8エンコードされた文字列の先頭を指して、変換します。 end ：UTF-8エンコードされた文字列のパスエンドを指して、変換するイテレーター。
result ：変換の結果を追加するUTF-16文字列の場所への出力イテレータ。
返品値：Appled UTF-16 Stringを後にした場所を指しているイテレーター。
使用例：
char utf8_with_surrogates[] = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
vector < unsigned short > utf16result;
utf8to16 (utf8_with_surrogates, utf8_with_surrogates + 9 , back_inserter(utf16result));
assert (utf16result.size() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e );無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。 end UTF-8シーケンスの過去を指していない場合、 utf8::not_enough_room例外がスローされます。
バージョン3.0以降で利用できます。 C ++ 11準拠コンパイラが必要です。
UTF-8エンコードされた文字列をUTF-16に変換します。
std::u16string utf8to16 ( const std::string& s); s ：変換するためにUTF-8エンコードされた文字列。
戻り値：UTF-16エンコードされた文字列
使用例：
string utf8_with_surrogates = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
u16string utf16result = utf8to16(utf8_with_surrogates);
assert (utf16result.length() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e );無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。
バージョン3.2以降で利用可能です。 C ++ 17準拠コンパイラが必要です。
UTF-8エンコードされた文字列をUTF-16に変換します。
std::u16string utf8to16 (std::string_view s); s ：変換するためにUTF-8エンコードされた文字列。
戻り値：UTF-16エンコードされた文字列
使用例：
string_view utf8_with_surrogates = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
u16string utf16result = utf8to16(utf8_with_surrogates);
assert (utf16result.length() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e );無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。
バージョン4.0以降で利用できます。 C ++ 20準拠コンパイラが必要です。
UTF-8エンコードされた文字列をUTF-16に変換します。
std::u16string utf8to16 (std::u8string& s); s ：変換するためにUTF-8エンコードされた文字列。
戻り値：UTF-16エンコードされた文字列
使用例：
std::u8string utf8_with_surrogates = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
std::u16string utf16result = utf8to16(utf8_with_surrogates);
assert (utf16result.length() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e );無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。
バージョン4.0以降で利用できます。 C ++ 20準拠コンパイラが必要です。
UTF-8エンコードされた文字列をUTF-16に変換します。
std::u16string utf8to16 (std::u8string_view& s); s ：変換するためにUTF-8エンコードされた文字列。
戻り値：UTF-16エンコードされた文字列
使用例：
std::u8string utf8_with_surrogates = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
std::u8string_view utf8stringview {utf8_with_surrogates}
std::u16string utf16result = utf8to16(utf8stringview);
assert (utf16result.length() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e );無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。
バージョン1.0以降で利用できます。
UTF-32エンコードされた文字列をUTF-8に変換します。
template < typename octet_iterator, typename u32bit_iterator>
octet_iterator utf32to8 (u32bit_iterator start, u32bit_iterator end, octet_iterator result); octet_iterator ：出力イテレーター。
u32bit_iterator ：入力イテレーター。
start ：UTF-32エンコードされた文字列の先頭を指して、変換します。
end ：UTF-32エンコードされた文字列のパスエンドを指すイテレーターは、変換します。
result ：変換の結果を追加するUTF-8文字列の場所への出力イテレータ。
返品値：Appled UTF-8文字列を後にした場所を指しているイテレーター。
使用例：
int utf32string[] = { 0x448 , 0x65E5 , 0x10346 , 0 };
vector< unsigned char > utf8result;
utf32to8 (utf32string, utf32string + 3 , back_inserter(utf8result));
assert (utf8result.size() == 9);無効なUTF-32文字列の場合、 utf8::invalid_code_point例外がスローされます。
バージョン3.0以降で利用できます。 C ++ 11準拠コンパイラが必要です。
UTF-32エンコードされた文字列をUTF-8に変換します。
std::string utf32to8 ( const std::u32string& s); s ：UTF-32エンコードされた文字列。
戻り値：UTF-8エンコードされた文字列。
使用例：
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9);無効なUTF-32文字列の場合、 utf8::invalid_code_point例外がスローされます。
バージョン4.0以降で利用できます。 C ++ 20準拠コンパイラが必要です。
UTF-32エンコードされた文字列をUTF-8に変換します。
std::u8string utf32to8 ( const std::u32string& s); s ：UTF-32エンコードされた文字列。
戻り値：UTF-8エンコードされた文字列。
使用例：
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u8string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9);無効なUTF-32文字列の場合、 utf8::invalid_code_point例外がスローされます。
バージョン4.0以降で利用できます。 C ++ 20準拠コンパイラが必要です。
UTF-32エンコードされた文字列をUTF-8に変換します。
std::u8string utf32to8 ( const std::u32string_view& s); s ：UTF-32エンコードされた文字列。
戻り値：UTF-8エンコードされた文字列。
使用例：
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u32string_view utf32stringview (utf32string);
u8string utf8result = utf32to8(utf32stringview);
assert (utf8result.size() == 9);無効なUTF-32文字列の場合、 utf8::invalid_code_point例外がスローされます。
バージョン3.0以降で利用できます。 C ++ 11準拠コンパイラが必要です。
UTF-32エンコードされた文字列をUTF-8に変換します。
std::string utf32to8 ( const std::u32string& s); s ：UTF-32エンコードされた文字列。
戻り値：UTF-8エンコードされた文字列。
使用例：
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9);無効なUTF-32文字列の場合、 utf8::invalid_code_point例外がスローされます。
バージョン3.2以降で利用可能です。 C ++ 17準拠コンパイラが必要です。
UTF-32エンコードされた文字列をUTF-8に変換します。
std::string utf32to8 (std::u32string_view s); s ：UTF-32エンコードされた文字列。
戻り値：UTF-8エンコードされた文字列。
使用例：
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u32string_view utf32stringview (utf32string);
string utf8result = utf32to8(utf32stringview);
assert (utf8result.size() == 9);無効なUTF-32文字列の場合、 utf8::invalid_code_point例外がスローされます。
バージョン1.0以降で利用できます。
UTF-8エンコードされた文字列をUTF-32に変換します。
template < typename octet_iterator, typename u32bit_iterator>
u32bit_iterator utf8to32 (octet_iterator start, octet_iterator end, u32bit_iterator result); octet_iterator ：入力イテレーター。
u32bit_iterator ：出力イテレーター。
start ：UTF-8エンコードされた文字列の先頭を指して、変換します。
end ：UTF-8エンコードされた文字列のパスエンドを指して、変換するイテレーター。
result ：変換の結果を追加するUTF-32文字列の場所への出力イテレータ。
返品値：Appled UTF-32文字列を後にした場所を指しているイテレーター。
使用例：
char * twochars = " xe6x97xa5xd1x88 " ;
vector< int > utf32result;
utf8to32 (twochars, twochars + 5 , back_inserter(utf32result));
assert (utf32result.size() == 2);無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。 end UTF-8シーケンスの過去を指していない場合、 utf8::not_enough_room例外がスローされます。
バージョン4.0以降で利用できます。 C ++ 20準拠コンパイラが必要です。
UTF-8エンコードされた文字列をUTF-32に変換します。
std::u32string utf8to32 ( const std::u8string& s); s ：UTF-8エンコード文字列。戻り値：UTF-32エンコードされた文字列。
使用例：
const std::u8string* twochars = u8" xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2);無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。
バージョン4.0以降で利用できます。 C ++ 20準拠コンパイラが必要です。
UTF-8エンコードされた文字列をUTF-32に変換します。
std::u32string utf8to32 ( const std::u8string_view& s); s ：UTF-8エンコード文字列。戻り値：UTF-32エンコードされた文字列。
使用例：
const u8string* twochars = u8" xe6x97xa5xd1x88 " ;
const u8string_view stringview{twochars};
u32string utf32result = utf8to32(stringview);
assert (utf32result.size() == 2);無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。
バージョン3.0以降で利用できます。 C ++ 11準拠コンパイラが必要です。
UTF-8エンコードされた文字列をUTF-32に変換します。
std::u32string utf8to32 ( const std::string& s); s ：UTF-8エンコード文字列。戻り値：UTF-32エンコードされた文字列。
使用例：
const char * twochars = " xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2);無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。
バージョン3.2以降で利用可能です。 C ++ 17準拠コンパイラが必要です。
UTF-8エンコードされた文字列をUTF-32に変換します。
std::u32string utf8to32 (std::string_view s); s ：UTF-8エンコード文字列。戻り値：UTF-32エンコードされた文字列。
使用例：
string_view twochars = " xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2);無効なUTF-8シーケンスの場合、 utf8::invalid_utf8例外がスローされます。
バージョン1.0以降で利用できます。
UTF-8文字列内の無効なシーケンスを検出します。
template < typename octet_iterator>
octet_iterator find_invalid (octet_iterator start, octet_iterator end); octet_iterator ：入力イテレーター。
start ：UTF-8文字列の始まりを指して、有効性をテストします。
end ：UTF-8文字列のパスエンドを指して、有効性をテストするイテレーター。
戻り値：UTF-8文字列の最初の無効なオクテットを指すイテレーター。何も見つからなかった場合、等しくなりend 。
使用例：
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
char * invalid = find_invalid(utf_invalid, utf_invalid + 6 );
assert (invalid == utf_invalid + 5 );この関数は通常、UTF-8文字列が他の関数で処理する前に有効であることを確認するために使用されます。チェックされていない操作を行う前に、それを呼び出すことが特に重要です。
バージョン4.0以降で利用できます。
CスタイルのUTF-8文字列内の無効なシーケンスを検出します。
const char * find_invalid ( const char * str); str ：UTF-8エンコード文字列。戻り値：UTF-8文字列の最初の無効なオクテットへのポインター。何も見つからなかった場合、後続のゼロバイトを指します。
使用例：
const char * utf_invalid = " xe6x97xa5xd1x88xfa " ;
const char * invalid = find_invalid(utf_invalid);
assert ((invalid - utf_invalid) == 5);この関数は通常、UTF-8文字列が他の関数で処理する前に有効であることを確認するために使用されます。チェックされていない操作を行う前に、それを呼び出すことが特に重要です。
バージョン3.0以降で利用できます。 4.0の前に、C ++ 11コンパイラが必要でした。要件は4.0で解除されます
UTF-8文字列内の無効なシーケンスを検出します。
std:: size_t find_invalid ( const std::string& s); s ：UTF-8エンコード文字列。戻り値：UTF-8文字列の最初の無効なオクテットのインデックス。何も見つからなかった場合、 std::string::nposに等しくなります。
使用例：
string utf_invalid = " xe6x97xa5xd1x88xfa " ;
auto invalid = find_invalid(utf_invalid);
assert (invalid == 5 );この関数は通常、UTF-8文字列が他の関数で処理する前に有効であることを確認するために使用されます。チェックされていない操作を行う前に、それを呼び出すことが特に重要です。
バージョン3.2以降で利用可能です。 C ++ 17準拠コンパイラが必要です。
UTF-8文字列内の無効なシーケンスを検出します。
std:: size_t find_invalid (std::string_view s); s ：UTF-8エンコード文字列。戻り値：UTF-8文字列の最初の無効なオクテットのインデックス。何も見つからなかった場合、 std::string_view::nposに等しくなります。
使用例：
string_view utf_invalid = " xe6x97xa5xd1x88xfa " ;
auto invalid = find_invalid(utf_invalid);
assert (invalid == 5 );この関数は通常、UTF-8文字列が他の関数で処理する前に有効であることを確認するために使用されます。チェックされていない操作を行う前に、それを呼び出すことが特に重要です。
バージョン1.0以降で利用できます。
オクテットのシーケンスが有効なUTF-8文字列であるかどうかを確認します。
template < typename octet_iterator>
bool is_valid (octet_iterator start, octet_iterator end); octet_iterator ：入力イテレーター。
start ：UTF-8文字列の始まりを指して、有効性をテストします。
end ：UTF-8文字列のパスエンドを指して、有効性をテストするイテレーター。
戻り値：シーケンスが有効なUTF-8文字列の場合はtrue 。そうでない場合はfalse 。
使用例：
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid, utf_invalid + 6 );
assert (bvalid == false ); is_valid find_invalid(start, end) == end; 。それを使用して、バイトシーケンスが有効なUTF-8文字列であることを確認することをお勧めします。
バージョン4.0以降で利用できます。
Cスタイルの文字列に有効なUTF-8エンコードされたテキストが含まれているかどうかを確認します。
bool is_valid ( const char * str); str ：UTF-8エンコード文字列。
戻り値：文字列に有効なUTF-8エンコードされたテキストが含まれている場合はtrue 。そうでない場合はfalse 。
使用例：
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); is_valid使用して、文字列に有効なUTF-8テキストが含まれていることを確認することをお勧めします。
バージョン3.0以降で利用できます。 4.0の前に、C ++ 11コンパイラが必要でした。要件は4.0で解除されます
文字列オブジェクトに有効なUTF-8エンコードされたテキストが含まれているかどうかを確認します。
bool is_valid ( const std::string& s); s ：UTF-8エンコード文字列。
戻り値：文字列に有効なUTF-8エンコードされたテキストが含まれている場合はtrue 。そうでない場合はfalse 。
使用例：
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); is_valid使用して、文字列に有効なUTF-8テキストが含まれていることを確認することをお勧めします。
バージョン3.2以降で利用可能です。 C ++ 17準拠コンパイラが必要です。
文字列オブジェクトに有効なUTF-8エンコードされたテキストが含まれているかどうかを確認します。
bool is_valid (std::string_view s); s ：UTF-8エンコード文字列。
戻り値：文字列に有効なUTF-8エンコードされたテキストが含まれている場合はtrue 。そうでない場合はfalse 。
使用例：
string_view utf_invalid = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); is_valid使用して、文字列に有効なUTF-8テキストが含まれていることを確認することをお勧めします。
バージョン2.0以降で利用できます。
文字列内のすべての無効なUTF-8シーケンスを交換マーカーに置き換えます。
template < typename octet_iterator, typename output_iterator>
output_iterator replace_invalid (octet_iterator start, octet_iterator end, output_iterator out, utfchar32_t replacement);
template < typename octet_iterator, typename output_iterator>
output_iterator replace_invalid (octet_iterator start, octet_iterator end, output_iterator out); octet_iterator ：入力イテレーター。
output_iterator ：出力イテレーター。
start ：UTF-8文字列の先頭を指して、無効なUTF-8シーケンスを探すイテレーター。
end ：UTF-8文字列のパスエンドを指して、無効なUTF-8シーケンスを探すイテレーター。
out ：交換の結果が保存されている範囲への出力イテレータ。
replacement : A Unicode code point for the replacement marker. The version without this parameter assumes the value 0xfffd
Return value: An iterator pointing to the place after the UTF-8 string with replaced invalid sequences.
Example of use:
char invalid_sequence[] = " a x80xe0xa0xc0xafxedxa0x80 z " ;
vector< char > replace_invalid_result;
replace_invalid (invalid_sequence, invalid_sequence + sizeof (invalid_sequence), back_inserter(replace_invalid_result), '?');
bvalid = is_valid(replace_invalid_result.begin(), replace_invalid_result.end());
assert (bvalid);
char * fixed_invalid_sequence = " a????z " ;
assert (std::equal(replace_invalid_result.begin(), replace_invalid_result.end(), fixed_invalid_sequence)); replace_invalid does not perform in-place replacement of invalid sequences. Rather, it produces a copy of the original string with the invalid sequences replaced with a replacement marker. Therefore, out must not be in the [start, end] range.
Available in version 3.0 and later. Prior to 4.0 it required a C++ 11 compiler; the requirement is lifted with 4.0
Replaces all invalid UTF-8 sequences within a string with a replacement marker.
std::string replace_invalid ( const std::string& s, utfchar32_t replacement);
std::string replace_invalid ( const std::string& s); s : a UTF-8 encoded string.
replacement : A Unicode code point for the replacement marker. The version without this parameter assumes the value 0xfffd
Return value: A UTF-8 encoded string with replaced invalid sequences.
Example of use:
string invalid_sequence = " a x80xe0xa0xc0xafxedxa0x80 z " ;
string replace_invalid_result = replace_invalid(invalid_sequence, ' ? ' );
bvalid = is_valid(replace_invalid_result);
assert (bvalid);
const string fixed_invalid_sequence = " a????z " ;
assert (fixed_invalid_sequence == replace_invalid_result);Available in version 3.2 and later. Requires a C++ 17 compliant compiler.
Replaces all invalid UTF-8 sequences within a string with a replacement marker.
std::string replace_invalid (std::string_view s, char32_t replacement);
std::string replace_invalid (std::string_view s); s : a UTF-8 encoded string.
replacement : A Unicode code point for the replacement marker. The version without this parameter assumes the value 0xfffd
Return value: A UTF-8 encoded string with replaced invalid sequences.
Example of use:
string_view invalid_sequence = " a x80xe0xa0xc0xafxedxa0x80 z " ;
string replace_invalid_result = replace_invalid(invalid_sequence, ' ? ' );
bool bvalid = is_valid(replace_invalid_result);
assert (bvalid);
const string fixed_invalid_sequence = " a????z " ;
assert (fixed_invalid_sequence, replace_invalid_result);Available in version 2.3 and later.
Checks whether an octet sequence starts with a UTF-8 byte order mark (BOM)
template < typename octet_iterator>
bool starts_with_bom (octet_iterator it, octet_iterator end); octet_iterator : an input iterator.
it : beginning of the octet sequence to check
end : pass-end of the sequence to check
Return value: true if the sequence starts with a UTF-8 byte order mark; false if not.
Example of use:
unsigned char byte_order_mark[] = { 0xef , 0xbb , 0xbf };
bool bbom = starts_with_bom(byte_order_mark, byte_order_mark + sizeof (byte_order_mark));
assert (bbom == true );The typical use of this function is to check the first three bytes of a file. If they form the UTF-8 BOM, we want to skip them before processing the actual UTF-8 encoded text.
Available in version 3.0 and later. Prior to 4.0 it required a C++ 11 compiler; the requirement is lifted with 4.0
Checks whether a string starts with a UTF-8 byte order mark (BOM)
bool starts_with_bom ( const std::string& s); s : a UTF-8 encoded string. Return value: true if the string starts with a UTF-8 byte order mark; false if not.
Example of use:
string byte_order_mark = { char ( 0xef ), char ( 0xbb ), char ( 0xbf )};
bool bbom = starts_with_bom(byte_order_mark);
assert (bbom == true );
string threechars = " xf0x90x8dx86xe6x97xa5xd1x88 " ;
bool no_bbom = starts_with_bom(threechars);
assert (no_bbom == false );The typical use of this function is to check the first three bytes of a file. If they form the UTF-8 BOM, we want to skip them before processing the actual UTF-8 encoded text.
Available in version 3.2 and later. Requires a C++ 17 compliant compiler.
Checks whether a string starts with a UTF-8 byte order mark (BOM)
bool starts_with_bom (std::string_view s); s : a UTF-8 encoded string. Return value: true if the string starts with a UTF-8 byte order mark; false if not.
Example of use:
string byte_order_mark = { char ( 0xef ), char ( 0xbb ), char ( 0xbf )};
string_view byte_order_mark_view (byte_order_mark);
bool bbom = starts_with_bom(byte_order_mark_view);
assert (bbom);
string_view threechars = " xf0x90x8dx86xe6x97xa5xd1x88 " ;
bool no_bbom = starts_with_bom(threechars);
assert (!no_bbom);The typical use of this function is to check the first three bytes of a file. If they form the UTF-8 BOM, we want to skip them before processing the actual UTF-8 encoded text.
Available in version 2.3 and later.
Base class for the exceptions thrown by UTF CPP library functions.
class exception : public std :: exception {};Example of use:
try {
code_that_uses_utf_cpp_library ();
}
catch ( const utf8:: exception & utfcpp_ex) {
cerr << utfcpp_ex. what ();
}Available in version 1.0 and later.
Thrown by UTF8 CPP functions such as advance and next if an UTF-8 sequence represents and invalid code point.
class invalid_code_point : public exception {
public:
utfchar32_t code_point () const ;
}; Member function code_point() can be used to determine the invalid code point that caused the exception to be thrown.
Available in version 1.0 and later.
Thrown by UTF8 CPP functions such as next and prior if an invalid UTF-8 sequence is detected during decoding.
class invalid_utf8 : public exception {
public:
utfchar8_t utf8_octet () const ;
}; Member function utf8_octet() can be used to determine the beginning of the byte sequence that caused the exception to be thrown.
Available in version 1.0 and later.
Thrown by UTF8 CPP function utf16to8 if an invalid UTF-16 sequence is detected during decoding.
class invalid_utf16 : public exception {
public:
utfchar16_t utf16_word () const ;
}; Member function utf16_word() can be used to determine the UTF-16 code unit that caused the exception to be thrown.
Available in version 1.0 and later.
Thrown by UTF8 CPP functions such as next if the end of the decoded UTF-8 sequence was reached before the code point was decoded.
class not_enough_room : public exception {};Available in version 2.0 and later.
Adapts the underlying octet iterator to iterate over the sequence of code points, rather than raw octets.
template < typename octet_iterator>
class iterator ; iterator(); the default constructor; the underlying octet_iterator is constructed with its default constructor.
explicit iterator (const octet_iterator& octet_it, const octet_iterator& range_start, const octet_iterator& range_end); a constructor that initializes the underlying octet_iterator with octet_it and sets the range in which the iterator is considered valid.
octet_iterator base () const; returns the underlying octet_iterator.
utfchar32_t operator * () const; decodes the utf-8 sequence the underlying octet_iterator is pointing to and returns the code point.
bool operator == (const iterator& rhs) const; returns true if the two underlying iterators are equal.
bool operator != (const iterator& rhs) const; returns true if the two underlying iterators are not equal.
iterator& operator ++ (); the prefix increment - moves the iterator to the next UTF-8 encoded code point.
iterator operator ++ (int); the postfix increment - moves the iterator to the next UTF-8 encoded code point and returns the current one.
iterator& operator -- (); the prefix decrement - moves the iterator to the previous UTF-8 encoded code point.
iterator operator -- (int); the postfix decrement - moves the iterator to the previous UTF-8 encoded code point and returns the current one.
Example of use:
char * threechars = " xf0x90x8dx86xe6x97xa5xd1x88 " ;
utf8::iterator< char *> it (threechars, threechars, threechars + 9 );
utf8::iterator< char *> it2 = it;
assert (it2 == it);
assert (*it == 0x10346 );
assert (*(++it) == 0x65e5);
assert ((*it++) == 0x65e5);
assert (*it == 0x0448 );
assert (it != it2);
utf8::iterator< char *> endit (threechars + 9 , threechars, threechars + 9 );
assert (++it == endit);
assert (*(--it) == 0x0448);
assert ((*it--) == 0x0448);
assert (*it == 0x65e5 );
assert (--it == utf8::iterator< char *>(threechars, threechars, threechars + 9 ));
assert (*it == 0x10346 ); The purpose of utf8::iterator adapter is to enable easy iteration as well as the use of STL algorithms with UTF-8 encoded strings. Increment and decrement operators are implemented in terms of utf8::next() and utf8::prior() functions.
Note that utf8::iterator adapter is a checked iterator. It operates on the range specified in the constructor; any attempt to go out of that range will result in an exception. Even the comparison operators require both iterator object to be constructed against the same range - otherwise an exception is thrown. Typically, the range will be determined by sequence container functions begin and end , ie:
std::string s = " example " ;
utf8::iterator i (s.begin(), s.begin(), s.end());Available in version 1.0 and later.
Encodes a 32 bit code point as a UTF-8 sequence of octets and appends the sequence to a UTF-8 string.
template < typename octet_iterator>
octet_iterator append ( utfchar32_t cp, octet_iterator result); cp : A 32 bit integer representing a code point to append to the sequence.
result : An output iterator to the place in the sequence where to append the code point.
Return value: An iterator pointing to the place after the newly appended sequence.
Example of use:
unsigned char u[ 5 ] = { 0 , 0 , 0 , 0 , 0 };
unsigned char * end = unchecked::append( 0x0448 , u);
assert (u[ 0 ] == 0xd1 && u[ 1 ] == 0x88 && u[ 2 ] == 0 && u[ 3 ] == 0 && u[ 4 ] == 0 ); This is a faster but less safe version of utf8::append . It does not check for validity of the supplied code point, and may produce an invalid UTF-8 sequence.
Available in version 4.0 and later.
Encodes a 32 bit code point as a UTF-16 sequence of words and appends the sequence to a UTF-16 string.
template < typename word_iterator>
word_iterator append16 ( utfchar32_t cp, word_iterator result) cp : A 32 bit integer representing a code point to append to the sequence.
result : An output iterator to the place in the sequence where to append the code point.
Return value: An iterator pointing to the place after the newly appended sequence.
Example of use:
unsigned short u[ 5 ] = { 0 , 0 };
utf8::unchecked::append16 ( 0x0448 , u);
assert (u[ 0 ], 0x0448 );
assert (u[ 1 ], 0x0000 ); This is a faster but less safe version of utf8::append . It does not check for validity of the supplied code point, and may produce an invalid UTF-8 sequence.
Available in version 1.0 and later.
Given the iterator to the beginning of a UTF-8 sequence, it returns the code point and moves the iterator to the next position.
template < typename octet_iterator>
utfchar32_t next (octet_iterator& it); it : a reference to an iterator pointing to the beginning of an UTF-8 encoded code point. After the function returns, it is incremented to point to the beginning of the next code point.
Return value: the 32 bit representation of the processed UTF-8 code point.
Example of use:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = unchecked::next(w);
assert (cp == 0x65e5 );
assert (w == twochars + 3 ); This is a faster but less safe version of utf8::next . It does not check for validity of the supplied UTF-8 sequence.
Available in version 4.0 and later.
Given the iterator to the beginning of the UTF-16 sequence, it returns the code point and moves the iterator to the next position.
template < typename word_iterator>
utfchar32_t next16 (word_iterator& it); word_iterator : an input iterator.
it : a reference to an iterator pointing to the beginning of an UTF-16 encoded code point. After the function returns, it is incremented to point to the beginning of the next code point.
Return value: the 32 bit representation of the processed UTF-16 code point.
Example of use:
const unsigned short u[ 3 ] = { 0x65e5 , 0xd800 , 0xdf46 };
const unsigned short * w = u;
int cp = unchecked::next16(w);
assert (cp, 0x65e5 );
assert (w, u + 1 );This function is typically used to iterate through a UTF-16 encoded string.
This is a faster but less safe version of utf8::next16 . It does not check for validity of the supplied UTF-8 sequence.
Available in version 2.1 and later.
Given the iterator to the beginning of a UTF-8 sequence, it returns the code point.
template < typename octet_iterator>
utfchar32_t peek_next (octet_iterator it); it : an iterator pointing to the beginning of an UTF-8 encoded code point.
Return value: the 32 bit representation of the processed UTF-8 code point.
Example of use:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = unchecked::peek_next(w);
assert (cp == 0x65e5 );
assert (w == twochars); This is a faster but less safe version of utf8::peek_next . It does not check for validity of the supplied UTF-8 sequence.
Available in version 1.02 and later.
Given a reference to an iterator pointing to an octet in a UTF-8 sequence, it decreases the iterator until it hits the beginning of the previous UTF-8 encoded code point and returns the 32 bits representation of the code point.
template < typename octet_iterator>
utfchar32_t prior (octet_iterator& it); it : a reference pointing to an octet within a UTF-8 encoded string. After the function returns, it is decremented to point to the beginning of the previous code point.
Return value: the 32 bit representation of the previous code point.
Example of use:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars + 3 ;
int cp = unchecked::prior (w);
assert (cp == 0x65e5 );
assert (w == twochars); This is a faster but less safe version of utf8::prior . It does not check for validity of the supplied UTF-8 sequence and offers no boundary checking.
Available in version 1.0 and later.
Advances an iterator by the specified number of code points within an UTF-8 sequence.
template < typename octet_iterator, typename distance_type>
void advance (octet_iterator& it, distance_type n); it : a reference to an iterator pointing to the beginning of an UTF-8 encoded code point. After the function returns, it is incremented to point to the nth following code point. n : number of code points it should be advanced. A negative value means decrement.
Example of use:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
unchecked::advance (w, 2 );
assert (w == twochars + 5 ); This is a faster but less safe version of utf8::advance . It does not check for validity of the supplied UTF-8 sequence and offers no boundary checking.
Available in version 1.0 and later.
Given the iterators to two UTF-8 encoded code points in a sequence, returns the number of code points between them.
template < typename octet_iterator>
typename std::iterator_traits<octet_iterator>::difference_type distance (octet_iterator first, octet_iterator last); first : an iterator to a beginning of a UTF-8 encoded code point.
last : an iterator to a "post-end" of the last UTF-8 encoded code point in the sequence we are trying to determine the length. It can be the beginning of a new code point, or not.
Return value: the distance between the iterators, in code points.
Example of use:
char * twochars = " xe6x97xa5xd1x88 " ;
size_t dist = utf8::unchecked::distance(twochars, twochars + 5 );
assert (dist == 2 ); This is a faster but less safe version of utf8::distance . It does not check for validity of the supplied UTF-8 sequence.
Available in version 1.0 and later.
Converts a UTF-16 encoded string to UTF-8.
template < typename u16bit_iterator, typename octet_iterator>
octet_iterator utf16to8 (u16bit_iterator start, u16bit_iterator end, octet_iterator result); start : an iterator pointing to the beginning of the UTF-16 encoded string to convert.
end : an iterator pointing to pass-the-end of the UTF-16 encoded string to convert.
result : an output iterator to the place in the UTF-8 string where to append the result of conversion.
Return value: An iterator pointing to the place after the appended UTF-8 string.
Example of use:
unsigned short utf16string[] = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
vector< unsigned char > utf8result;
unchecked::utf16to8 (utf16string, utf16string + 5 , back_inserter(utf8result));
assert (utf8result.size() == 10); This is a faster but less safe version of utf8::utf16to8 . It does not check for validity of the supplied UTF-16 sequence.
Available in version 1.0 and later.
Converts an UTF-8 encoded string to UTF-16
template < typename u16bit_iterator, typename octet_iterator>
u16bit_iterator utf8to16 (octet_iterator start, octet_iterator end, u16bit_iterator result); start : an iterator pointing to the beginning of the UTF-8 encoded string to convert. end : an iterator pointing to pass-the-end of the UTF-8 encoded string to convert.
result : an output iterator to the place in the UTF-16 string where to append the result of conversion.
Return value: An iterator pointing to the place after the appended UTF-16 string.
Example of use:
char utf8_with_surrogates[] = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
vector < unsigned short > utf16result;
unchecked::utf8to16 (utf8_with_surrogates, utf8_with_surrogates + 9 , back_inserter(utf16result));
assert (utf16result.size() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e ); This is a faster but less safe version of utf8::utf8to16 . It does not check for validity of the supplied UTF-8 sequence.
Available in version 1.0 and later.
Converts a UTF-32 encoded string to UTF-8.
template < typename octet_iterator, typename u32bit_iterator>
octet_iterator utf32to8 (u32bit_iterator start, u32bit_iterator end, octet_iterator result); start : an iterator pointing to the beginning of the UTF-32 encoded string to convert.
end : an iterator pointing to pass-the-end of the UTF-32 encoded string to convert.
result : an output iterator to the place in the UTF-8 string where to append the result of conversion.
Return value: An iterator pointing to the place after the appended UTF-8 string.
Example of use:
int utf32string[] = { 0x448 , 0x65e5 , 0x10346 , 0 };
vector< unsigned char > utf8result;
utf32to8 (utf32string, utf32string + 3 , back_inserter(utf8result));
assert (utf8result.size() == 9); This is a faster but less safe version of utf8::utf32to8 . It does not check for validity of the supplied UTF-32 sequence.
Available in version 1.0 and later.
Converts a UTF-8 encoded string to UTF-32.
template < typename octet_iterator, typename u32bit_iterator>
u32bit_iterator utf8to32 (octet_iterator start, octet_iterator end, u32bit_iterator result); start : an iterator pointing to the beginning of the UTF-8 encoded string to convert.
end : an iterator pointing to pass-the-end of the UTF-8 encoded string to convert.
result : an output iterator to the place in the UTF-32 string where to append the result of conversion.
Return value: An iterator pointing to the place after the appended UTF-32 string.
Example of use:
char * twochars = " xe6x97xa5xd1x88 " ;
vector< int > utf32result;
unchecked::utf8to32 (twochars, twochars + 5 , back_inserter(utf32result));
assert (utf32result.size() == 2); This is a faster but less safe version of utf8::utf8to32 . It does not check for validity of the supplied UTF-8 sequence.
Available in version 3.1 and later.
Replaces all invalid UTF-8 sequences within a string with a replacement marker.
template < typename octet_iterator, typename output_iterator>
output_iterator replace_invalid (octet_iterator start, octet_iterator end, output_iterator out, utfchar32_t replacement);
template < typename octet_iterator, typename output_iterator>
output_iterator replace_invalid (octet_iterator start, octet_iterator end, output_iterator out); octet_iterator : an input iterator.
output_iterator : an output iterator.
start : an iterator pointing to the beginning of the UTF-8 string to look for invalid UTF-8 sequences.
end : an iterator pointing to pass-the-end of the UTF-8 string to look for invalid UTF-8 sequences.
out : An output iterator to the range where the result of replacement is stored.
replacement : A Unicode code point for the replacement marker. The version without this parameter assumes the value 0xfffd
Return value: An iterator pointing to the place after the UTF-8 string with replaced invalid sequences.
Example of use:
char invalid_sequence[] = " a x80xe0xa0xc0xafxedxa0x80 z " ;
vector< char > replace_invalid_result;
unchecked::replace_invalid (invalid_sequence, invalid_sequence + sizeof (invalid_sequence), back_inserter(replace_invalid_result), '?');
bvalid = utf8::is_valid(replace_invalid_result.begin(), replace_invalid_result.end());
assert (bvalid);
char * fixed_invalid_sequence = " a????z " ;
assert (std::equal(replace_invalid_result.begin(), replace_invalid_result.end(), fixed_invalid_sequence)); replace_invalid does not perform in-place replacement of invalid sequences. Rather, it produces a copy of the original string with the invalid sequences replaced with a replacement marker. Therefore, out must not be in the [start, end] range.
Unlike utf8::replace_invalid , this function does not verify validity of the replacement marker.
Available in version 2.0 and later.
Adapts the underlying octet iterator to iterate over the sequence of code points, rather than raw octets.
template < typename octet_iterator>
class iterator ; iterator(); the default constructor; the underlying octet_iterator is constructed with its default constructor.
explicit iterator (const octet_iterator& octet_it); a constructor that initializes the underlying octet_iterator with octet_it .
octet_iterator base () const; returns the underlying octet_iterator.
utfchar32_t operator * () const; decodes the utf-8 sequence the underlying octet_iterator is pointing to and returns the code point.
bool operator == (const iterator& rhs) const; returns true if the two underlying iterators are equal.
bool operator != (const iterator& rhs) const; returns true if the two underlying iterators are not equal.
iterator& operator ++ (); the prefix increment - moves the iterator to the next UTF-8 encoded code point.
iterator operator ++ (int); the postfix increment - moves the iterator to the next UTF-8 encoded code point and returns the current one.
iterator& operator -- (); the prefix decrement - moves the iterator to the previous UTF-8 encoded code point.
iterator operator -- (int); the postfix decrement - moves the iterator to the previous UTF-8 encoded code point and returns the current one.
Example of use:
char * threechars = " xf0x90x8dx86xe6x97xa5xd1x88 " ;
utf8::unchecked::iterator< char *> un_it (threechars);
utf8::unchecked::iterator< char *> un_it2 = un_it;
assert (un_it2 == un_it);
assert (*un_it == 0x10346 );
assert (*(++un_it) == 0x65e5);
assert ((*un_it++) == 0x65e5);
assert (*un_it == 0x0448 );
assert (un_it != un_it2);
utf8::::unchecked::iterator< char *> un_endit (threechars + 9 );
assert (++un_it == un_endit);
assert (*(--un_it) == 0x0448);
assert ((*un_it--) == 0x0448);
assert (*un_it == 0x65e5 );
assert (--un_it == utf8::unchecked::iterator< char *>(threechars));
assert (*un_it == 0x10346 ); This is an unchecked version of utf8::iterator . It is faster in many cases, but offers no validity or range checks.
