utfcpp
Release 4.0.6
Pengembang C ++ masih kehilangan cara yang mudah dan portabel untuk menangani string yang dikodekan Unicode. Standar C ++ asli (dikenal sebagai C ++ 98 atau C ++ 03) adalah unicode agnostik. Beberapa kemajuan telah dibuat dalam edisi standar selanjutnya, tetapi masih sulit untuk bekerja dengan Unicode hanya menggunakan fasilitas standar.
Saya datang dengan perpustakaan generik yang kompatibel dengan C ++ 98 untuk menangani string yang dikodekan UTF-8. Bagi siapa pun yang dulu bekerja dengan algoritma dan iterator STL, itu harus mudah dan alami untuk digunakan. Kode ini tersedia secara bebas untuk tujuan apa pun - lihat lisensi. Perpustakaan telah banyak digunakan sejak rilis pertama pada tahun 2006 baik dalam proyek komersial maupun open-source dan terbukti stabil dan bermanfaat.
Ini adalah perpustakaan header saja dan cara yang didukung untuk menggunakannya adalah:
File cmakelist.txt awalnya dibuat untuk tujuan pengujian saja, tetapi sayangnya dari waktu ke waktu saya menerima kontribusi yang menambahkan target instalasi. Ini bukan cara yang didukung untuk menginstal perpustakaan UTFCPP dan saya mempertimbangkan untuk menghapus cmakelist.txt dalam rilis mendatang.
Untuk mengilustrasikan penggunaan perpustakaan, mari kita mulai dengan program kecil tapi lengkap yang membuka file yang berisi teks yang dikodekan UTF-8, membacanya baris demi baris, memeriksa setiap baris untuk urutan byte UTF-8 yang tidak valid, dan mengubahnya menjadi pengkodean UTF-16 dan kembali ke 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 ;
} Dalam sampel kode sebelumnya, untuk setiap baris kami melakukan deteksi urutan UTF-8 yang tidak valid dengan find_invalid ; Jumlah karakter (lebih tepatnya - jumlah titik kode unicode, termasuk akhir baris dan bahkan bom jika ada satu) di setiap baris ditentukan dengan penggunaan utf8::distance ; Akhirnya, kami telah mengonversi setiap baris menjadi pengkodean UTF-16 dengan utf8to16 dan kembali ke UTF-8 dengan utf16to8 .
Perhatikan pola penggunaan yang berbeda untuk kompiler lama. Misalnya, ini adalah bagaimana kami mengonversi string yang dikodekan UTF-8 menjadi UTF-16 yang dikodekan dengan kompiler pre-C ++ 11:
vector< unsigned short > utf16line;
utf8::utf8to16 (line.begin(), end_it, back_inserter(utf16line));Dengan kompiler yang lebih modern, operasi yang sama akan terlihat seperti:
u16string utf16line = utf8::utf8to16(line); Jika __cplusplus makro menunjuk ke C ++ 11 atau lebih, perpustakaan memperlihatkan API yang memperhitungkan string unicode standar C ++ dan memindahkan semantik. Dengan kompiler yang lebih tua, masih dimungkinkan untuk menggunakan fungsionalitas yang sama, hanya dengan cara yang kurang nyaman
Jika Anda tidak mempercayai makro __cplusplus atau, misalnya, tidak ingin memasukkan fungsi pembantu C ++ 11 bahkan dengan kompiler modern, tentukan makro UTF_CPP_CPLUSPLUS sebelum memasukkan utf8.h dan tetapkan nilai untuk standar yang ingin Anda gunakan - nilainya sama dengan untuk __cplusplus mac. Ini juga dapat berguna dengan kompiler yang konservatif dalam mengatur makro __cplusplus bahkan jika mereka memiliki dukungan yang baik untuk edisi standar terbaru - Visual C ++ Microsoft adalah salah satu contoh.
Berikut adalah fungsi yang memeriksa apakah konten file adalah teks yang dikodekan UTF-8 yang valid tanpa membaca konten ke dalam memori:
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);
} Karena fungsi utf8::is_valid() berfungsi dengan iterator input, kami dapat meneruskan istreambuf_iterator ke it dan membaca konten file secara langsung tanpa memuatnya ke memori terlebih dahulu.
Perhatikan bahwa fungsi lain yang mengambil argumen input iterator dapat digunakan dengan cara yang sama. Misalnya, untuk membaca konten file teks yang dikodekan UTF-8 dan mengubah teks menjadi UTF-16, lakukan saja sesuatu seperti:
utf8::utf8to16 (it, eos, back_inserter(u16string));Jika kami memiliki beberapa teks yang "mungkin" berisi teks yang dikodekan UTF-8 dan kami ingin mengganti urutan UTF-8 yang tidak valid dengan karakter pengganti, sesuatu seperti fungsi berikut dapat digunakan:
void fix_utf8_string (std::string& str)
{
std::string temp;
utf8::replace_invalid (str. begin (), str. end (), back_inserter (temp));
str = temp;
}Fungsi ini akan menggantikan urutan UTF-8 yang tidak valid dengan karakter penggantian unicode. Ada fungsi kelebihan beban yang memungkinkan penelepon untuk memasok karakter pengganti mereka sendiri.
Perpustakaan dirancang untuk:
Untuk alternatif dan perbandingan, saya merekomendasikan artikel berikut: Dunia C ++ encoding API yang sangat mengerikan (dengan beberapa karat), oleh Jeanheyd Meneide. Dalam artikel tersebut, perpustakaan ini dibandingkan dengan:
Artikel ini menyajikan pandangan penulis tentang kualitas desain API, tetapi juga beberapa tolok ukur kecepatan.
Tersedia dalam versi 1.0 dan yang lebih baru.
Mengkodekan titik kode 32 bit sebagai urutan oktet UTF-8 dan menambahkan urutan ke string UTF-8.
template < typename octet_iterator>
octet_iterator append ( utfchar32_t cp, octet_iterator result); octet_iterator : Iterator output.
cp : Integer 32 bit yang mewakili titik kode untuk ditambahkan ke urutan.
result : Iterator output ke tempat di urutan di mana untuk menambahkan titik kode.
Nilai Pengembalian: Iterator yang menunjuk ke tempat itu setelah urutan yang baru ditambahkan.
Contoh Penggunaan:
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 ); Perhatikan bahwa append tidak mengalokasikan memori apa pun - itu adalah beban penelepon untuk memastikan ada cukup memori yang dialokasikan untuk operasi. Untuk membuat hal -hal lebih menarik, append dapat menambah antara 1 dan 4 oktet ke urutan. Dalam praktiknya, Anda paling sering ingin menggunakan std::back_inserter untuk memastikan bahwa memori yang diperlukan dialokasikan.
Dalam hal titik kode yang tidak valid, pengecualian utf8::invalid_code_point dilemparkan.
Tersedia dalam versi 3.0 dan yang lebih baru. Sebelum 4.0 diperlukan kompiler C ++ 11; Persyaratan diangkat dengan 4.0.
Mengkodekan titik kode 32 bit sebagai urutan oktet UTF-8 dan menambahkan urutan ke string UTF-8.
void append ( utfchar32_t cp, std::string& s); cp : Poin kode untuk ditambahkan ke string.
s : String yang dikodekan UTF-8 untuk menambahkan titik kode.
Contoh Penggunaan:
std::string u;
append ( 0x0448 , u);
assert (u[ 0 ] == char ( 0xd1 ) && u[1] == char( 0x88 ) && u.length() == 2); Dalam hal titik kode yang tidak valid, pengecualian utf8::invalid_code_point dilemparkan.
Tersedia dalam versi 4.0 dan yang lebih baru.
Mengkodekan titik kode 32 bit sebagai urutan kata UTF-16 dan menambahkan urutan ke string UTF-16.
template < typename word_iterator>
word_iterator append16 ( utfchar32_t cp, word_iterator result); word_iterator : Iterator output.
cp : Integer 32 bit yang mewakili titik kode untuk ditambahkan ke urutan.
result : Iterator output ke tempat di urutan di mana untuk menambahkan titik kode.
Nilai Pengembalian: Iterator yang menunjuk ke tempat itu setelah urutan yang baru ditambahkan.
Contoh Penggunaan:
unsigned short u[ 2 ] = { 0 , 0 };
unsigned short * end = append16( 0x0448 , u);
assert (u[ 0 ] == 0x0448 && u[ 1 ] == 0 ); Perhatikan bahwa append16 tidak mengalokasikan memori apa pun - itu adalah beban penelepon untuk memastikan ada cukup memori yang dialokasikan untuk operasi. Untuk membuat segalanya lebih menarik, append16 dapat menambahkan satu atau dua kata ke urutan. Dalam praktiknya, Anda paling sering ingin menggunakan std::back_inserter untuk memastikan bahwa memori yang diperlukan dialokasikan.
Dalam hal titik kode yang tidak valid, pengecualian utf8::invalid_code_point dilemparkan.
Tersedia dalam versi 4.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 11.
Mengkodekan titik kode 32 bit sebagai urutan kata UTF-16 dan menambahkan urutan ke string UTF-16.
void append ( utfchar32_t cp, std::u16string& s); cp : Poin kode untuk ditambahkan ke string.
s : String yang dikodekan UTF-16 untuk menambahkan titik kode.
Contoh Penggunaan:
std::u16string u;
append ( 0x0448 , u);
assert (u[ 0 ] == 0x0448 && u.length() == 1); Dalam hal titik kode yang tidak valid, pengecualian utf8::invalid_code_point dilemparkan.
Tersedia dalam versi 1.0 dan yang lebih baru.
Mengingat iterator ke awal urutan UTF-8, ia mengembalikan titik kode dan memindahkan iterator ke posisi berikutnya.
template < typename octet_iterator>
utfchar32_t next (octet_iterator& it, octet_iterator end); octet_iterator : Iterator input.
it : Referensi ke iterator yang menunjuk ke awal titik kode yang dikodekan UTF-8. Setelah fungsi kembali, bertambah untuk menunjuk ke awal titik kode berikutnya.
end : Akhir dari Urutan UTF-8 yang akan diproses. Jika it sama dengan end selama ekstraksi titik kode, pengecualian utf8::not_enough_room dilemparkan.
Nilai Pengembalian: Representasi 32 bit dari titik kode UTF-8 yang diproses.
Contoh Penggunaan:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = next(w, twochars + 6 );
assert (cp == 0x65e5 );
assert (w == twochars + 3 );Fungsi ini biasanya digunakan untuk mengulangi melalui string yang dikodekan UTF-8.
Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan.
Tersedia dalam versi 4.0 dan yang lebih baru.
Mengingat iterator ke awal urutan UTF-16, ia mengembalikan titik kode dan memindahkan iterator ke posisi berikutnya.
template < typename word_iterator>
utfchar32_t next16 (word_iterator& it, word_iterator end); word_iterator : Iterator input.
it : referensi ke iterator yang menunjuk ke awal titik kode yang dikodekan UTF-16. Setelah fungsi kembali, bertambah untuk menunjuk ke awal titik kode berikutnya.
end : Akhir dari urutan UTF-16 yang akan diproses. Jika it sama dengan end selama ekstraksi titik kode, pengecualian utf8::not_enough_room dilemparkan.
Nilai Pengembalian: Representasi 32 bit dari titik kode UTF-16 yang diproses.
Contoh Penggunaan:
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 );Fungsi ini biasanya digunakan untuk mengulangi melalui string yang dikodekan UTF-16.
Dalam hal urutan UTF-16 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan.
Tersedia dalam versi 2.1 dan yang lebih baru.
Mengingat iterator ke awal urutan UTF-8, ia mengembalikan titik kode untuk urutan berikut tanpa mengubah nilai iterator.
template < typename octet_iterator>
utfchar32_t peek_next (octet_iterator it, octet_iterator end); octet_iterator : Iterator input.
it : Iterator yang menunjuk ke awal titik kode yang dikodekan UTF-8.
end : Akhir dari Urutan UTF-8 yang akan diproses. Jika it sama dengan end selama ekstraksi titik kode, pengecualian utf8::not_enough_room dilemparkan.
Nilai Pengembalian: Representasi 32 bit dari titik kode UTF-8 yang diproses.
Contoh Penggunaan:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = peek_next(w, twochars + 6 );
assert (cp == 0x65e5 );
assert (w == twochars); Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan.
Tersedia dalam versi 1.02 dan yang lebih baru.
Diberi referensi ke iterator yang menunjuk ke oktet dalam urutan UTF-8, itu mengurangi iterator sampai mencapai awal titik kode yang dikodekan UTF-8 sebelumnya dan mengembalikan representasi 32 bit dari titik kode.
template < typename octet_iterator>
utfchar32_t prior (octet_iterator& it, octet_iterator start); octet_iterator : Iterator dua arah.
it : Referensi yang menunjuk ke oktet dalam string yang dikodekan UTF-8. Setelah fungsi kembali, dikurangi untuk menunjuk ke awal titik kode sebelumnya.
start : Iterator ke awal urutan di mana pencarian awal titik kode dilakukan. Ini adalah tindakan keamanan untuk mencegah melewati awal string dalam pencarian oktet timah UTF-8.
Nilai Pengembalian: Representasi 32 bit dari titik kode sebelumnya.
Contoh Penggunaan:
char * twochars = " xe6x97xa5xd1x88 " ;
unsigned char * w = twochars + 3 ;
int cp = prior (w, twochars);
assert (cp == 0x65e5 );
assert (w == twochars); Fungsi ini memiliki dua tujuan: satu adalah dua iterate ke belakang melalui string yang dikodekan UTF-8. Perhatikan bahwa biasanya merupakan ide yang lebih baik untuk beralih ke depan, karena utf8::next lebih cepat. Tujuan kedua adalah untuk menemukan awal dari urutan UTF-8 jika kita memiliki posisi acak dalam suatu string. Perhatikan bahwa dalam hal ini utf8::prior mungkin tidak mendeteksi urutan UTF-8 yang tidak valid dalam beberapa skenario: misalnya jika ada oktet trail yang berlebihan, itu hanya akan melewatkannya.
it biasanya akan menunjuk ke awal titik kode, dan start akan menunjuk ke awal string untuk memastikan kami tidak mundur terlalu jauh. it menurun sampai menunjuk ke timah utf-8 octet, dan kemudian urutan UTF-8 dimulai dengan oktet itu diterjemahkan ke representasi 32 bit dan dikembalikan.
Dalam kasus start tercapai sebelum oktet timah UTF-8 dipukul, atau jika urutan UTF-8 yang tidak valid dimulai oleh oktet timbal, pengecualian invalid_utf8 dilemparkan.
Jika start sama it , pengecualian not_enough_room dilemparkan.
Tersedia dalam versi 1.0 dan yang lebih baru.
Memajukan iterator dengan jumlah titik kode yang ditentukan dalam urutan UTF-8.
template < typename octet_iterator, typename distance_type>
void advance (octet_iterator& it, distance_type n, octet_iterator end); octet_iterator : Iterator input.
distance_type : Jenis integral dapat dikonversi ke jenis perbedaan octet_iterator .
it : Referensi ke iterator yang menunjuk ke awal titik kode yang dikodekan UTF-8. Setelah fungsi kembali, bertambah untuk menunjuk ke titik kode berikut.
n : Jumlah Poin Kode it harus ditingkatkan. Nilai negatif berarti penurunan.
end : Batas urutan UTF-8 yang akan diproses. Jika n positif dan it sama dengan end selama ekstraksi titik kode, pengecualian utf8::not_enough_room dilemparkan. Jika n negatif dan it end sementara it menunjuk byte TA trail dari urutan UTF-8, pengecualian utf8::invalid_code_point dilemparkan.
Contoh Penggunaan:
char * twochars = " xe6x97xa5xd1x88 " ;
unsigned char * w = twochars;
advance (w, 2 , twochars + 6 );
assert (w == twochars + 5 );
advance (w, - 2 , twochars);
assert (w == twochars); Dalam hal titik kode yang tidak valid, pengecualian utf8::invalid_code_point dilemparkan.
Tersedia dalam versi 1.0 dan yang lebih baru.
Mengingat iterator ke dua titik kode yang dikodekan UTF-8 dalam urutan, mengembalikan jumlah titik kode di antara mereka.
template < typename octet_iterator>
typename std::iterator_traits<octet_iterator>::difference_type distance (octet_iterator first, octet_iterator last); octet_iterator : Iterator input.
first : Iterator ke awal titik kode yang dikodekan UTF-8.
last : Iterator ke "post-end" dari titik kode yang dikodekan UTF-8 terakhir dalam urutan yang kami coba tentukan panjangnya. Ini bisa menjadi awal dari titik kode baru, atau tidak.
Nilai pengembalian jarak antara iterator, dalam titik kode.
Contoh Penggunaan:
char * twochars = " xe6x97xa5xd1x88 " ;
size_t dist = utf8::distance(twochars, twochars + 5 );
assert (dist == 2 ); Fungsi ini digunakan untuk menemukan panjang (dalam titik kode) dari string yang dikodekan UTF-8. Alasannya disebut jarak , bukan, katakanlah, panjangnya terutama karena pengembang digunakan bahwa panjangnya adalah fungsi O (1). Menghitung panjang string UTF-8 adalah operasi linier, dan terlihat lebih baik untuk memodelkannya setelah algoritma std::distance .
Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan. Jika last tidak menunjuk ke masa lalu dari urutan UTF-8, pengecualian utf8::not_enough_room dilemparkan.
Tersedia dalam versi 1.0 dan yang lebih baru.
Mengubah string yang dikodekan UTF-16 ke UTF-8.
template < typename u16bit_iterator, typename octet_iterator>
octet_iterator utf16to8 (u16bit_iterator start, u16bit_iterator end, octet_iterator result); u16bit_iterator : Iterator input.
octet_iterator : Iterator output.
start : Iterator yang menunjuk ke awal string yang dikodekan UTF-16 untuk dikonversi.
end : Iterator yang menunjuk ke ujung-ujung string yang dikodekan UTF-16 untuk dikonversi.
result : Iterator output ke tempat di string UTF-8 di mana untuk menambahkan hasil konversi.
Nilai Pengembalian: Iterator yang menunjuk ke tempat itu setelah string UTF-8 yang ditambahkan.
Contoh Penggunaan:
unsigned short utf16string[] = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
vector< unsigned char > utf8result;
utf16to8 (utf16string, utf16string + 5 , back_inserter(utf8result));
assert (utf8result.size() == 10); Dalam hal urutan UTF-16 tidak valid, pengecualian utf8::invalid_utf16 dilemparkan.
Tersedia dalam versi 3.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 11.
Mengubah string yang dikodekan UTF-16 ke UTF-8.
std::string utf16to8 ( const std::u16string& s); s : String yang dikodekan UTF-16. Nilai Pengembalian: String yang dikodekan UTF-8.
Contoh Penggunaan:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
string u = utf16to8(utf16string);
assert (u.size() == 10); Dalam hal urutan UTF-16 tidak valid, pengecualian utf8::invalid_utf16 dilemparkan.
Tersedia dalam versi 3.2 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 17.
Mengubah string yang dikodekan UTF-16 ke UTF-8.
std::string utf16to8 (std::u16string_view s); s : String yang dikodekan UTF-16. Nilai Pengembalian: String yang dikodekan UTF-8.
Contoh Penggunaan:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u16string_view utf16stringview (u16string);
string u = utf16to8(utf16string);
assert (u.size() == 10); Dalam hal urutan UTF-16 tidak valid, pengecualian utf8::invalid_utf16 dilemparkan.
Tersedia dalam versi 4.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 20.
Mengubah string yang dikodekan UTF-16 ke UTF-8.
std::u8string utf16tou8 ( const std::u16string& s); s : String yang dikodekan UTF-16. Nilai Pengembalian: String yang dikodekan UTF-8.
Contoh Penggunaan:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u8string u = utf16tou8(utf16string);
assert (u.size() == 10); Dalam hal urutan UTF-16 tidak valid, pengecualian utf8::invalid_utf16 dilemparkan.
Tersedia dalam versi 4.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 20.
Mengubah string yang dikodekan UTF-16 ke UTF-8.
std::u8string utf16tou8 ( const std::u16string_view& s); s : String yang dikodekan UTF-16. Nilai Pengembalian: String yang dikodekan UTF-8.
Contoh Penggunaan:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u16string_view utf16stringview (u16string);
u8string u = utf16tou8(utf16string);
assert (u.size() == 10); Dalam hal urutan UTF-16 tidak valid, pengecualian utf8::invalid_utf16 dilemparkan.
Tersedia dalam versi 1.0 dan yang lebih baru.
Mengubah string yang dikodekan UTF-8 ke UTF-16
template < typename u16bit_iterator, typename octet_iterator>
u16bit_iterator utf8to16 (octet_iterator start, octet_iterator end, u16bit_iterator result); octet_iterator : Iterator input.
u16bit_iterator : Iterator output.
start : Iterator yang menunjuk ke awal string yang dikodekan UTF-8 untuk dikonversi. end : Iterator yang menunjuk ke ujung-ujung string yang dikodekan UTF-8 untuk dikonversi.
result : Iterator output ke tempat di string UTF-16 di mana untuk menambahkan hasil konversi.
Nilai Pengembalian: Iterator yang menunjuk ke tempat itu setelah string UTF-16 yang ditambahkan.
Contoh Penggunaan:
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 ); Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan. Jika end tidak menunjuk ke masa lalu dari urutan UTF-8, pengecualian utf8::not_enough_room dilemparkan.
Tersedia dalam versi 3.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 11.
Konversi string yang dikodekan UTF-8 ke UTF-16.
std::u16string utf8to16 ( const std::string& s); s : String yang dikodekan UTF-8 untuk dikonversi.
Nilai pengembalian: string yang dikodekan UTF-16
Contoh Penggunaan:
string utf8_with_surrogates = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
u16string utf16result = utf8to16(utf8_with_surrogates);
assert (utf16result.length() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e ); Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan.
Tersedia dalam versi 3.2 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 17.
Konversi string yang dikodekan UTF-8 ke UTF-16.
std::u16string utf8to16 (std::string_view s); s : String yang dikodekan UTF-8 untuk dikonversi.
Nilai pengembalian: string yang dikodekan UTF-16
Contoh Penggunaan:
string_view utf8_with_surrogates = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
u16string utf16result = utf8to16(utf8_with_surrogates);
assert (utf16result.length() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e ); Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan.
Tersedia dalam versi 4.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 20.
Konversi string yang dikodekan UTF-8 ke UTF-16.
std::u16string utf8to16 (std::u8string& s); s : String yang dikodekan UTF-8 untuk dikonversi.
Nilai pengembalian: string yang dikodekan UTF-16
Contoh Penggunaan:
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 ); Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan.
Tersedia dalam versi 4.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 20.
Konversi string yang dikodekan UTF-8 ke UTF-16.
std::u16string utf8to16 (std::u8string_view& s); s : String yang dikodekan UTF-8 untuk dikonversi.
Nilai pengembalian: string yang dikodekan UTF-16
Contoh Penggunaan:
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 ); Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan.
Tersedia dalam versi 1.0 dan yang lebih baru.
Mengubah string yang dikodekan UTF-32 ke UTF-8.
template < typename octet_iterator, typename u32bit_iterator>
octet_iterator utf32to8 (u32bit_iterator start, u32bit_iterator end, octet_iterator result); octet_iterator : Iterator output.
u32bit_iterator : Iterator input.
start : Iterator yang menunjuk ke awal string yang dikodekan UTF-32 untuk dikonversi.
end : Iterator yang menunjuk ke ujung-ujung string yang dikodekan UTF-32 untuk dikonversi.
result : Iterator output ke tempat di string UTF-8 di mana untuk menambahkan hasil konversi.
Nilai Pengembalian: Iterator yang menunjuk ke tempat itu setelah string UTF-8 yang ditambahkan.
Contoh Penggunaan:
int utf32string[] = { 0x448 , 0x65E5 , 0x10346 , 0 };
vector< unsigned char > utf8result;
utf32to8 (utf32string, utf32string + 3 , back_inserter(utf8result));
assert (utf8result.size() == 9); Dalam hal string UTF-32 yang tidak valid, pengecualian utf8::invalid_code_point dilemparkan.
Tersedia dalam versi 3.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 11.
Mengubah string yang dikodekan UTF-32 ke UTF-8.
std::string utf32to8 ( const std::u32string& s); s : String yang dikodekan UTF-32.
Nilai Pengembalian: String yang dikodekan UTF-8.
Contoh Penggunaan:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); Dalam hal string UTF-32 yang tidak valid, pengecualian utf8::invalid_code_point dilemparkan.
Tersedia dalam versi 4.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 20.
Mengubah string yang dikodekan UTF-32 ke UTF-8.
std::u8string utf32to8 ( const std::u32string& s); s : String yang dikodekan UTF-32.
Nilai Pengembalian: String yang dikodekan UTF-8.
Contoh Penggunaan:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u8string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); Dalam hal string UTF-32 yang tidak valid, pengecualian utf8::invalid_code_point dilemparkan.
Tersedia dalam versi 4.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 20.
Mengubah string yang dikodekan UTF-32 ke UTF-8.
std::u8string utf32to8 ( const std::u32string_view& s); s : String yang dikodekan UTF-32.
Nilai Pengembalian: String yang dikodekan UTF-8.
Contoh Penggunaan:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u32string_view utf32stringview (utf32string);
u8string utf8result = utf32to8(utf32stringview);
assert (utf8result.size() == 9); Dalam hal string UTF-32 yang tidak valid, pengecualian utf8::invalid_code_point dilemparkan.
Tersedia dalam versi 3.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 11.
Mengubah string yang dikodekan UTF-32 ke UTF-8.
std::string utf32to8 ( const std::u32string& s); s : String yang dikodekan UTF-32.
Nilai Pengembalian: String yang dikodekan UTF-8.
Contoh Penggunaan:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); Dalam hal string UTF-32 yang tidak valid, pengecualian utf8::invalid_code_point dilemparkan.
Tersedia dalam versi 3.2 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 17.
Mengubah string yang dikodekan UTF-32 ke UTF-8.
std::string utf32to8 (std::u32string_view s); s : String yang dikodekan UTF-32.
Nilai Pengembalian: String yang dikodekan UTF-8.
Contoh Penggunaan:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u32string_view utf32stringview (utf32string);
string utf8result = utf32to8(utf32stringview);
assert (utf8result.size() == 9); Dalam hal string UTF-32 yang tidak valid, pengecualian utf8::invalid_code_point dilemparkan.
Tersedia dalam versi 1.0 dan yang lebih baru.
Mengubah string yang dikodekan UTF-8 ke UTF-32.
template < typename octet_iterator, typename u32bit_iterator>
u32bit_iterator utf8to32 (octet_iterator start, octet_iterator end, u32bit_iterator result); octet_iterator : Iterator input.
u32bit_iterator : Iterator output.
start : Iterator yang menunjuk ke awal string yang dikodekan UTF-8 untuk dikonversi.
end : Iterator yang menunjuk ke ujung-ujung string yang dikodekan UTF-8 untuk dikonversi.
result : Iterator output ke tempat di string UTF-32 di mana untuk menambahkan hasil konversi.
Nilai Pengembalian: Iterator yang menunjuk ke tempat itu setelah string UTF-32 yang ditambahkan.
Contoh Penggunaan:
char * twochars = " xe6x97xa5xd1x88 " ;
vector< int > utf32result;
utf8to32 (twochars, twochars + 5 , back_inserter(utf32result));
assert (utf32result.size() == 2); Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan. Jika end tidak menunjuk ke masa lalu dari urutan UTF-8, pengecualian utf8::not_enough_room dilemparkan.
Tersedia dalam versi 4.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 20.
Mengubah string yang dikodekan UTF-8 ke UTF-32.
std::u32string utf8to32 ( const std::u8string& s); s : String yang dikodekan UTF-8. Nilai pengembalian: String yang dikodekan UTF-32.
Contoh Penggunaan:
const std::u8string* twochars = u8" xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan.
Tersedia dalam versi 4.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 20.
Mengubah string yang dikodekan UTF-8 ke UTF-32.
std::u32string utf8to32 ( const std::u8string_view& s); s : String yang dikodekan UTF-8. Nilai pengembalian: String yang dikodekan UTF-32.
Contoh Penggunaan:
const u8string* twochars = u8" xe6x97xa5xd1x88 " ;
const u8string_view stringview{twochars};
u32string utf32result = utf8to32(stringview);
assert (utf32result.size() == 2); Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan.
Tersedia dalam versi 3.0 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 11.
Mengubah string yang dikodekan UTF-8 ke UTF-32.
std::u32string utf8to32 ( const std::string& s); s : String yang dikodekan UTF-8. Nilai pengembalian: String yang dikodekan UTF-32.
Contoh Penggunaan:
const char * twochars = " xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan.
Tersedia dalam versi 3.2 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 17.
Mengubah string yang dikodekan UTF-8 ke UTF-32.
std::u32string utf8to32 (std::string_view s); s : String yang dikodekan UTF-8. Nilai pengembalian: String yang dikodekan UTF-32.
Contoh Penggunaan:
string_view twochars = " xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); Dalam hal urutan UTF-8 yang tidak valid, pengecualian utf8::invalid_utf8 dilemparkan.
Tersedia dalam versi 1.0 dan yang lebih baru.
Mendeteksi urutan yang tidak valid dalam string UTF-8.
template < typename octet_iterator>
octet_iterator find_invalid (octet_iterator start, octet_iterator end); octet_iterator : Iterator input.
start : Iterator yang menunjuk ke awal string UTF-8 untuk menguji validitas.
end : Iterator yang menunjuk ke ujung string UTF-8 untuk menguji validitas.
Nilai Pengembalian: Iterator yang menunjuk ke oktet tidak valid pertama di string UTF-8. Dalam kasus tidak ada yang ditemukan, sama dengan end .
Contoh Penggunaan:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
char * invalid = find_invalid(utf_invalid, utf_invalid + 6 );
assert (invalid == utf_invalid + 5 );Fungsi ini biasanya digunakan untuk memastikan string UTF-8 valid sebelum memprosesnya dengan fungsi lain. Sangat penting untuk menyebutnya jika sebelum melakukan operasi yang tidak terkendali di atasnya.
Tersedia dalam versi 4.0 dan yang lebih baru.
Mendeteksi urutan yang tidak valid dalam string UTF-8 gaya-C.
const char * find_invalid ( const char * str); str : String yang dikodekan UTF-8. Nilai pengembalian: Pointer ke oktet tidak valid pertama di string UTF-8. Dalam kasus tidak ada yang ditemukan, poin ke byte nol trailing.
Contoh Penggunaan:
const char * utf_invalid = " xe6x97xa5xd1x88xfa " ;
const char * invalid = find_invalid(utf_invalid);
assert ((invalid - utf_invalid) == 5);Fungsi ini biasanya digunakan untuk memastikan string UTF-8 valid sebelum memprosesnya dengan fungsi lain. Sangat penting untuk menyebutnya jika sebelum melakukan operasi yang tidak terkendali di atasnya.
Tersedia dalam versi 3.0 dan yang lebih baru. Sebelum 4.0 diperlukan kompiler C ++ 11; Persyaratan diangkat dengan 4.0
Mendeteksi urutan yang tidak valid dalam string UTF-8.
std:: size_t find_invalid ( const std::string& s); s : String yang dikodekan UTF-8. Nilai Pengembalian: Indeks oktet tidak valid pertama di string UTF-8. Dalam kasus tidak ada yang ditemukan, sama dengan std::string::npos .
Contoh Penggunaan:
string utf_invalid = " xe6x97xa5xd1x88xfa " ;
auto invalid = find_invalid(utf_invalid);
assert (invalid == 5 );Fungsi ini biasanya digunakan untuk memastikan string UTF-8 valid sebelum memprosesnya dengan fungsi lain. Sangat penting untuk menyebutnya jika sebelum melakukan operasi yang tidak terkendali di atasnya.
Tersedia dalam versi 3.2 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 17.
Mendeteksi urutan yang tidak valid dalam string UTF-8.
std:: size_t find_invalid (std::string_view s); s : String yang dikodekan UTF-8. Nilai Pengembalian: Indeks oktet tidak valid pertama di string UTF-8. Jika tidak ada yang ditemukan, sama dengan std::string_view::npos .
Contoh Penggunaan:
string_view utf_invalid = " xe6x97xa5xd1x88xfa " ;
auto invalid = find_invalid(utf_invalid);
assert (invalid == 5 );Fungsi ini biasanya digunakan untuk memastikan string UTF-8 valid sebelum memprosesnya dengan fungsi lain. Sangat penting untuk menyebutnya jika sebelum melakukan operasi yang tidak terkendali di atasnya.
Tersedia dalam versi 1.0 dan yang lebih baru.
Memeriksa apakah urutan oktet adalah string UTF-8 yang valid.
template < typename octet_iterator>
bool is_valid (octet_iterator start, octet_iterator end); octet_iterator : Iterator input.
start : Iterator yang menunjuk ke awal string UTF-8 untuk menguji validitas.
end : Iterator yang menunjuk ke ujung string UTF-8 untuk menguji validitas.
Nilai Pengembalian: true jika urutannya adalah string UTF-8 yang valid; false jika tidak.
Contoh Penggunaan:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid, utf_invalid + 6 );
assert (bvalid == false ); is_valid adalah steno untuk find_invalid(start, end) == end; . Anda mungkin ingin menggunakannya untuk memastikan bahwa urutan byte adalah string UTF-8 yang valid tanpa perlu mengetahui di mana ia gagal jika tidak valid.
Tersedia dalam versi 4.0 dan yang lebih baru.
Periksa apakah string gaya-C berisi teks yang dikodekan UTF-8 yang valid.
bool is_valid ( const char * str); str : String yang dikodekan UTF-8.
Nilai Pengembalian: true jika string berisi teks yang dikodekan UTF-8 yang valid; false jika tidak.
Contoh Penggunaan:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Anda mungkin ingin menggunakan is_valid untuk memastikan bahwa string berisi teks UTF-8 yang valid tanpa perlu mengetahui di mana ia gagal jika tidak valid.
Tersedia dalam versi 3.0 dan yang lebih baru. Sebelum 4.0 diperlukan kompiler C ++ 11; Persyaratan diangkat dengan 4.0
Periksa apakah objek string berisi teks yang dikodekan UTF-8 yang valid.
bool is_valid ( const std::string& s); s : String yang dikodekan UTF-8.
Nilai Pengembalian: true jika string berisi teks yang dikodekan UTF-8 yang valid; false jika tidak.
Contoh Penggunaan:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Anda mungkin ingin menggunakan is_valid untuk memastikan bahwa string berisi teks UTF-8 yang valid tanpa perlu mengetahui di mana ia gagal jika tidak valid.
Tersedia dalam versi 3.2 dan yang lebih baru. Membutuhkan kompiler yang sesuai dengan C ++ 17.
Periksa apakah objek string berisi teks yang dikodekan UTF-8 yang valid.
bool is_valid (std::string_view s); s : String yang dikodekan UTF-8.
Nilai Pengembalian: true jika string berisi teks yang dikodekan UTF-8 yang valid; false jika tidak.
Contoh Penggunaan:
string_view utf_invalid = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Anda mungkin ingin menggunakan is_valid untuk memastikan bahwa string berisi teks UTF-8 yang valid tanpa perlu mengetahui di mana ia gagal jika tidak valid.
Tersedia dalam versi 2.0 dan yang lebih baru.
Menggantikan semua urutan UTF-8 yang tidak valid dalam string dengan penanda penggantian.
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 : Iterator input.
output_iterator : Iterator output.
start : Iterator yang menunjuk ke awal string UTF-8 untuk mencari urutan UTF-8 yang tidak valid.
end : Iterator yang menunjuk ke ujung string UTF-8 untuk mencari urutan UTF-8 yang tidak valid.
out : Iterator output ke kisaran di mana hasil penggantian disimpan.
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.
