utfcpp
Release 4.0.6
Les développeurs C ++ manquent toujours une manière facile et portable de gérer les chaînes codées Unicode. La norme C ++ d'origine (connue sous le nom de C ++ 98 ou C ++ 03) est Agnostique Unicode. Certains progrès ont été réalisés dans les dernières éditions de la norme, mais il est toujours difficile de travailler avec Unicode en utilisant uniquement les installations standard.
J'ai trouvé une petite bibliothèque générique compatible C ++ 98 afin de gérer les chaînes codées UTF-8. Pour quiconque travaillait avec des algorithmes STL et des itérateurs, il devrait être facile et naturel à utiliser. Le code est disponible gratuitement à quelque fin que ce soit - consultez la licence. La bibliothèque a été beaucoup utilisée depuis la première version en 2006 à la fois dans des projets commerciaux et open-source et s'est avérée stable et utile.
Il s'agit d'une bibliothèque d'en-tête uniquement et la manière prise en charge de le déployer est:
Le fichier cMakelist.txt a été initialement conçu à des fins de test uniquement, mais malheureusement, au fil du temps, j'ai accepté des contributions qui ont ajouté la cible d'installation. Ce n'est pas un moyen pris en charge d'installer la bibliothèque UTFCPP et j'envisage de supprimer le CMakelist.txt dans une future version.
Pour illustrer l'utilisation de la bibliothèque, commençons par un programme petit mais complet qui ouvre un fichier contenant du texte codé UTF-8, le lit ligne par ligne, vérifie chaque ligne pour les séquences d'octets UTF-8 non valides et le convertit en encodage UTF-16 et retour à 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 ;
} Dans l'échantillon de code précédent, pour chaque ligne, nous avons effectué une détection de séquences UTF-8 non valides avec find_invalid ; Le nombre de caractères (plus précisément - le nombre de points de code Unicode, y compris la fin de la ligne et même la bom s'il y en a un) dans chaque ligne a été déterminé avec une utilisation de utf8::distance ; Enfin, nous avons converti chaque ligne en codage UTF-16 avec utf8to16 et de retour en UTF-8 avec utf16to8 .
Notez un modèle d'utilisation différent pour les anciens compilateurs. Par exemple, c'est ainsi que nous convertissons une chaîne codée UTF-8 en un UTF-16 encodé avec un compilateur pré - C ++ 11:
vector< unsigned short > utf16line;
utf8::utf8to16 (line.begin(), end_it, back_inserter(utf16line));Avec un compilateur plus moderne, la même opération ressemblerait:
u16string utf16line = utf8::utf8to16(line); Si la macro __cplusplus pointe vers un C ++ 11 ou version ultérieure, la bibliothèque expose l'API qui prend en compte les chaînes UNICODS standard C ++ et déplacer la sémantique. Avec un compilateur plus ancien, il est toujours possible d'utiliser les mêmes fonctionnalités, juste une manière un peu moins pratique
Dans le cas où vous ne faites pas confiance à la macro __cplusplus ou, par exemple, ne souhaitez pas inclure les fonctions d'assistance C ++ 11 même avec un compilateur moderne, définissez UTF_CPP_CPLUSPLUS avant d'inclure utf8.h et affectez-lui une valeur pour la norme que vous souhaitez utiliser - les valeurs sont les mêmes que pour le macro __cplusplus . Cela peut également être utile avec les compilateurs qui sont conservateurs dans la définition de la macro __cplusplus , même s'ils ont un bon support pour une édition standard récente - Visual C ++ de Microsoft en est un exemple.
Voici une fonction qui vérifie si le contenu d'un fichier est un texte codé UTF-8 valide sans lire le contenu dans la mémoire:
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);
} Étant donné que la fonction utf8::is_valid() fonctionne avec les itérateurs d'entrée, nous avons pu it passer un istreambuf_iterator et lire le contenu du fichier directement sans le charger d'abord dans la mémoire.
Notez que d'autres fonctions qui prennent des arguments d'itérateur d'entrée peuvent être utilisées de la même manière. Par exemple, pour lire le contenu d'un fichier texte codé UTF-8 et convertir le texte en UTF-16, faites quelque chose comme:
utf8::utf8to16 (it, eos, back_inserter(u16string));Si nous avons du texte qui contient "probablement" du texte encodé UTF-8 et que nous voulons remplacer toute séquence UTF-8 non valide par un caractère de remplacement, quelque chose comme la fonction suivante peut être utilisée:
void fix_utf8_string (std::string& str)
{
std::string temp;
utf8::replace_invalid (str. begin (), str. end (), back_inserter (temp));
str = temp;
}La fonction remplacera toute séquence UTF-8 non valide par un caractère de remplacement Unicode. Il existe une fonction surchargée qui permet à l'appelant de fournir son propre caractère de remplacement.
La bibliothèque a été conçue pour être:
Pour les alternatives et les comparaisons, je recommande l'article suivant: Le monde merveilleusement terrible de C et C ++ codant les API (avec une certaine rouille), par Jeanheyd Meneide. Dans l'article, cette bibliothèque est comparée à:
L'article présente le point de vue de l'auteur sur la qualité de la conception de l'API, mais aussi quelques repères de vitesse.
Disponible dans la version 1.0 et plus tard.
Encode un point de code 32 bits en tant que séquence UTF-8 d'octets et ajoute la séquence vers une chaîne UTF-8.
template < typename octet_iterator>
octet_iterator append ( utfchar32_t cp, octet_iterator result); octet_iterator : un itérateur de sortie.
cp : un entier 32 bits représentant un point de code pour ajouter à la séquence.
result : un itérateur de sortie à la place dans la séquence où ajouter le point de code.
Valeur de retour: un itérateur pointant vers l'endroit après la séquence nouvellement annexée.
Exemple d'utilisation:
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 ); Notez que append n'attribue aucune mémoire - c'est le fardeau de l'appelant pour s'assurer qu'il y a suffisamment de mémoire allouée à l'opération. Pour rendre les choses plus intéressantes, append peut ajouter entre 1 et 4 octets à la séquence. En pratique, vous voudriez le plus souvent utiliser std::back_inserter pour vous assurer que la mémoire nécessaire est allouée.
Dans le cas d'un point de code non valide, une exception utf8::invalid_code_point est lancée.
Disponible dans la version 3.0 et plus tard. Avant 4.0, il nécessitait un compilateur C ++ 11; L'exigence est levée avec 4.0.
Encode un point de code 32 bits en tant que séquence UTF-8 d'octets et ajoute la séquence vers une chaîne UTF-8.
void append ( utfchar32_t cp, std::string& s); cp : un point de code pour ajouter à la chaîne.
s : une chaîne codée UTF-8 pour ajouter le point de code vers.
Exemple d'utilisation:
std::string u;
append ( 0x0448 , u);
assert (u[ 0 ] == char ( 0xd1 ) && u[1] == char( 0x88 ) && u.length() == 2); Dans le cas d'un point de code non valide, une exception utf8::invalid_code_point est lancée.
Disponible dans la version 4.0 et plus tard.
Encode un point de code 32 bits en tant que séquence UTF-16 de mots et ajoute la séquence vers une chaîne UTF-16.
template < typename word_iterator>
word_iterator append16 ( utfchar32_t cp, word_iterator result); word_iterator : un itérateur de sortie.
cp : un entier 32 bits représentant un point de code pour ajouter à la séquence.
result : un itérateur de sortie à la place dans la séquence où ajouter le point de code.
Valeur de retour: un itérateur pointant vers l'endroit après la séquence nouvellement annexée.
Exemple d'utilisation:
unsigned short u[ 2 ] = { 0 , 0 };
unsigned short * end = append16( 0x0448 , u);
assert (u[ 0 ] == 0x0448 && u[ 1 ] == 0 ); Notez que append16 n'attribue aucune mémoire - c'est le fardeau de l'appelant pour s'assurer qu'il y a suffisamment de mémoire allouée à l'opération. Pour rendre les choses plus intéressantes, append16 peut ajouter un ou deux mots à la séquence. En pratique, vous voudriez le plus souvent utiliser std::back_inserter pour vous assurer que la mémoire nécessaire est allouée.
Dans le cas d'un point de code non valide, une exception utf8::invalid_code_point est lancée.
Disponible dans la version 4.0 et plus tard. Nécessite un compilateur conforme C ++ 11.
Encode un point de code 32 bits en tant que séquence UTF-16 de mots et ajoute la séquence vers une chaîne UTF-16.
void append ( utfchar32_t cp, std::u16string& s); cp : un point de code pour ajouter à la chaîne.
s : une chaîne codée UTF-16 pour ajouter le point de code vers.
Exemple d'utilisation:
std::u16string u;
append ( 0x0448 , u);
assert (u[ 0 ] == 0x0448 && u.length() == 1); Dans le cas d'un point de code non valide, une exception utf8::invalid_code_point est lancée.
Disponible dans la version 1.0 et plus tard.
Compte tenu de l'itérateur au début de la séquence UTF-8, il renvoie le point de code et déplace l'itérateur à la position suivante.
template < typename octet_iterator>
utfchar32_t next (octet_iterator& it, octet_iterator end); octet_iterator : un itérateur d'entrée.
it : Une référence à un itérateur pointant vers le début d'un point de code codé UTF-8. Après le retour de la fonction, il est incrémenté pour pointer vers le début du point de code suivant.
end : Fin de la séquence UTF-8 à traiter. it est égal à end lors de l'extraction d'un point de code, une exception utf8::not_enough_room est lancée.
Valeur de retour: la représentation 32 bits du point de code UTF-8 traité.
Exemple d'utilisation:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = next(w, twochars + 6 );
assert (cp == 0x65e5 );
assert (w == twochars + 3 );Cette fonction est généralement utilisée pour parcourir une chaîne codée UTF-8.
Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée.
Disponible dans la version 4.0 et plus tard.
Compte tenu de l'itérateur au début de la séquence UTF-16, il renvoie le point de code et déplace l'itérateur à la position suivante.
template < typename word_iterator>
utfchar32_t next16 (word_iterator& it, word_iterator end); word_iterator : un itérateur d'entrée.
it : Une référence à un itérateur pointant vers le début d'un point de code codé UTF-16. Après le retour de la fonction, il est incrémenté pour pointer vers le début du point de code suivant.
end : Fin de la séquence UTF-16 à traiter. it est égal à end lors de l'extraction d'un point de code, une exception utf8::not_enough_room est lancée.
Valeur de retour: la représentation 32 bits du point de code UTF-16 traité.
Exemple d'utilisation:
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 );Cette fonction est généralement utilisée pour parcourir une chaîne codée UTF-16.
Dans le cas d'une séquence UTF-16 non valide, une exception utf8::invalid_utf8 est lancée.
Disponible dans la version 2.1 et plus tard.
Compte tenu de l'itérateur au début de la séquence UTF-8, il renvoie le point de code pour la séquence suivante sans modifier la valeur de l'itérateur.
template < typename octet_iterator>
utfchar32_t peek_next (octet_iterator it, octet_iterator end); octet_iterator : un itérateur d'entrée.
it : Un itérateur pointant vers le début d'un point de code codé UTF-8.
end : Fin de la séquence UTF-8 à traiter. it est égal à end lors de l'extraction d'un point de code, une exception utf8::not_enough_room est lancée.
Valeur de retour: la représentation 32 bits du point de code UTF-8 traité.
Exemple d'utilisation:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = peek_next(w, twochars + 6 );
assert (cp == 0x65e5 );
assert (w == twochars); Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée.
Disponible dans la version 1.02 et plus tard.
Étant donné une référence à un itérateur pointant vers un octet dans une séquence UTF-8, il diminue l'itérateur jusqu'à ce qu'il atteigne le début du point de code codé UTF-8 précédent et renvoie la représentation de 32 bits du point de code.
template < typename octet_iterator>
utfchar32_t prior (octet_iterator& it, octet_iterator start); octet_iterator : un itérateur bidirectionnel.
it : une référence pointant vers un octet dans une chaîne codée UTF-8. Après le retour de la fonction, il est décrémenté pour pointer vers le début du point de code précédent.
start : un itérateur au début de la séquence où la recherche du début d'un point de code est effectuée. Il s'agit d'une mesure de sécurité pour éviter de passer le début de la chaîne dans la recherche d'un octet de plomb UTF-8.
Valeur de retour: la représentation 32 bits du point de code précédent.
Exemple d'utilisation:
char * twochars = " xe6x97xa5xd1x88 " ;
unsigned char * w = twochars + 3 ;
int cp = prior (w, twochars);
assert (cp == 0x65e5 );
assert (w == twochars); Cette fonction a deux objectifs: l'une est deux itération vers l'arrière via une chaîne codée UTF-8. Notez que c'est généralement une meilleure idée d'itérer vers l'avant à la place, car utf8::next est plus rapide. Le deuxième objectif est de trouver un début d'une séquence UTF-8 si nous avons une position aléatoire dans une chaîne. Notez que dans ce cas utf8::prior peut ne pas détecter une séquence UTF-8 non valide dans certains scénarios: par exemple s'il y a des octets de sentier superflus, il les sautera.
it pointera généralement vers le début d'un point de code, et start le début du début de la chaîne pour nous assurer que nous ne reculaes pas trop loin. it est diminué jusqu'à ce qu'il pointe vers un octant UTF-8 lead, puis la séquence UTF-8 commençant par cet octet est décodée en représentation 32 bits et retournée.
Dans le cas où start est atteint avant qu'un octet de plomb UTF-8 ne soit touché, ou si une séquence UTF-8 non valide est lancée par l'octet de plomb, une exception invalid_utf8 est lancée.
En cas de start , une exception not_enough_room est it .
Disponible dans la version 1.0 et plus tard.
Avance un itérateur par le nombre spécifié de points de code dans une séquence UTF-8.
template < typename octet_iterator, typename distance_type>
void advance (octet_iterator& it, distance_type n, octet_iterator end); octet_iterator : un itérateur d'entrée.
distance_type : un type intégral convertible en type de différence d' octet_iterator .
it : Une référence à un itérateur pointant vers le début d'un point de code codé UTF-8. Une fois la fonction renvoyée, il est incrémenté pour pointer vers le NTh Point de code suivant.
n : Nombre de points de code it doit être avancé. Une valeur négative signifie une diminution.
end : limite de la séquence UTF-8 à traiter. Si n est positif et it est égal à end lors de l'extraction d'un point de code, une exception utf8::not_enough_room est lancée. Si n est négatif et it atteint end tandis it pointe l'octet TA de trail d'une séquence UTF-8, une exception utf8::invalid_code_point est lancée.
Exemple d'utilisation:
char * twochars = " xe6x97xa5xd1x88 " ;
unsigned char * w = twochars;
advance (w, 2 , twochars + 6 );
assert (w == twochars + 5 );
advance (w, - 2 , twochars);
assert (w == twochars); Dans le cas d'un point de code non valide, une exception utf8::invalid_code_point est lancée.
Disponible dans la version 1.0 et plus tard.
Étant donné les itérateurs à deux points de code codés UTF-8 dans une séquence, renvoie le nombre de points de code entre eux.
template < typename octet_iterator>
typename std::iterator_traits<octet_iterator>::difference_type distance (octet_iterator first, octet_iterator last); octet_iterator : un itérateur d'entrée.
first : un itérateur au début d'un point de code encodé UTF-8.
last : un itérateur d'un "post-end" du dernier point de code codé UTF-8 dans la séquence que nous essayons de déterminer la longueur. Cela peut être le début d'un nouveau point de code, ou non.
Valeur de retour La distance entre les itérateurs, en points de code.
Exemple d'utilisation:
char * twochars = " xe6x97xa5xd1x88 " ;
size_t dist = utf8::distance(twochars, twochars + 5 );
assert (dist == 2 ); Cette fonction est utilisée pour trouver la longueur (en points de code) d'une chaîne codée UTF-8. La raison pour laquelle il est appelé la distance , plutôt que, par exemple, la longueur est principalement parce que les développeurs sont utilisés que la longueur est une fonction O (1). Le calcul de la longueur d'une chaîne UTF-8 est une opération linéaire, et il semblait mieux de le modéliser après l'algorithme std::distance .
Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée. Si last ne pointe pas vers le passé d'une séquence UTF-8, une exception utf8::not_enough_room est lancée.
Disponible dans la version 1.0 et plus tard.
Convertit une chaîne codée UTF-16 en UTF-8.
template < typename u16bit_iterator, typename octet_iterator>
octet_iterator utf16to8 (u16bit_iterator start, u16bit_iterator end, octet_iterator result); u16bit_iterator : un itérateur d'entrée.
octet_iterator : un itérateur de sortie.
start : un itérateur pointant vers le début de la chaîne codée UTF-16 à convertir.
end : un itérateur pointant vers la fin de la chaîne codée UTF-16 à convertir.
result : un itérateur de sortie à la place dans la chaîne UTF-8 où ajouter le résultat de la conversion.
Valeur de retour: un itérateur pointant vers l'endroit après la chaîne UTF-8 annexe.
Exemple d'utilisation:
unsigned short utf16string[] = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
vector< unsigned char > utf8result;
utf16to8 (utf16string, utf16string + 5 , back_inserter(utf8result));
assert (utf8result.size() == 10); En cas de séquence UTF-16 non valide, une exception utf8::invalid_utf16 est lancée.
Disponible dans la version 3.0 et plus tard. Nécessite un compilateur conforme C ++ 11.
Convertit une chaîne codée UTF-16 en UTF-8.
std::string utf16to8 ( const std::u16string& s); s : une chaîne codée UTF-16. Valeur de retour: une chaîne codée UTF-8.
Exemple d'utilisation:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
string u = utf16to8(utf16string);
assert (u.size() == 10); En cas de séquence UTF-16 non valide, une exception utf8::invalid_utf16 est lancée.
Disponible dans la version 3.2 et plus tard. Nécessite un compilateur conforme C ++ 17.
Convertit une chaîne codée UTF-16 en UTF-8.
std::string utf16to8 (std::u16string_view s); s : une chaîne codée UTF-16. Valeur de retour: une chaîne codée UTF-8.
Exemple d'utilisation:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u16string_view utf16stringview (u16string);
string u = utf16to8(utf16string);
assert (u.size() == 10); En cas de séquence UTF-16 non valide, une exception utf8::invalid_utf16 est lancée.
Disponible dans la version 4.0 et plus tard. Nécessite un compilateur conforme C ++ 20.
Convertit une chaîne codée UTF-16 en UTF-8.
std::u8string utf16tou8 ( const std::u16string& s); s : une chaîne codée UTF-16. Valeur de retour: une chaîne codée UTF-8.
Exemple d'utilisation:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u8string u = utf16tou8(utf16string);
assert (u.size() == 10); En cas de séquence UTF-16 non valide, une exception utf8::invalid_utf16 est lancée.
Disponible dans la version 4.0 et plus tard. Nécessite un compilateur conforme C ++ 20.
Convertit une chaîne codée UTF-16 en UTF-8.
std::u8string utf16tou8 ( const std::u16string_view& s); s : une chaîne codée UTF-16. Valeur de retour: une chaîne codée UTF-8.
Exemple d'utilisation:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u16string_view utf16stringview (u16string);
u8string u = utf16tou8(utf16string);
assert (u.size() == 10); En cas de séquence UTF-16 non valide, une exception utf8::invalid_utf16 est lancée.
Disponible dans la version 1.0 et plus tard.
Convertit une chaîne codée UTF-8 en UTF-16
template < typename u16bit_iterator, typename octet_iterator>
u16bit_iterator utf8to16 (octet_iterator start, octet_iterator end, u16bit_iterator result); octet_iterator : un itérateur d'entrée.
u16bit_iterator : un itérateur de sortie.
start : un itérateur pointant vers le début de la chaîne codée UTF-8 à convertir. end : un itérateur pointant vers la fin de la chaîne codée UTF-8 à convertir.
result : un itérateur de sortie à la place de la chaîne UTF-16 où ajouter le résultat de la conversion.
Valeur de retour: un itérateur pointant vers l'endroit après la chaîne UTF-16 annexe.
Exemple d'utilisation:
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 ); Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée. Si end ne pointe pas vers le passé d'une séquence UTF-8, une exception utf8::not_enough_room est lancée.
Disponible dans la version 3.0 et plus tard. Nécessite un compilateur conforme C ++ 11.
Convertit une chaîne codée UTF-8 en UTF-16.
std::u16string utf8to16 ( const std::string& s); s : une chaîne codée UTF-8 à convertir.
Valeur de retour: une chaîne codée UTF-16
Exemple d'utilisation:
string utf8_with_surrogates = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
u16string utf16result = utf8to16(utf8_with_surrogates);
assert (utf16result.length() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e ); Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée.
Disponible dans la version 3.2 et plus tard. Nécessite un compilateur conforme C ++ 17.
Convertit une chaîne codée UTF-8 en UTF-16.
std::u16string utf8to16 (std::string_view s); s : une chaîne codée UTF-8 à convertir.
Valeur de retour: une chaîne codée UTF-16
Exemple d'utilisation:
string_view utf8_with_surrogates = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
u16string utf16result = utf8to16(utf8_with_surrogates);
assert (utf16result.length() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e ); Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée.
Disponible dans la version 4.0 et plus tard. Nécessite un compilateur conforme C ++ 20.
Convertit une chaîne codée UTF-8 en UTF-16.
std::u16string utf8to16 (std::u8string& s); s : une chaîne codée UTF-8 à convertir.
Valeur de retour: une chaîne codée UTF-16
Exemple d'utilisation:
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 ); Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée.
Disponible dans la version 4.0 et plus tard. Nécessite un compilateur conforme C ++ 20.
Convertit une chaîne codée UTF-8 en UTF-16.
std::u16string utf8to16 (std::u8string_view& s); s : une chaîne codée UTF-8 à convertir.
Valeur de retour: une chaîne codée UTF-16
Exemple d'utilisation:
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 ); Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée.
Disponible dans la version 1.0 et plus tard.
Convertit une chaîne codée UTF-32 en UTF-8.
template < typename octet_iterator, typename u32bit_iterator>
octet_iterator utf32to8 (u32bit_iterator start, u32bit_iterator end, octet_iterator result); octet_iterator : un itérateur de sortie.
u32bit_iterator : un itérateur d'entrée.
start : un itérateur pointant vers le début de la chaîne codée UTF-32 à convertir.
end : un itérateur pointant vers la fin de la chaîne codée UTF-32 à convertir.
result : un itérateur de sortie à la place dans la chaîne UTF-8 où ajouter le résultat de la conversion.
Valeur de retour: un itérateur pointant vers l'endroit après la chaîne UTF-8 annexe.
Exemple d'utilisation:
int utf32string[] = { 0x448 , 0x65E5 , 0x10346 , 0 };
vector< unsigned char > utf8result;
utf32to8 (utf32string, utf32string + 3 , back_inserter(utf8result));
assert (utf8result.size() == 9); En cas de chaîne UTF-32 non valide, une exception utf8::invalid_code_point est lancée.
Disponible dans la version 3.0 et plus tard. Nécessite un compilateur conforme C ++ 11.
Convertit une chaîne codée UTF-32 en UTF-8.
std::string utf32to8 ( const std::u32string& s); s : une chaîne codée UTF-32.
Valeur de retour: une chaîne codée UTF-8.
Exemple d'utilisation:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); En cas de chaîne UTF-32 non valide, une exception utf8::invalid_code_point est lancée.
Disponible dans la version 4.0 et plus tard. Nécessite un compilateur conforme C ++ 20.
Convertit une chaîne codée UTF-32 en UTF-8.
std::u8string utf32to8 ( const std::u32string& s); s : une chaîne codée UTF-32.
Valeur de retour: une chaîne codée UTF-8.
Exemple d'utilisation:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u8string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); En cas de chaîne UTF-32 non valide, une exception utf8::invalid_code_point est lancée.
Disponible dans la version 4.0 et plus tard. Nécessite un compilateur conforme C ++ 20.
Convertit une chaîne codée UTF-32 en UTF-8.
std::u8string utf32to8 ( const std::u32string_view& s); s : une chaîne codée UTF-32.
Valeur de retour: une chaîne codée UTF-8.
Exemple d'utilisation:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u32string_view utf32stringview (utf32string);
u8string utf8result = utf32to8(utf32stringview);
assert (utf8result.size() == 9); En cas de chaîne UTF-32 non valide, une exception utf8::invalid_code_point est lancée.
Disponible dans la version 3.0 et plus tard. Nécessite un compilateur conforme C ++ 11.
Convertit une chaîne codée UTF-32 en UTF-8.
std::string utf32to8 ( const std::u32string& s); s : une chaîne codée UTF-32.
Valeur de retour: une chaîne codée UTF-8.
Exemple d'utilisation:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); En cas de chaîne UTF-32 non valide, une exception utf8::invalid_code_point est lancée.
Disponible dans la version 3.2 et plus tard. Nécessite un compilateur conforme C ++ 17.
Convertit une chaîne codée UTF-32 en UTF-8.
std::string utf32to8 (std::u32string_view s); s : une chaîne codée UTF-32.
Valeur de retour: une chaîne codée UTF-8.
Exemple d'utilisation:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u32string_view utf32stringview (utf32string);
string utf8result = utf32to8(utf32stringview);
assert (utf8result.size() == 9); En cas de chaîne UTF-32 non valide, une exception utf8::invalid_code_point est lancée.
Disponible dans la version 1.0 et plus tard.
Convertit une chaîne codée UTF-8 en UTF-32.
template < typename octet_iterator, typename u32bit_iterator>
u32bit_iterator utf8to32 (octet_iterator start, octet_iterator end, u32bit_iterator result); octet_iterator : un itérateur d'entrée.
u32bit_iterator : un itérateur de sortie.
start : un itérateur pointant vers le début de la chaîne codée UTF-8 à convertir.
end : un itérateur pointant vers la fin de la chaîne codée UTF-8 à convertir.
result : un itérateur de sortie à la place de la chaîne UTF-32 où ajouter le résultat de la conversion.
Valeur de retour: un itérateur pointant vers l'endroit après la chaîne UTF-32 annexe.
Exemple d'utilisation:
char * twochars = " xe6x97xa5xd1x88 " ;
vector< int > utf32result;
utf8to32 (twochars, twochars + 5 , back_inserter(utf32result));
assert (utf32result.size() == 2); Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée. Si end ne pointe pas vers le passé d'une séquence UTF-8, une exception utf8::not_enough_room est lancée.
Disponible dans la version 4.0 et plus tard. Nécessite un compilateur conforme C ++ 20.
Convertit une chaîne codée UTF-8 en UTF-32.
std::u32string utf8to32 ( const std::u8string& s); s : une chaîne codée UTF-8. Valeur de retour: une chaîne codée UTF-32.
Exemple d'utilisation:
const std::u8string* twochars = u8" xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée.
Disponible dans la version 4.0 et plus tard. Nécessite un compilateur conforme C ++ 20.
Convertit une chaîne codée UTF-8 en UTF-32.
std::u32string utf8to32 ( const std::u8string_view& s); s : une chaîne codée UTF-8. Valeur de retour: une chaîne codée UTF-32.
Exemple d'utilisation:
const u8string* twochars = u8" xe6x97xa5xd1x88 " ;
const u8string_view stringview{twochars};
u32string utf32result = utf8to32(stringview);
assert (utf32result.size() == 2); Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée.
Disponible dans la version 3.0 et plus tard. Nécessite un compilateur conforme C ++ 11.
Convertit une chaîne codée UTF-8 en UTF-32.
std::u32string utf8to32 ( const std::string& s); s : une chaîne codée UTF-8. Valeur de retour: une chaîne codée UTF-32.
Exemple d'utilisation:
const char * twochars = " xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée.
Disponible dans la version 3.2 et plus tard. Nécessite un compilateur conforme C ++ 17.
Convertit une chaîne codée UTF-8 en UTF-32.
std::u32string utf8to32 (std::string_view s); s : une chaîne codée UTF-8. Valeur de retour: une chaîne codée UTF-32.
Exemple d'utilisation:
string_view twochars = " xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); Dans le cas d'une séquence UTF-8 non valide, une exception utf8::invalid_utf8 est lancée.
Disponible dans la version 1.0 et plus tard.
Détecte une séquence non valide dans une chaîne UTF-8.
template < typename octet_iterator>
octet_iterator find_invalid (octet_iterator start, octet_iterator end); octet_iterator : un itérateur d'entrée.
start : un itérateur pointant vers le début de la chaîne UTF-8 pour tester la validité.
end : un itérateur pointant vers la fin de la chaîne UTF-8 pour tester la validité.
Valeur de retour: un itérateur pointant vers le premier octet non valide de la chaîne UTF-8. Dans le cas où aucune n'a été trouvée, égale à end .
Exemple d'utilisation:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
char * invalid = find_invalid(utf_invalid, utf_invalid + 6 );
assert (invalid == utf_invalid + 5 );Cette fonction est généralement utilisée pour s'assurer qu'une chaîne UTF-8 est valide avant de la traiter avec d'autres fonctions. Il est particulièrement important de l'appeler si avant d'effectuer l'une des opérations incontrôlées .
Disponible dans la version 4.0 et plus tard.
Détecte une séquence non valide dans une chaîne UTF-8 de style C.
const char * find_invalid ( const char * str); str : une chaîne codée UTF-8. Valeur de retour: un pointeur vers le premier octet non valide de la chaîne UTF-8. Dans le cas où aucune n'a été trouvée, indique l'octet zéro.
Exemple d'utilisation:
const char * utf_invalid = " xe6x97xa5xd1x88xfa " ;
const char * invalid = find_invalid(utf_invalid);
assert ((invalid - utf_invalid) == 5);Cette fonction est généralement utilisée pour s'assurer qu'une chaîne UTF-8 est valide avant de la traiter avec d'autres fonctions. Il est particulièrement important de l'appeler si avant d'effectuer l'une des opérations incontrôlées .
Disponible dans la version 3.0 et plus tard. Avant 4.0, il nécessitait un compilateur C ++ 11; l'exigence est levée avec 4.0
Détecte une séquence non valide dans une chaîne UTF-8.
std:: size_t find_invalid ( const std::string& s); s : une chaîne codée UTF-8. Valeur de retour: l'index du premier octet non valide dans la chaîne UTF-8. Dans le cas où aucune n'a été trouvée, est égal std::string::npos .
Exemple d'utilisation:
string utf_invalid = " xe6x97xa5xd1x88xfa " ;
auto invalid = find_invalid(utf_invalid);
assert (invalid == 5 );Cette fonction est généralement utilisée pour s'assurer qu'une chaîne UTF-8 est valide avant de la traiter avec d'autres fonctions. Il est particulièrement important de l'appeler si avant d'effectuer l'une des opérations incontrôlées .
Disponible dans la version 3.2 et plus tard. Nécessite un compilateur conforme C ++ 17.
Détecte une séquence non valide dans une chaîne UTF-8.
std:: size_t find_invalid (std::string_view s); s : une chaîne codée UTF-8. Valeur de retour: l'index du premier octet non valide dans la chaîne UTF-8. Dans le cas où aucune n'a été trouvée, est égal std::string_view::npos .
Exemple d'utilisation:
string_view utf_invalid = " xe6x97xa5xd1x88xfa " ;
auto invalid = find_invalid(utf_invalid);
assert (invalid == 5 );Cette fonction est généralement utilisée pour s'assurer qu'une chaîne UTF-8 est valide avant de la traiter avec d'autres fonctions. Il est particulièrement important de l'appeler si avant d'effectuer l'une des opérations incontrôlées .
Disponible dans la version 1.0 et plus tard.
Vérifie si une séquence d'octets est une chaîne UTF-8 valide.
template < typename octet_iterator>
bool is_valid (octet_iterator start, octet_iterator end); octet_iterator : un itérateur d'entrée.
start : un itérateur pointant vers le début de la chaîne UTF-8 pour tester la validité.
end : un itérateur pointant vers la fin de la chaîne UTF-8 pour tester la validité.
Valeur de retour: true si la séquence est une chaîne UTF-8 valide; false sinon.
Exemple d'utilisation:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid, utf_invalid + 6 );
assert (bvalid == false ); is_valid est un raccourci pour find_invalid(start, end) == end; . Vous voudrez peut-être l'utiliser pour vous assurer qu'une séquence d'octets est une chaîne UTF-8 valide sans avoir besoin de savoir où il échoue s'il n'est pas valide.
Disponible dans la version 4.0 et plus tard.
Vérifie si une chaîne de style C contient un texte codé UTF-8 valide.
bool is_valid ( const char * str); str : une chaîne codée UTF-8.
Valeur de retour: true si la chaîne contient un texte codé UTF-8 valide; false sinon.
Exemple d'utilisation:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Vous voudrez peut-être utiliser is_valid pour vous assurer qu'une chaîne contient un texte UTF-8 valide sans avoir besoin de savoir où il échoue s'il n'est pas valide.
Disponible dans la version 3.0 et plus tard. Avant 4.0, il nécessitait un compilateur C ++ 11; l'exigence est levée avec 4.0
Vérifie si un objet String contient un texte codé UTF-8 valide.
bool is_valid ( const std::string& s); s : une chaîne codée UTF-8.
Valeur de retour: true si la chaîne contient un texte codé UTF-8 valide; false sinon.
Exemple d'utilisation:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Vous voudrez peut-être utiliser is_valid pour vous assurer qu'une chaîne contient un texte UTF-8 valide sans avoir besoin de savoir où il échoue s'il n'est pas valide.
Disponible dans la version 3.2 et plus tard. Nécessite un compilateur conforme C ++ 17.
Vérifie si un objet String contient un texte codé UTF-8 valide.
bool is_valid (std::string_view s); s : une chaîne codée UTF-8.
Valeur de retour: true si la chaîne contient un texte codé UTF-8 valide; false sinon.
Exemple d'utilisation:
string_view utf_invalid = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Vous voudrez peut-être utiliser is_valid pour vous assurer qu'une chaîne contient un texte UTF-8 valide sans avoir besoin de savoir où il échoue s'il n'est pas valide.
Disponible dans la version 2.0 et plus tard.
Remplace toutes les séquences UTF-8 non valides dans une chaîne par un marqueur de remplacement.
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 : un itérateur d'entrée.
output_iterator : un itérateur de sortie.
start : un itérateur pointant vers le début de la chaîne UTF-8 pour rechercher des séquences UTF-8 non valides.
end : un itérateur pointant vers la fin de la chaîne UTF-8 pour rechercher des séquences UTF-8 non valides.
out : Un itérateur de sortie dans la plage où le résultat du remplacement est stocké.
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.
