utfcpp
Release 4.0.6
Los desarrolladores de C ++ todavía pierden una forma fácil y portátil de manejar cadenas codificadas unicode. El estándar C ++ original (conocido como C ++ 98 o C ++ 03) es unicode agnóstico. Se han realizado algunos progresos en las ediciones posteriores del estándar, pero aún es difícil trabajar con Unicode usando solo las instalaciones estándar.
Se me ocurrieron una pequeña biblioteca genérica compatible C ++ 98 para manejar cadenas codificadas UTF-8. Para cualquiera solía trabajar con algoritmos e iteradores STL, debe ser fácil y natural de usar. El código está disponible gratuitamente para cualquier propósito: consulte la licencia. La biblioteca se ha utilizado mucho desde el primer lanzamiento en 2006 tanto en proyectos comerciales como de código abierto y demostró ser estable y útil.
Esta es una biblioteca solo de encabezado y la forma compatible de implementarla es:
El archivo cmakelist.txt se realizó originalmente solo para fines de prueba, pero desafortunadamente con el tiempo acepté contribuciones que agregaron el objetivo de instalación. Esta no es una forma compatible de instalar la biblioteca UTFCPP y estoy considerando eliminar la cmakelist.txt en una versión futura.
Para ilustrar el uso de la biblioteca, comencemos con un programa pequeño pero completo que abre un archivo que contenga texto codificado UTF-8, lea la línea por línea, verifica cada línea las secuencias de bytes UTF-8 inválidas y lo convierte en codificación UTF-16 y regresa a 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 ;
} En la muestra de código anterior, para cada línea realizamos una detección de secuencias UTF-8 inválidas con find_invalid ; El número de caracteres (más precisamente: el número de puntos de código Unicode, incluido el final de la línea e incluso nació si hay uno) en cada línea se determinó con un uso de utf8::distance ; Finalmente, hemos convertido cada línea a UTF-16 codificando con utf8to16 y regreso a UTF-8 con utf16to8 .
Tenga en cuenta un patrón diferente de uso para compiladores antiguos. Por ejemplo, así es como convertimos una cadena codificada UTF-8 a una UTF-16 codificada con un compilador Pre-C ++ 11:
vector< unsigned short > utf16line;
utf8::utf8to16 (line.begin(), end_it, back_inserter(utf16line));Con un compilador más moderno, la misma operación se vería como:
u16string utf16line = utf8::utf8to16(line); Si __cplusplus macro apunta a un C ++ 11 o posterior, la biblioteca expone API que tiene en cuenta las cadenas de unicode estándar de C ++ y mueve la semántica. Con un compilador más antiguo, aún es posible usar la misma funcionalidad, solo de una manera un poco menos conveniente
En caso de que no confíe en la macro __cplusplus o, por ejemplo, no desea incluir las funciones de C ++ 11 Helper, incluso con un compilador moderno, defina UTF_CPP_CPLUSPLUS Macro antes de incluir utf8.h y asignarle un valor para el estándar que desea usar: los valores son los mismos que para el Macro __cplusplus . Esto también puede ser útil con los compiladores que son conservadores para establecer la macro __cplusplus , incluso si tienen un buen soporte para una edición estándar reciente: Visual C ++ de Microsoft es un ejemplo.
Aquí hay una función que verifica si el contenido de un archivo es válido de texto codificado UTF-8 sin leer el contenido en la memoria:
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);
} Debido a que la función utf8::is_valid() funciona con iteradores de entrada, pudimos it un istreambuf_iterator y leer el contenido del archivo directamente sin cargarlo primero a la memoria.
Tenga en cuenta que otras funciones que toman argumentos de iterador de entrada pueden usarse de manera similar. Por ejemplo, para leer el contenido de un archivo de texto codificado UTF-8 y convertir el texto en UTF-16, solo haga algo como:
utf8::utf8to16 (it, eos, back_inserter(u16string));Si tenemos algún texto que "probablemente" contiene texto codificado UTF-8 y queremos reemplazar cualquier secuencia no válida de UTF-8 con un carácter de reemplazo, se puede usar algo como la siguiente función:
void fix_utf8_string (std::string& str)
{
std::string temp;
utf8::replace_invalid (str. begin (), str. end (), back_inserter (temp));
str = temp;
}La función reemplazará cualquier secuencia no válida de UTF-8 con un carácter de reemplazo de Unicode. Hay una función sobrecargada que permite a la persona que llama suministrar su propio carácter de reemplazo.
La biblioteca fue diseñada para ser:
Para alternativas y comparaciones, recomiendo el siguiente artículo: el mundo maravillosamente terrible de las API codificadoras de C y C ++ (con algo de óxido), por Jeanheyd Meneide. En el artículo, esta biblioteca se compara con:
El artículo presenta la visión del autor de la calidad del diseño de la API, pero también algunos puntos de referencia de velocidad.
Disponible en la versión 1.0 y más tarde.
Codifica un punto de código de 32 bits como una secuencia UTF-8 de octetos y agrega la secuencia a una cadena UTF-8.
template < typename octet_iterator>
octet_iterator append ( utfchar32_t cp, octet_iterator result); octet_iterator : un iterador de salida.
cp : un entero de 32 bits que representa un punto de código para agregar a la secuencia.
result : un iterador de salida al lugar en la secuencia donde agregar el punto de código.
Valor de retorno: un iterador que apunta al lugar después de la secuencia recién agregada.
Ejemplo de uso:
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 ); Tenga en cuenta que append no asigna memoria: es la carga de la persona que llama asegurarse de que haya suficiente memoria asignada para la operación. Para hacer las cosas más interesantes, append puede agregar en cualquier lugar entre 1 y 4 octetos a la secuencia. En la práctica, con mayor frecuencia querría usar std::back_inserter para garantizar que se asigne la memoria necesaria.
En el caso de un punto de código no válido, se lanza una excepción utf8::invalid_code_point .
Disponible en la versión 3.0 y más tarde. Antes de 4.0 requería un compilador C ++ 11; El requisito se levanta con 4.0.
Codifica un punto de código de 32 bits como una secuencia UTF-8 de octetos y agrega la secuencia a una cadena UTF-8.
void append ( utfchar32_t cp, std::string& s); cp : un código de código para agregar a la cadena.
s : una cadena codificada UTF-8 para agregar el punto de código.
Ejemplo de uso:
std::string u;
append ( 0x0448 , u);
assert (u[ 0 ] == char ( 0xd1 ) && u[1] == char( 0x88 ) && u.length() == 2); En el caso de un punto de código no válido, se lanza una excepción utf8::invalid_code_point .
Disponible en la versión 4.0 y más tarde.
Codifica un punto de código de 32 bits como una secuencia UTF-16 de palabras y agrega la secuencia a una cadena UTF-16.
template < typename word_iterator>
word_iterator append16 ( utfchar32_t cp, word_iterator result); word_iterator : un iterador de salida.
cp : un entero de 32 bits que representa un punto de código para agregar a la secuencia.
result : un iterador de salida al lugar en la secuencia donde agregar el punto de código.
Valor de retorno: un iterador que apunta al lugar después de la secuencia recién agregada.
Ejemplo de uso:
unsigned short u[ 2 ] = { 0 , 0 };
unsigned short * end = append16( 0x0448 , u);
assert (u[ 0 ] == 0x0448 && u[ 1 ] == 0 ); Tenga en cuenta que append16 no asigna ningún recuerdo: es la carga de la persona que llama asegurarse de que haya suficiente memoria asignada para la operación. Para hacer las cosas más interesantes, append16 puede agregar una o dos palabras a la secuencia. En la práctica, con mayor frecuencia querría usar std::back_inserter para garantizar que se asigne la memoria necesaria.
En el caso de un punto de código no válido, se lanza una excepción utf8::invalid_code_point .
Disponible en la versión 4.0 y más tarde. Requiere un compilador compatible con C ++ 11.
Codifica un punto de código de 32 bits como una secuencia UTF-16 de palabras y agrega la secuencia a una cadena UTF-16.
void append ( utfchar32_t cp, std::u16string& s); cp : un código de código para agregar a la cadena.
s : una cadena codificada UTF-16 para agregar el punto de código.
Ejemplo de uso:
std::u16string u;
append ( 0x0448 , u);
assert (u[ 0 ] == 0x0448 && u.length() == 1); En el caso de un punto de código no válido, se lanza una excepción utf8::invalid_code_point .
Disponible en la versión 1.0 y más tarde.
Dado el iterador al comienzo de la secuencia UTF-8, devuelve el punto de código y mueve el iterador a la siguiente posición.
template < typename octet_iterator>
utfchar32_t next (octet_iterator& it, octet_iterator end); octet_iterator : un iterador de entrada.
it : una referencia a un iterador que apunta al comienzo de un punto de código codificado UTF-8. Después de que la función regresa, se incrementa para apuntar al comienzo del siguiente punto de código.
end : Fin de la secuencia UTF-8 a procesar. Si it igual al end durante la extracción de un punto de código, se lanza una excepción utf8::not_enough_room .
Valor de retorno: la representación de 32 bits del punto de código UTF-8 procesado.
Ejemplo de uso:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = next(w, twochars + 6 );
assert (cp == 0x65e5 );
assert (w == twochars + 3 );Esta función se usa típicamente para iterar a través de una cadena codificada UTF-8.
En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 .
Disponible en la versión 4.0 y más tarde.
Dado el iterador al comienzo de la secuencia UTF-16, devuelve el punto de código y mueve el iterador a la siguiente posición.
template < typename word_iterator>
utfchar32_t next16 (word_iterator& it, word_iterator end); word_iterator : un iterador de entrada.
it : una referencia a un iterador que apunta al comienzo de un punto de código codificado UTF-16. Después de que la función regresa, se incrementa para apuntar al comienzo del siguiente punto de código.
end : Fin de la secuencia UTF-16 a procesar. Si it igual al end durante la extracción de un punto de código, se lanza una excepción utf8::not_enough_room .
Valor de retorno: la representación de 32 bits del punto de código UTF-16 procesado.
Ejemplo de uso:
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 );Esta función se usa típicamente para iterar a través de una cadena codificada UTF-16.
En el caso de una secuencia UTF-16 inválida, se lanza una excepción utf8::invalid_utf8 .
Disponible en la versión 2.1 y más tarde.
Dado el iterador al comienzo de la secuencia UTF-8, devuelve el punto de código para la siguiente secuencia sin cambiar el valor del iterador.
template < typename octet_iterator>
utfchar32_t peek_next (octet_iterator it, octet_iterator end); octet_iterator : un iterador de entrada.
it : un iterador que apunta al comienzo de un punto de código codificado UTF-8.
end : Fin de la secuencia UTF-8 a procesar. Si it igual al end durante la extracción de un punto de código, se lanza una excepción utf8::not_enough_room .
Valor de retorno: la representación de 32 bits del punto de código UTF-8 procesado.
Ejemplo de uso:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = peek_next(w, twochars + 6 );
assert (cp == 0x65e5 );
assert (w == twochars); En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 .
Disponible en la versión 1.02 y más tarde.
Dada una referencia a un iterador que apunta a un octeto en una secuencia UTF-8, disminuye el iterador hasta que llega al comienzo del punto de código codificado UTF-8 anterior y devuelve la representación de 32 bits del punto de código.
template < typename octet_iterator>
utfchar32_t prior (octet_iterator& it, octet_iterator start); octet_iterator : un iterador bidireccional.
it : una referencia que apunta a un octeto dentro de una cadena codificada UTF-8. Después de que la función regresa, se disminuye para apuntar al comienzo del punto de código anterior.
start : un iterador al comienzo de la secuencia donde se realiza la búsqueda del comienzo de un punto de código. Es una medida de seguridad para evitar pasar el comienzo de la cadena en la búsqueda de un octeto de plomo UTF-8.
Valor de retorno: la representación de 32 bits del punto de código anterior.
Ejemplo de uso:
char * twochars = " xe6x97xa5xd1x88 " ;
unsigned char * w = twochars + 3 ;
int cp = prior (w, twochars);
assert (cp == 0x65e5 );
assert (w == twochars); Esta función tiene dos propósitos: uno es dos iterados hacia atrás a través de una cadena codificada UTF-8. Tenga en cuenta que generalmente es una mejor idea iterar hacia adelante, ya que utf8::next es más rápido. El segundo propósito es encontrar un comienzo de una secuencia UTF-8 si tenemos una posición aleatoria dentro de una cadena. Tenga en cuenta que en ese caso utf8::prior puede no detectar una secuencia no válida de UTF-8 en algunos escenarios: por ejemplo, si hay octetos de senderos superfluos, simplemente los omitirá.
it lo general, apuntará al comienzo de un punto de código, y start apuntará al comienzo de la cadena para asegurarnos de que no vayamos demasiado lejos. it reduce hasta que apunta a un octeto UTF-8 principal, y luego la secuencia UTF-8 que comienza con ese octeto se decodifica a una representación de 32 bits y se devuelve.
En caso de que se alcance start antes de que se alcance un octeto de plomo UTF-8, o si el octeto de plomo inicia una secuencia UTF-8 inválida, se lanza una excepción invalid_utf8 .
En caso de que start it igual, se lanza una excepción not_enough_room .
Disponible en la versión 1.0 y más tarde.
Avanza un iterador por el número especificado de puntos de código dentro de una secuencia UTF-8.
template < typename octet_iterator, typename distance_type>
void advance (octet_iterator& it, distance_type n, octet_iterator end); octet_iterator : un iterador de entrada.
distance_type : un tipo integral convertible para el tipo de diferencia de octet_iterator .
it : una referencia a un iterador que apunta al comienzo de un punto de código codificado UTF-8. Después de que la función regresa, se incrementa para señalar el enésimo punto de código siguiente.
n : Número de puntos de código it avanzar. Un valor negativo significa disminución.
end : Límite de la secuencia UTF-8 a procesar. Si n es positivo y it igual al end durante la extracción de un punto de código, se lanza una excepción utf8::not_enough_room . Si n es negativo y it al end mientras it a un byte de trail de una secuencia UTF-8, se lanza una excepción utf8::invalid_code_point .
Ejemplo de uso:
char * twochars = " xe6x97xa5xd1x88 " ;
unsigned char * w = twochars;
advance (w, 2 , twochars + 6 );
assert (w == twochars + 5 );
advance (w, - 2 , twochars);
assert (w == twochars); En el caso de un punto de código no válido, se lanza una excepción utf8::invalid_code_point .
Disponible en la versión 1.0 y más tarde.
Dados los iteradores a dos puntos de código codificados UTF-8 en una secuencia, devuelve el número de puntos de código entre ellos.
template < typename octet_iterator>
typename std::iterator_traits<octet_iterator>::difference_type distance (octet_iterator first, octet_iterator last); octet_iterator : un iterador de entrada.
first : un iterador para el comienzo de un punto de código codificado UTF-8.
last : un iterador de un "post-end" del último punto de código codificado UTF-8 en la secuencia que estamos tratando de determinar la longitud. Puede ser el comienzo de un nuevo punto de código, o no.
Valor de retorno La distancia entre los iteradores, en puntos de código.
Ejemplo de uso:
char * twochars = " xe6x97xa5xd1x88 " ;
size_t dist = utf8::distance(twochars, twochars + 5 );
assert (dist == 2 ); Esta función se utiliza para encontrar la longitud (en puntos de código) de una cadena codificada UTF-8. La razón por la que se llama distancia , en lugar de, por ejemplo, la longitud se debe principalmente a que los desarrolladores se usan que la longitud es una función O (1). Calcular la longitud de una cadena UTF-8 es una operación lineal, y parecía mejor modelarla después del algoritmo std::distance .
En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 . Si last no apunta al pasado de extremo de una secuencia UTF-8, se lanza una excepción utf8::not_enough_room .
Disponible en la versión 1.0 y más tarde.
Convierte una cadena codificada UTF-16 a UTF-8.
template < typename u16bit_iterator, typename octet_iterator>
octet_iterator utf16to8 (u16bit_iterator start, u16bit_iterator end, octet_iterator result); u16bit_iterator : un iterador de entrada.
octet_iterator : un iterador de salida.
start : un iterador que apunta al comienzo de la cadena codificada UTF-16 para convertir.
end : un iterador que apunta al paso de la cadena codificada UTF-16 para convertir.
result : un iterador de salida al lugar en la cadena UTF-8 donde agregar el resultado de la conversión.
Valor de retorno: un iterador que apunta al lugar después de la cadena UTF-8 adjunta.
Ejemplo de uso:
unsigned short utf16string[] = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
vector< unsigned char > utf8result;
utf16to8 (utf16string, utf16string + 5 , back_inserter(utf8result));
assert (utf8result.size() == 10); En caso de secuencia no válida de UTF-16, se lanza una excepción utf8::invalid_utf16 .
Disponible en la versión 3.0 y más tarde. Requiere un compilador compatible con C ++ 11.
Convierte una cadena codificada UTF-16 a UTF-8.
std::string utf16to8 ( const std::u16string& s); s : una cadena codificada UTF-16. Valor de retorno: una cadena codificada UTF-8.
Ejemplo de uso:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
string u = utf16to8(utf16string);
assert (u.size() == 10); En caso de secuencia no válida de UTF-16, se lanza una excepción utf8::invalid_utf16 .
Disponible en la versión 3.2 y más tarde. Requiere un compilador compatible con C ++ 17.
Convierte una cadena codificada UTF-16 a UTF-8.
std::string utf16to8 (std::u16string_view s); s : una cadena codificada UTF-16. Valor de retorno: una cadena codificada UTF-8.
Ejemplo de uso:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u16string_view utf16stringview (u16string);
string u = utf16to8(utf16string);
assert (u.size() == 10); En caso de secuencia no válida de UTF-16, se lanza una excepción utf8::invalid_utf16 .
Disponible en la versión 4.0 y más tarde. Requiere un compilador compatible con C ++ 20.
Convierte una cadena codificada UTF-16 a UTF-8.
std::u8string utf16tou8 ( const std::u16string& s); s : una cadena codificada UTF-16. Valor de retorno: una cadena codificada UTF-8.
Ejemplo de uso:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u8string u = utf16tou8(utf16string);
assert (u.size() == 10); En caso de secuencia no válida de UTF-16, se lanza una excepción utf8::invalid_utf16 .
Disponible en la versión 4.0 y más tarde. Requiere un compilador compatible con C ++ 20.
Convierte una cadena codificada UTF-16 a UTF-8.
std::u8string utf16tou8 ( const std::u16string_view& s); s : una cadena codificada UTF-16. Valor de retorno: una cadena codificada UTF-8.
Ejemplo de uso:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u16string_view utf16stringview (u16string);
u8string u = utf16tou8(utf16string);
assert (u.size() == 10); En caso de secuencia no válida de UTF-16, se lanza una excepción utf8::invalid_utf16 .
Disponible en la versión 1.0 y más tarde.
Convierte una cadena codificada 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 iterador de entrada.
u16bit_iterator : un iterador de salida.
start : un iterador que apunta al comienzo de la cadena codificada UTF-8 para convertir. end : un iterador que apunta al paso de la cadena codificada UTF-8 para convertir.
result : un iterador de salida al lugar en la cadena UTF-16 donde agregar el resultado de la conversión.
Valor de retorno: un iterador que apunta al lugar después de la cadena UTF-16 adjunta.
Ejemplo de uso:
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 ); En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 . Si end no apunta al pasado de extremo de una secuencia UTF-8, se lanza una excepción utf8::not_enough_room .
Disponible en la versión 3.0 y más tarde. Requiere un compilador compatible con C ++ 11.
Convierte una cadena codificada UTF-8 en UTF-16.
std::u16string utf8to16 ( const std::string& s); s : una cadena codificada UTF-8 para convertir.
Valor de retorno: una cadena codificada UTF-16
Ejemplo de uso:
string utf8_with_surrogates = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
u16string utf16result = utf8to16(utf8_with_surrogates);
assert (utf16result.length() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e ); En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 .
Disponible en la versión 3.2 y más tarde. Requiere un compilador compatible con C ++ 17.
Convierte una cadena codificada UTF-8 en UTF-16.
std::u16string utf8to16 (std::string_view s); s : una cadena codificada UTF-8 para convertir.
Valor de retorno: una cadena codificada UTF-16
Ejemplo de uso:
string_view utf8_with_surrogates = " xe6x97xa5xd1x88xf0x9dx84x9e " ;
u16string utf16result = utf8to16(utf8_with_surrogates);
assert (utf16result.length() == 4);
assert (utf16result[ 2 ] == 0xd834 );
assert (utf16result[ 3 ] == 0xdd1e ); En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 .
Disponible en la versión 4.0 y más tarde. Requiere un compilador compatible con C ++ 20.
Convierte una cadena codificada UTF-8 en UTF-16.
std::u16string utf8to16 (std::u8string& s); s : una cadena codificada UTF-8 para convertir.
Valor de retorno: una cadena codificada UTF-16
Ejemplo de uso:
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 ); En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 .
Disponible en la versión 4.0 y más tarde. Requiere un compilador compatible con C ++ 20.
Convierte una cadena codificada UTF-8 en UTF-16.
std::u16string utf8to16 (std::u8string_view& s); s : una cadena codificada UTF-8 para convertir.
Valor de retorno: una cadena codificada UTF-16
Ejemplo de uso:
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 ); En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 .
Disponible en la versión 1.0 y más tarde.
Convierte una cadena codificada 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 iterador de salida.
u32bit_iterator : un iterador de entrada.
start : un iterador que apunta al comienzo de la cadena codificada UTF-32 para convertir.
end : un iterador que apunta al paso de la cadena codificada UTF-32 para convertir.
result : un iterador de salida al lugar en la cadena UTF-8 donde agregar el resultado de la conversión.
Valor de retorno: un iterador que apunta al lugar después de la cadena UTF-8 adjunta.
Ejemplo de uso:
int utf32string[] = { 0x448 , 0x65E5 , 0x10346 , 0 };
vector< unsigned char > utf8result;
utf32to8 (utf32string, utf32string + 3 , back_inserter(utf8result));
assert (utf8result.size() == 9); En el caso de una cadena UTF-32 inválida, se lanza una excepción utf8::invalid_code_point .
Disponible en la versión 3.0 y más tarde. Requiere un compilador compatible con C ++ 11.
Convierte una cadena codificada UTF-32 en UTF-8.
std::string utf32to8 ( const std::u32string& s); s : una cadena codificada UTF-32.
Valor de retorno: una cadena codificada UTF-8.
Ejemplo de uso:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); En el caso de una cadena UTF-32 inválida, se lanza una excepción utf8::invalid_code_point .
Disponible en la versión 4.0 y más tarde. Requiere un compilador compatible con C ++ 20.
Convierte una cadena codificada UTF-32 en UTF-8.
std::u8string utf32to8 ( const std::u32string& s); s : una cadena codificada UTF-32.
Valor de retorno: una cadena codificada UTF-8.
Ejemplo de uso:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u8string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); En el caso de una cadena UTF-32 inválida, se lanza una excepción utf8::invalid_code_point .
Disponible en la versión 4.0 y más tarde. Requiere un compilador compatible con C ++ 20.
Convierte una cadena codificada UTF-32 en UTF-8.
std::u8string utf32to8 ( const std::u32string_view& s); s : una cadena codificada UTF-32.
Valor de retorno: una cadena codificada UTF-8.
Ejemplo de uso:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u32string_view utf32stringview (utf32string);
u8string utf8result = utf32to8(utf32stringview);
assert (utf8result.size() == 9); En el caso de una cadena UTF-32 inválida, se lanza una excepción utf8::invalid_code_point .
Disponible en la versión 3.0 y más tarde. Requiere un compilador compatible con C ++ 11.
Convierte una cadena codificada UTF-32 en UTF-8.
std::string utf32to8 ( const std::u32string& s); s : una cadena codificada UTF-32.
Valor de retorno: una cadena codificada UTF-8.
Ejemplo de uso:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); En el caso de una cadena UTF-32 inválida, se lanza una excepción utf8::invalid_code_point .
Disponible en la versión 3.2 y más tarde. Requiere un compilador compatible con C ++ 17.
Convierte una cadena codificada UTF-32 en UTF-8.
std::string utf32to8 (std::u32string_view s); s : una cadena codificada UTF-32.
Valor de retorno: una cadena codificada UTF-8.
Ejemplo de uso:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u32string_view utf32stringview (utf32string);
string utf8result = utf32to8(utf32stringview);
assert (utf8result.size() == 9); En el caso de una cadena UTF-32 inválida, se lanza una excepción utf8::invalid_code_point .
Disponible en la versión 1.0 y más tarde.
Convierte una cadena codificada 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 iterador de entrada.
u32bit_iterator : un iterador de salida.
start : un iterador que apunta al comienzo de la cadena codificada UTF-8 para convertir.
end : un iterador que apunta al paso de la cadena codificada UTF-8 para convertir.
result : un iterador de salida al lugar en la cadena UTF-32 donde agregar el resultado de la conversión.
Valor de retorno: un iterador que apunta al lugar después de la cadena UTF-32 adjunta.
Ejemplo de uso:
char * twochars = " xe6x97xa5xd1x88 " ;
vector< int > utf32result;
utf8to32 (twochars, twochars + 5 , back_inserter(utf32result));
assert (utf32result.size() == 2); En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 . Si end no apunta al pasado de extremo de una secuencia UTF-8, se lanza una excepción utf8::not_enough_room .
Disponible en la versión 4.0 y más tarde. Requiere un compilador compatible con C ++ 20.
Convierte una cadena codificada UTF-8 en UTF-32.
std::u32string utf8to32 ( const std::u8string& s); s : una cadena codificada UTF-8. Valor de retorno: una cadena codificada UTF-32.
Ejemplo de uso:
const std::u8string* twochars = u8" xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 .
Disponible en la versión 4.0 y más tarde. Requiere un compilador compatible con C ++ 20.
Convierte una cadena codificada UTF-8 en UTF-32.
std::u32string utf8to32 ( const std::u8string_view& s); s : una cadena codificada UTF-8. Valor de retorno: una cadena codificada UTF-32.
Ejemplo de uso:
const u8string* twochars = u8" xe6x97xa5xd1x88 " ;
const u8string_view stringview{twochars};
u32string utf32result = utf8to32(stringview);
assert (utf32result.size() == 2); En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 .
Disponible en la versión 3.0 y más tarde. Requiere un compilador compatible con C ++ 11.
Convierte una cadena codificada UTF-8 en UTF-32.
std::u32string utf8to32 ( const std::string& s); s : una cadena codificada UTF-8. Valor de retorno: una cadena codificada UTF-32.
Ejemplo de uso:
const char * twochars = " xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 .
Disponible en la versión 3.2 y más tarde. Requiere un compilador compatible con C ++ 17.
Convierte una cadena codificada UTF-8 en UTF-32.
std::u32string utf8to32 (std::string_view s); s : una cadena codificada UTF-8. Valor de retorno: una cadena codificada UTF-32.
Ejemplo de uso:
string_view twochars = " xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); En el caso de una secuencia no válida de UTF-8, se lanza una excepción utf8::invalid_utf8 .
Disponible en la versión 1.0 y más tarde.
Detecta una secuencia no válida dentro de una cadena UTF-8.
template < typename octet_iterator>
octet_iterator find_invalid (octet_iterator start, octet_iterator end); octet_iterator : un iterador de entrada.
start : un iterador que apunta al comienzo de la cadena UTF-8 para probar la validez.
end : un iterador que apunta al paso de la cadena UTF-8 para probar validez.
Valor de retorno: un iterador que apunta al primer octeto inválido en la cadena UTF-8. En caso de que no se encuentre ninguno, es igual end .
Ejemplo de uso:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
char * invalid = find_invalid(utf_invalid, utf_invalid + 6 );
assert (invalid == utf_invalid + 5 );Esta función se usa típicamente para asegurarse de que una cadena UTF-8 sea válida antes de procesarla con otras funciones. Es especialmente importante llamarlo si antes de hacer alguna de las operaciones sin control sobre él.
Disponible en la versión 4.0 y más tarde.
Detecta una secuencia no válida dentro de una cadena UTF-8 de estilo C.
const char * find_invalid ( const char * str); str : una cadena codificada UTF-8. Valor de retorno: un puntero al primer octeto inválido en la cadena UTF-8. En caso de que no se encuentre ninguno, apunta al byte cero final.
Ejemplo de uso:
const char * utf_invalid = " xe6x97xa5xd1x88xfa " ;
const char * invalid = find_invalid(utf_invalid);
assert ((invalid - utf_invalid) == 5);Esta función se usa típicamente para asegurarse de que una cadena UTF-8 sea válida antes de procesarla con otras funciones. Es especialmente importante llamarlo si antes de hacer alguna de las operaciones sin control sobre él.
Disponible en la versión 3.0 y más tarde. Antes de 4.0 requería un compilador C ++ 11; El requisito se levanta con 4.0
Detecta una secuencia no válida dentro de una cadena UTF-8.
std:: size_t find_invalid ( const std::string& s); s : una cadena codificada UTF-8. Valor de retorno: el índice del primer octeto inválido en la cadena UTF-8. En caso de que no se encuentre ninguno, es igual std::string::npos .
Ejemplo de uso:
string utf_invalid = " xe6x97xa5xd1x88xfa " ;
auto invalid = find_invalid(utf_invalid);
assert (invalid == 5 );Esta función se usa típicamente para asegurarse de que una cadena UTF-8 sea válida antes de procesarla con otras funciones. Es especialmente importante llamarlo si antes de hacer alguna de las operaciones sin control sobre él.
Disponible en la versión 3.2 y más tarde. Requiere un compilador compatible con C ++ 17.
Detecta una secuencia no válida dentro de una cadena UTF-8.
std:: size_t find_invalid (std::string_view s); s : una cadena codificada UTF-8. Valor de retorno: el índice del primer octeto inválido en la cadena UTF-8. En caso de que no se encuentre ninguno, es igual std::string_view::npos .
Ejemplo de uso:
string_view utf_invalid = " xe6x97xa5xd1x88xfa " ;
auto invalid = find_invalid(utf_invalid);
assert (invalid == 5 );Esta función se usa típicamente para asegurarse de que una cadena UTF-8 sea válida antes de procesarla con otras funciones. Es especialmente importante llamarlo si antes de hacer alguna de las operaciones sin control sobre él.
Disponible en la versión 1.0 y más tarde.
Comprueba si una secuencia de octetos es una cadena UTF-8 válida.
template < typename octet_iterator>
bool is_valid (octet_iterator start, octet_iterator end); octet_iterator : un iterador de entrada.
start : un iterador que apunta al comienzo de la cadena UTF-8 para probar la validez.
end : un iterador que apunta al paso de la cadena UTF-8 para probar validez.
Valor de retorno: true Si la secuencia es una cadena UTF-8 válida; false si no.
Ejemplo de uso:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid, utf_invalid + 6 );
assert (bvalid == false ); is_valid es una taquigrafía para find_invalid(start, end) == end; . Es posible que desee usarlo para asegurarse de que una secuencia de bytes sea una cadena UTF-8 válida sin la necesidad de saber dónde falla si no es válida.
Disponible en la versión 4.0 y más tarde.
Comprueba si una cadena de estilo C contiene texto codificado UTF-8 válido.
bool is_valid ( const char * str); str : una cadena codificada UTF-8.
Valor de retorno: true Si la cadena contiene texto codificado UTF-8 válido; false si no.
Ejemplo de uso:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Es posible que desee usar is_valid para asegurarse de que una cadena contenga texto UTF-8 válido sin la necesidad de saber dónde falla si no es válido.
Disponible en la versión 3.0 y más tarde. Antes de 4.0 requería un compilador C ++ 11; El requisito se levanta con 4.0
Comprueba si un objeto de cadena contiene texto codificado UTF-8 válido.
bool is_valid ( const std::string& s); s : una cadena codificada UTF-8.
Valor de retorno: true Si la cadena contiene texto codificado UTF-8 válido; false si no.
Ejemplo de uso:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Es posible que desee usar is_valid para asegurarse de que una cadena contenga texto UTF-8 válido sin la necesidad de saber dónde falla si no es válido.
Disponible en la versión 3.2 y más tarde. Requiere un compilador compatible con C ++ 17.
Comprueba si un objeto de cadena contiene texto codificado UTF-8 válido.
bool is_valid (std::string_view s); s : una cadena codificada UTF-8.
Valor de retorno: true Si la cadena contiene texto codificado UTF-8 válido; false si no.
Ejemplo de uso:
string_view utf_invalid = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Es posible que desee usar is_valid para asegurarse de que una cadena contenga texto UTF-8 válido sin la necesidad de saber dónde falla si no es válido.
Disponible en la versión 2.0 y más tarde.
Reemplaza todas las secuencias UTF-8 inválidas dentro de una cadena con un marcador de reemplazo.
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 iterador de entrada.
output_iterator : un iterador de salida.
start : un iterador que apunta al comienzo de la cadena UTF-8 para buscar secuencias UTF-8 no válidas.
end : un iterador que apunta al paso de la cadena UTF-8 para buscar secuencias UTF-8 no válidas.
out : un iterador de salida al rango donde se almacena el resultado del reemplazo.
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.
