utfcpp
Release 4.0.6
لا يزال مطورو C ++ يفوتون طريقة سهلة ومحمولة للتعامل مع السلاسل المشفرة Unicode. معيار C ++ الأصلي (المعروف باسم C ++ 98 أو C ++ 03) هو غير مؤلف. تم إحراز بعض التقدم في الإصدارات اللاحقة من المعيار ، ولكن لا يزال من الصعب العمل مع Unicode باستخدام المرافق القياسية فقط.
توصلت إلى مكتبة عامة متوافقة مع C ++ 98 من أجل التعامل مع السلاسل المشفرة UTF-8. لأي شخص يستخدم للعمل مع خوارزميات STL والتكرار ، يجب أن يكون سهلاً وطبيعيًا للاستخدام. الرمز متاح بحرية لأي غرض - تحقق من الترخيص. تم استخدام المكتبة كثيرًا منذ الإصدار الأول في عام 2006 في مشاريع تجارية ومفتوحة المصدر وأثبتت أنها مستقرة ومفيدة.
هذه مكتبة رأس فقط والطريقة المدعومة لنشرها هي:
تم تقديم ملف cmakelist.txt في الأصل لأغراض الاختبار فقط ، لكن لسوء الحظ مع مرور الوقت ، قبلت المساهمات التي أضفت تثبيت الهدف. هذه ليست وسيلة مدعومة لتثبيت مكتبة UTFCPP وأنا أفكر في إزالة cmakelist.txt في إصدار مستقبلي.
لتوضيح استخدام المكتبة ، دعنا نبدأ ببرنامج صغير ولكنه كامل يفتح ملفًا يحتوي على نص مشفر UTF-8 ، ويقرأه سطرًا ، ويتحقق من كل سطر من تسلسل UTF-8 غير صالح ، ويحوله إلى UTF-16 الترميز والعودة إلى 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 ;
} في عينة الكود السابقة ، أجرينا في كل سطر اكتشاف تسلسل UTF-8 غير صالح مع find_invalid ؛ عدد الأحرف (بشكل أدق - عدد نقاط رمز Unicode ، بما في ذلك نهاية السطر وحتى BOM إذا كان هناك واحد) في كل سطر تم تحديده باستخدام utf8::distance ؛ أخيرًا ، قمنا بتحويل كل سطر إلى UTF-16 الترميز مع utf8to16 والعودة إلى UTF-8 مع utf16to8 .
لاحظ نمطًا مختلفًا من الاستخدام للمترجمين القدامى. على سبيل المثال ، هذه هي الطريقة التي نقوم بتحويلها سلسلة مشفرة UTF-8 إلى واحدة مشفرة UTF-16 مع برنامج التحويل البرمجي قبل-C ++ 11:
vector< unsigned short > utf16line;
utf8::utf8to16 (line.begin(), end_it, back_inserter(utf16line));مع مترجم أكثر حداثة ، ستبدو نفس العملية:
u16string utf16line = utf8::utf8to16(line); إذا أشار __cplusplus Macro إلى C ++ 11 أو في وقت لاحق ، فإن المكتبة تعرض API التي تأخذ في الاعتبار سلاسل Unicode القياسية C ++ وتحريك الدلالات. مع برنامج التحويل البرمجي الأقدم ، لا يزال من الممكن استخدام نفس الوظيفة ، بطريقة أقل ملاءمة قليلاً
في حال كنت لا تثق في الماكرو __cplusplus أو ، على سبيل المثال ، لا ترغب في تضمين وظائف المساعدة C ++ 11 حتى مع وجود برنامج التحويل البرمجي الحديث ، حدد UTF_CPP_CPLUSPLUS MACRO قبل تضمين utf8.h وتعيين قيمة للمعيار الذي تريد استخدامه - والقيم هي نفسها بالنسبة إلى __cplusplus macl. يمكن أن يكون هذا مفيدًا أيضًا مع المترجمين المحافظة في تعيين الماكرو __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() تعمل مع تكرارات الإدخال ، تمكنا من تمرير 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 غير صالح مع حرف استبدال Unicode. هناك وظيفة محملة تمكن المتصل من توفير طابع الاستبدال الخاص به.
تم تصميم المكتبة لتكون:
بالنسبة للبدائل والمقارنات ، أوصي بالمقال التالي: العالم الرهيب الرائع من C ++ لتشفير واجهات برمجة التطبيقات (مع بعض الصدأ) ، بقلم جينهيد مينيد. في المقالة ، تتم مقارنة هذه المكتبة مع:
يقدم المقال وجهة نظر المؤلف لجودة تصميم 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 إضافة كلمة واحدة أو كلمتين إلى التسلسل. في الممارسة العملية ، غالبًا ما تريد استخدام 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 : إشارة إلى Iterator يشير إلى بداية نقطة رمز مشفرة UTF-8. بعد إرجاع الوظيفة ، يتم زيادة الإشارة إلى بداية نقطة الكود التالية.
end : نهاية تسلسل UTF-8 المراد معالجتها. إذا كان it مساوًا end أثناء استخراج نقطة الكود ، يتم طرح استثناء utf8::not_enough_room .
قيمة الإرجاع: تمثيل 32 بت من نقطة رمز UTF-8 المعالجة.
مثال على الاستخدام:
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 : إشارة إلى Iterator يشير إلى بداية نقطة رمز مشفرة UTF-16. بعد إرجاع الوظيفة ، يتم زيادة الإشارة إلى بداية نقطة الكود التالية.
end : نهاية تسلسل UTF-16 المراد معالجتها. إذا كان it مساوًا end أثناء استخراج نقطة الكود ، يتم طرح استثناء utf8::not_enough_room .
قيمة الإرجاع: تمثيل 32 بت من نقطة رمز UTF-16 المعالجة.
مثال على الاستخدام:
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 المراد معالجتها. إذا كان it مساوًا end أثناء استخراج نقطة الكود ، يتم طرح استثناء utf8::not_enough_room .
قيمة الإرجاع: تمثيل 32 بت من نقطة رمز UTF-8 المعالجة.
مثال على الاستخدام:
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 وبعد ذلك.
بالنظر إلى إشارة إلى التكرار الذي يشير إلى Octet في تسلسل UTF-8 ، فإنه يقلل من التكرار حتى يصل إلى بداية نقطة الرمز المشفر في UTF-8 السابقة ويعيد تمثيل 32 بت من نقطة الرمز.
template < typename octet_iterator>
utfchar32_t prior (octet_iterator& it, octet_iterator start); octet_iterator : تكرار ثنائي الاتجاه.
it : مرجع يشير إلى Octet داخل سلسلة مشفرة UTF-8. بعد عودة الوظيفة ، يتم الانخفاض للإشارة إلى بداية نقطة الكود السابقة.
start : ايتراتور إلى بداية التسلسل حيث يتم إجراء البحث عن بداية نقطة الكود. إنه مقياس أمان لمنع تمرير بداية السلسلة في البحث عن Outf-8 Lead.
قيمة الإرجاع: تمثيل 32 بت من نقطة الكود السابقة.
مثال على الاستخدام:
char * twochars = " xe6x97xa5xd1x88 " ;
unsigned char * w = twochars + 3 ;
int cp = prior (w, twochars);
assert (cp == 0x65e5 );
assert (w == twochars); تحتوي هذه الوظيفة على غرضان: أحدهما هو اثنين من التكرار للخلف من خلال سلسلة مشفرة UTF-8. لاحظ أنه عادة ما تكون فكرة أفضل للتكرار إلى الأمام بدلاً من ذلك ، لأن utf8::next أسرع. والغرض الثاني هو العثور على بداية لتسلسل UTF-8 إذا كان لدينا موضع عشوائي داخل السلسلة. لاحظ أنه في هذه الحالة ، لا يجوز utf8::prior اكتشاف تسلسل UTF-8 غير صالح في بعض السيناريوهات: على سبيل المثال ، إذا كان هناك ثمانيات غير ضرورية ، فسيتخطيها فقط.
it عادة إلى بداية نقطة الكود ، وستشير start إلى بداية السلسلة للتأكد من أننا لا نعود إلى الوراء. it انخفاضه حتى يشير إلى Octet UTF-8 Lead ، ثم يتم فك تشفير تسلسل UTF-8 الذي يبدأ بهذا الثمينات إلى تمثيل 32 بت وإعادته.
في حالة start قبل ضرب Octet UTF-8 ، أو إذا تم بدء تسلسل UTF-8 غير صالح بواسطة Octet Lead ، يتم إلقاء استثناء 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 : إشارة إلى Iterator يشير إلى بداية نقطة رمز مشفرة UTF-8. بعد عودة الوظيفة ، يتم زيادة الإشارة إلى نقطة الكود التالية.
n : عدد نقاط الكود it أن يكون متقدمًا. القيمة السالبة تعني الانخفاض.
end : الحد من تسلسل UTF-8 المراد معالجته. إذا كان n إيجابيًا it مساوياً end أثناء استخراج نقطة الكود ، يتم طرح استثناء utf8::not_enough_room . إذا كان n سلبيًا it إلى end بينما it بايت TA Trail لتسلسل UTF-8 ، يتم طرح استثناء 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 وبعد ذلك.
بالنظر إلى التكرار إلى نقطتين من رمز 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 حيث يتم إلحاق نتيجة التحويل.
قيمة الإرجاع: يشير مؤلف مؤلف إلى المكان بعد سلسلة 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 حيث يتم إلحاق نتيجة التحويل.
قيمة الإرجاع: يشير مؤكرات إلى المكان بعد سلسلة UTF-16 الملحقة.
مثال على الاستخدام:
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 حيث يتم إلحاق نتيجة التحويل.
قيمة الإرجاع: يشير مؤلف مؤلف إلى المكان بعد سلسلة 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 حيث يتم إلحاق نتيجة التحويل.
قيمة الإرجاع: يشير مؤكرات إلى المكان بعد سلسلة 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 وبعد ذلك.
يكتشف تسلسلًا غير صالح داخل سلسلة UTF-8 على غرار C.
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 لاختبار الصلاحية.
قيمة الإرجاع: true إذا كان التسلسل عبارة عن سلسلة UTF-8 صالحة ؛ 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.
قيمة الإرجاع: true إذا كانت السلسلة تحتوي على نص مشفر UTF-8 صالح ؛ 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.
قيمة الإرجاع: true إذا كانت السلسلة تحتوي على نص مشفر UTF-8 صالح ؛ 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.
قيمة الإرجاع: true إذا كانت السلسلة تحتوي على نص مشفر UTF-8 صالح ؛ 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.
