utfcpp
Release 4.0.6
Os desenvolvedores de C ++ ainda sentem falta de uma maneira fácil e portátil de lidar com strings codificadas Unicode. O padrão C ++ original (conhecido como C ++ 98 ou C ++ 03) é Unicode Agnóstico. Alguns progressos foram feitos nas edições posteriores do padrão, mas ainda é difícil trabalhar com o Unicode usando apenas as instalações padrão.
Eu criei uma pequena biblioteca genérica compatível com C ++ 98 para lidar com seqüências de cordas codificadas UTF-8. Para quem costumava trabalhar com algoritmos e iteradores STL, deve ser fácil e natural de usar. O código está disponível gratuitamente para qualquer finalidade - consulte a licença. A biblioteca tem sido muito usada desde o primeiro lançamento em 2006 em projetos comerciais e de código aberto e provou ser estável e útil.
Esta é uma biblioteca somente para cabeçalho e a maneira suportada de implantá-la é:
O arquivo cmakelist.txt foi originalmente feito apenas para fins de teste, mas, infelizmente, com o tempo, aceitei contribuições que adicionaram o destino de instalação. Esta não é uma maneira suportada de instalar a biblioteca UTFCPP e estou pensando em remover o cmakelist.txt em uma versão futura.
Para ilustrar o uso da biblioteca, vamos começar com um programa pequeno, mas completo, que abre um arquivo que contém o texto codificado UTF-8, o linha linha por linha, verifica cada linha para seqüências inválidas de UTF-8 de bytes e a converte para a codificação UTF-16 e volte para o 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 ;
} Na amostra de código anterior, para cada linha, realizamos uma detecção de sequências UTF-8 inválidas com find_invalid ; O número de caracteres (com mais precisão - o número de pontos de código Unicode, incluindo o final da linha e até o Bom, se houver um) em cada linha, foi determinado com o uso do utf8::distance ; Finalmente, convertemos cada linha em codificação UTF-16 com utf8to16 e voltamos para o UTF-8 com utf16to8 .
Observe um padrão diferente de uso para compiladores antigos. Por exemplo, é assim que convertemos uma string codificada UTF-8 em um UTF-16 codificado com um compilador pré-C ++ 11:
vector< unsigned short > utf16line;
utf8::utf8to16 (line.begin(), end_it, back_inserter(utf16line));Com um compilador mais moderno, a mesma operação seria:
u16string utf16line = utf8::utf8to16(line); Se __cplusplus macro apontar para um C ++ 11 ou posterior, a biblioteca expõe a API que leva em consideração Strings Unicode Standard C ++ e mova a semântica. Com um compilador mais antigo, ainda é possível usar a mesma funcionalidade, apenas de maneira um pouco menos conveniente
Caso você não confie na macro __cplusplus ou, por exemplo, não deseja incluir as funções auxiliares C ++ 11, mesmo com um compilador moderno, defina UTF_CPP_CPLUSPLUS Macro antes de incluir utf8.h e atribuir um valor para o padrão que deseja usar - os valores são os mesmos para o __cplusplus Macs. Isso também pode ser útil com compiladores que são conservadores ao definir a macro __cplusplus , mesmo que tenham um bom suporte para uma edição padrão recente - o visual c ++ da Microsoft é um exemplo.
Aqui está uma função que verifica se o conteúdo de um arquivo é um texto codificado UTF-8 válido sem ler o conteúdo na memória:
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);
} Como a função utf8::is_valid() funciona com os iteradores de entrada, conseguimos it um istreambuf_iterator e ler o conteúdo do arquivo diretamente sem carregá -lo na memória primeiro.
Observe que outras funções que recebem argumentos do iterador de entrada podem ser usadas de maneira semelhante. Por exemplo, para ler o conteúdo de um arquivo de texto codificado UTF-8 e converter o texto para o UTF-16, faça algo como:
utf8::utf8to16 (it, eos, back_inserter(u16string));Se tivermos algum texto que "provavelmente" contém texto codificado UTF-8 e queremos substituir qualquer sequência UTF-8 inválida por um caractere de substituição, algo como a seguinte função pode ser usada:
void fix_utf8_string (std::string& str)
{
std::string temp;
utf8::replace_invalid (str. begin (), str. end (), back_inserter (temp));
str = temp;
}A função substituirá qualquer sequência UTF-8 inválida por um caractere de substituição Unicode. Há uma função sobrecarregada que permite ao chamador fornecer seu próprio caractere de substituição.
A biblioteca foi projetada para ser:
Para alternativas e comparações, recomendo o seguinte artigo: O mundo maravilhosamente terrível das APIs de codificação C e C ++ (com alguma ferrugem), de Jeanheyd Meneide. No artigo, esta biblioteca é comparada com:
O artigo apresenta a visão do autor sobre a qualidade do design da API, mas também alguns benchmarks de velocidade.
Disponível na versão 1.0 e posterior.
Codifica um ponto de código de 32 bits como uma sequência UTF-8 de octetos e anexa a sequência a uma sequência UTF-8.
template < typename octet_iterator>
octet_iterator append ( utfchar32_t cp, octet_iterator result); octet_iterator : um iterador de saída.
cp : Um número inteiro de 32 bits representando um ponto de código para anexar à sequência.
result : um iterador de saída para o local na sequência em que anexar o ponto de código.
Valor de retorno: um iterador apontando para o local após a sequência recém -anexa.
Exemplo 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 ); Observe que append não aloca nenhuma memória - é o ônus do chamador para garantir que haja memória suficiente alocada para a operação. Para tornar as coisas mais interessantes, append pode adicionar entre 1 e 4 octetos à sequência. Na prática, você mais frequentemente deseja usar std::back_inserter para garantir que a memória necessária seja alocada.
No caso de um ponto de código inválido, uma exceção utf8::invalid_code_point é lançada.
Disponível na versão 3.0 e posterior. Antes de 4.0, era necessário um compilador C ++ 11; O requisito é levantado com 4.0.
Codifica um ponto de código de 32 bits como uma sequência UTF-8 de octetos e anexa a sequência a uma sequência UTF-8.
void append ( utfchar32_t cp, std::string& s); cp : Um ponto de código a ser anexado à string.
s : Uma sequência codificada UTF-8 para anexar o código do código.
Exemplo de uso:
std::string u;
append ( 0x0448 , u);
assert (u[ 0 ] == char ( 0xd1 ) && u[1] == char( 0x88 ) && u.length() == 2); No caso de um ponto de código inválido, uma exceção utf8::invalid_code_point é lançada.
Disponível na versão 4.0 e posterior.
Codifica um ponto de código de 32 bits como uma sequência UTF-16 de palavras e anexa a sequência a uma sequência UTF-16.
template < typename word_iterator>
word_iterator append16 ( utfchar32_t cp, word_iterator result); word_iterator : um iterador de saída.
cp : Um número inteiro de 32 bits representando um ponto de código para anexar à sequência.
result : um iterador de saída para o local na sequência em que anexar o ponto de código.
Valor de retorno: um iterador apontando para o local após a sequência recém -anexa.
Exemplo de uso:
unsigned short u[ 2 ] = { 0 , 0 };
unsigned short * end = append16( 0x0448 , u);
assert (u[ 0 ] == 0x0448 && u[ 1 ] == 0 ); Observe que append16 não aloca nenhuma memória - é o ônus do chamador para garantir que haja memória suficiente alocada para a operação. Para tornar as coisas mais interessantes, append16 pode adicionar uma ou duas palavras à sequência. Na prática, você mais frequentemente deseja usar std::back_inserter para garantir que a memória necessária seja alocada.
No caso de um ponto de código inválido, uma exceção utf8::invalid_code_point é lançada.
Disponível na versão 4.0 e posterior. Requer um compilador compilador de C ++ 11.
Codifica um ponto de código de 32 bits como uma sequência UTF-16 de palavras e anexa a sequência a uma sequência UTF-16.
void append ( utfchar32_t cp, std::u16string& s); cp : Um ponto de código a ser anexado à string.
s : Uma sequência codificada UTF-16 para anexar o código do ponto.
Exemplo de uso:
std::u16string u;
append ( 0x0448 , u);
assert (u[ 0 ] == 0x0448 && u.length() == 1); No caso de um ponto de código inválido, uma exceção utf8::invalid_code_point é lançada.
Disponível na versão 1.0 e posterior.
Dado o iterador para o início da sequência UTF-8, ele retorna o ponto de código e move o iterador para a próxima posição.
template < typename octet_iterator>
utfchar32_t next (octet_iterator& it, octet_iterator end); octet_iterator : um iterador de entrada.
it : Uma referência a um iterador apontando para o início de um ponto de código codificado UTF-8. Após o retorno da função, é incrementado para apontar para o início do próximo ponto de código.
end : Fim da sequência UTF-8 a ser processada. Se it igual ao end durante a extração de um ponto de código, uma exceção utf8::not_enough_room será lançada.
Valor de retorno: a representação de 32 bits do ponto de código UTF-8 processado.
Exemplo de uso:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = next(w, twochars + 6 );
assert (cp == 0x65e5 );
assert (w == twochars + 3 );Esta função é normalmente usada para iterar através de uma sequência codificada UTF-8.
No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada.
Disponível na versão 4.0 e posterior.
Dado o iterador para o início da sequência UTF-16, ele retorna o ponto de código e move o iterador para a próxima posição.
template < typename word_iterator>
utfchar32_t next16 (word_iterator& it, word_iterator end); word_iterator : um iterador de entrada.
it : Uma referência a um iterador apontando para o início de um ponto de código codificado UTF-16. Após o retorno da função, é incrementado para apontar para o início do próximo ponto de código.
end : Fim da sequência UTF-16 a ser processada. Se it igual ao end durante a extração de um ponto de código, uma exceção utf8::not_enough_room será lançada.
Valor de retorno: a representação de 32 bits do ponto de código UTF-16 processado.
Exemplo 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 função é normalmente usada para iterar através de uma sequência codificada UTF-16.
No caso de uma sequência UTF-16 inválida, uma exceção utf8::invalid_utf8 é lançada.
Disponível na versão 2.1 e posterior.
Dado o iterador para o início da sequência UTF-8, ele retorna o ponto de código para a seguinte sequência sem alterar o valor do iterador.
template < typename octet_iterator>
utfchar32_t peek_next (octet_iterator it, octet_iterator end); octet_iterator : um iterador de entrada.
it : Um iterador apontando para o início de um ponto de código codificado UTF-8.
end : Fim da sequência UTF-8 a ser processada. Se it igual ao end durante a extração de um ponto de código, uma exceção utf8::not_enough_room será lançada.
Valor de retorno: a representação de 32 bits do ponto de código UTF-8 processado.
Exemplo de uso:
char * twochars = " xe6x97xa5xd1x88 " ;
char * w = twochars;
int cp = peek_next(w, twochars + 6 );
assert (cp == 0x65e5 );
assert (w == twochars); No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada.
Disponível na versão 1.02 e posterior.
Dada uma referência a um iterador apontando para um octeto em uma sequência UTF-8, ele diminui o iterador até atingir o início do ponto de código codificado anterior do UTF-8 e retorna a representação de 32 bits do ponto de código.
template < typename octet_iterator>
utfchar32_t prior (octet_iterator& it, octet_iterator start); octet_iterator : um iterador bidirecional.
it : Uma referência apontando para um octeto dentro de uma string codificada UTF-8. Após o retorno da função, ela diminui para apontar para o início do ponto de código anterior.
start : um iterador para o início da sequência em que a busca pelo início de um ponto de código é executada. É uma medida de segurança para impedir a passagem do início da string na busca de um octeto de chumbo UTF-8.
Valor de retorno: a representação de 32 bits do ponto de código anterior.
Exemplo de uso:
char * twochars = " xe6x97xa5xd1x88 " ;
unsigned char * w = twochars + 3 ;
int cp = prior (w, twochars);
assert (cp == 0x65e5 );
assert (w == twochars); Esta função possui dois propósitos: um é dois iterados para trás através de uma sequência codificada UTF-8. Observe que geralmente é uma ideia melhor para iterar, pois utf8::next é mais rápido. O segundo objetivo é encontrar o início de uma sequência UTF-8 se tivermos uma posição aleatória dentro de uma string. Observe que, nesse caso, utf8::prior pode não detectar uma sequência UTF-8 inválida em alguns cenários: por exemplo, se houver octetos de trilhas supérfluos, ele apenas os ignorará.
Normalmente, it aponta para o início de um ponto de código e start apontará para o início da string para garantir que não voltemos muito longe. it diminui até apontar para um octeto UTF-8 de chumbo e, em seguida, a sequência UTF-8, começando com esse octeto, é decodificada para uma representação de 32 bits e devolvida.
Caso start seja alcançado antes que um octeto de chumbo UTF-8 seja atingido, ou se uma sequência UTF-8 inválida for iniciada pelo octeto principal, uma exceção invalid_utf8 será lançada.
Caso start seja igual it , uma exceção not_enough_room é lançada.
Disponível na versão 1.0 e posterior.
Avança um iterador pelo número especificado de pontos de código dentro de uma sequência UTF-8.
template < typename octet_iterator, typename distance_type>
void advance (octet_iterator& it, distance_type n, octet_iterator end); octet_iterator : um iterador de entrada.
distance_type : Um tipo integral conversível para o tipo de diferença do octet_iterator .
it : Uma referência a um iterador apontando para o início de um ponto de código codificado UTF-8. Após o retorno da função, ela é incrementada para apontar para o Nth após o ponto de código.
n : Número de pontos de código it deve ser avançado. Um valor negativo significa decréscimo.
end : Limite da sequência UTF-8 a ser processada. Se n for positivo e it igual ao end durante a extração de um ponto de código, uma exceção utf8::not_enough_room é lançada. Se n for negativo e it end enquanto it byte de trilha TA de uma sequência UTF-8, uma exceção utf8::invalid_code_point será lançada.
Exemplo 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); No caso de um ponto de código inválido, uma exceção utf8::invalid_code_point é lançada.
Disponível na versão 1.0 e posterior.
Dados os iteradores para dois pontos de código codificados UTF-8 em uma sequência, retorna o número de pontos de código entre eles.
template < typename octet_iterator>
typename std::iterator_traits<octet_iterator>::difference_type distance (octet_iterator first, octet_iterator last); octet_iterator : um iterador de entrada.
first : um iterador para o início de um ponto de código codificado UTF-8.
last : um iterador para um "post-end" do último ponto de código codificado UTF-8 na sequência, estamos tentando determinar o comprimento. Pode ser o começo de um novo ponto de código, ou não.
Valor de retorno A distância entre os iteradores, nos pontos de código.
Exemplo de uso:
char * twochars = " xe6x97xa5xd1x88 " ;
size_t dist = utf8::distance(twochars, twochars + 5 );
assert (dist == 2 ); Esta função é usada para encontrar o comprimento (nos pontos de código) de uma sequência codificada UTF-8. A razão pela qual é chamada de distância , e não, digamos, o comprimento é principalmente porque os desenvolvedores são usados que o comprimento é uma função O (1). A computação do comprimento de uma string UTF-8 é uma operação linear e parecia melhor modelá-la após o algoritmo std::distance .
No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada. Se last não apontar para o passado de uma sequência UTF-8, uma exceção utf8::not_enough_room será lançada.
Disponível na versão 1.0 e posterior.
Converte uma sequência codificada UTF-16 em UTF-8.
template < typename u16bit_iterator, typename octet_iterator>
octet_iterator utf16to8 (u16bit_iterator start, u16bit_iterator end, octet_iterator result); u16bit_iterator : um iterador de entrada.
octet_iterator : um iterador de saída.
start : um iterador apontando para o início da sequência codificada UTF-16 para converter.
end : um iterador apontando para passar o final da sequência codificada UTF-16 para converter.
result : um iterador de saída para o local na sequência UTF-8 onde anexar o resultado da conversão.
Valor de retorno: um iterador apontando para o local após a sequência UTF-8 anexada.
Exemplo 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); No caso de sequência UTF-16 inválida, uma exceção utf8::invalid_utf16 é lançada.
Disponível na versão 3.0 e posterior. Requer um compilador compilador de C ++ 11.
Converte uma sequência codificada UTF-16 em UTF-8.
std::string utf16to8 ( const std::u16string& s); s : Uma string codificada UTF-16. Valor de retorno: uma string codificada UTF-8.
Exemplo de uso:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
string u = utf16to8(utf16string);
assert (u.size() == 10); No caso de sequência UTF-16 inválida, uma exceção utf8::invalid_utf16 é lançada.
Disponível na versão 3.2 e posterior. Requer um compilador compilador de C ++ 17.
Converte uma sequência codificada UTF-16 em UTF-8.
std::string utf16to8 (std::u16string_view s); s : Uma string codificada UTF-16. Valor de retorno: uma string codificada UTF-8.
Exemplo de uso:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u16string_view utf16stringview (u16string);
string u = utf16to8(utf16string);
assert (u.size() == 10); No caso de sequência UTF-16 inválida, uma exceção utf8::invalid_utf16 é lançada.
Disponível na versão 4.0 e posterior. Requer um compilador compilador de C ++ 20.
Converte uma sequência codificada UTF-16 em UTF-8.
std::u8string utf16tou8 ( const std::u16string& s); s : Uma string codificada UTF-16. Valor de retorno: uma string codificada UTF-8.
Exemplo de uso:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u8string u = utf16tou8(utf16string);
assert (u.size() == 10); No caso de sequência UTF-16 inválida, uma exceção utf8::invalid_utf16 é lançada.
Disponível na versão 4.0 e posterior. Requer um compilador compilador de C ++ 20.
Converte uma sequência codificada UTF-16 em UTF-8.
std::u8string utf16tou8 ( const std::u16string_view& s); s : Uma string codificada UTF-16. Valor de retorno: uma string codificada UTF-8.
Exemplo de uso:
u16string utf16string = { 0x41 , 0x0448 , 0x65e5 , 0xd834 , 0xdd1e };
u16string_view utf16stringview (u16string);
u8string u = utf16tou8(utf16string);
assert (u.size() == 10); No caso de sequência UTF-16 inválida, uma exceção utf8::invalid_utf16 é lançada.
Disponível na versão 1.0 e posterior.
Converte uma string codificada UTF-8 em UTF-16
template < typename u16bit_iterator, typename octet_iterator>
u16bit_iterator utf8to16 (octet_iterator start, octet_iterator end, u16bit_iterator result); octet_iterator : um iterador de entrada.
u16bit_iterator : um iterador de saída.
start : Um iterador apontando para o início da sequência codificada UTF-8 para converter. end : um iterador apontando para passar o final da sequência codificada UTF-8 para converter.
result : um iterador de saída para o local na sequência UTF-16 onde anexar o resultado da conversão.
Valor de retorno: um iterador apontando para o local após a sequência UTF-16 anexada.
Exemplo 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 ); No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada. Se end não apontar para o passado de uma sequência UTF-8, uma exceção utf8::not_enough_room será lançada.
Disponível na versão 3.0 e posterior. Requer um compilador compilador de C ++ 11.
Converte uma sequência codificada UTF-8 em UTF-16.
std::u16string utf8to16 ( const std::string& s); s : Uma sequência codificada UTF-8 para converter.
Valor de retorno: uma string codificada UTF-16
Exemplo 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 ); No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada.
Disponível na versão 3.2 e posterior. Requer um compilador compilador de C ++ 17.
Converte uma sequência codificada UTF-8 em UTF-16.
std::u16string utf8to16 (std::string_view s); s : Uma sequência codificada UTF-8 para converter.
Valor de retorno: uma string codificada UTF-16
Exemplo 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 ); No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada.
Disponível na versão 4.0 e posterior. Requer um compilador compilador de C ++ 20.
Converte uma sequência codificada UTF-8 em UTF-16.
std::u16string utf8to16 (std::u8string& s); s : Uma sequência codificada UTF-8 para converter.
Valor de retorno: uma string codificada UTF-16
Exemplo 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 ); No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada.
Disponível na versão 4.0 e posterior. Requer um compilador compilador de C ++ 20.
Converte uma sequência codificada UTF-8 em UTF-16.
std::u16string utf8to16 (std::u8string_view& s); s : Uma sequência codificada UTF-8 para converter.
Valor de retorno: uma string codificada UTF-16
Exemplo 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 ); No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada.
Disponível na versão 1.0 e posterior.
Converte uma sequência codificada UTF-32 em UTF-8.
template < typename octet_iterator, typename u32bit_iterator>
octet_iterator utf32to8 (u32bit_iterator start, u32bit_iterator end, octet_iterator result); octet_iterator : um iterador de saída.
u32bit_iterator : um iterador de entrada.
start : Um iterador apontando para o início da sequência codificada UTF-32 para converter.
end : um iterador apontando para passar o final da sequência codificada UTF-32 para converter.
result : um iterador de saída para o local na sequência UTF-8 onde anexar o resultado da conversão.
Valor de retorno: um iterador apontando para o local após a sequência UTF-8 anexada.
Exemplo de uso:
int utf32string[] = { 0x448 , 0x65E5 , 0x10346 , 0 };
vector< unsigned char > utf8result;
utf32to8 (utf32string, utf32string + 3 , back_inserter(utf8result));
assert (utf8result.size() == 9); No caso de String inválida UTF-32, uma exceção utf8::invalid_code_point é lançada.
Disponível na versão 3.0 e posterior. Requer um compilador compilador de C ++ 11.
Converte uma sequência codificada UTF-32 em UTF-8.
std::string utf32to8 ( const std::u32string& s); s : uma sequência codificada UTF-32.
Valor de retorno: uma string codificada UTF-8.
Exemplo de uso:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); No caso de String inválida UTF-32, uma exceção utf8::invalid_code_point é lançada.
Disponível na versão 4.0 e posterior. Requer um compilador compilador de C ++ 20.
Converte uma sequência codificada UTF-32 em UTF-8.
std::u8string utf32to8 ( const std::u32string& s); s : uma sequência codificada UTF-32.
Valor de retorno: uma string codificada UTF-8.
Exemplo de uso:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u8string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); No caso de String inválida UTF-32, uma exceção utf8::invalid_code_point é lançada.
Disponível na versão 4.0 e posterior. Requer um compilador compilador de C ++ 20.
Converte uma sequência codificada UTF-32 em UTF-8.
std::u8string utf32to8 ( const std::u32string_view& s); s : uma sequência codificada UTF-32.
Valor de retorno: uma string codificada UTF-8.
Exemplo de uso:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u32string_view utf32stringview (utf32string);
u8string utf8result = utf32to8(utf32stringview);
assert (utf8result.size() == 9); No caso de String inválida UTF-32, uma exceção utf8::invalid_code_point é lançada.
Disponível na versão 3.0 e posterior. Requer um compilador compilador de C ++ 11.
Converte uma sequência codificada UTF-32 em UTF-8.
std::string utf32to8 ( const std::u32string& s); s : uma sequência codificada UTF-32.
Valor de retorno: uma string codificada UTF-8.
Exemplo de uso:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9); No caso de String inválida UTF-32, uma exceção utf8::invalid_code_point é lançada.
Disponível na versão 3.2 e posterior. Requer um compilador compilador de C ++ 17.
Converte uma sequência codificada UTF-32 em UTF-8.
std::string utf32to8 (std::u32string_view s); s : uma sequência codificada UTF-32.
Valor de retorno: uma string codificada UTF-8.
Exemplo de uso:
u32string utf32string = { 0x448 , 0x65E5 , 0x10346 };
u32string_view utf32stringview (utf32string);
string utf8result = utf32to8(utf32stringview);
assert (utf8result.size() == 9); No caso de String inválida UTF-32, uma exceção utf8::invalid_code_point é lançada.
Disponível na versão 1.0 e posterior.
Converte uma sequência codificada UTF-8 em UTF-32.
template < typename octet_iterator, typename u32bit_iterator>
u32bit_iterator utf8to32 (octet_iterator start, octet_iterator end, u32bit_iterator result); octet_iterator : um iterador de entrada.
u32bit_iterator : um iterador de saída.
start : Um iterador apontando para o início da sequência codificada UTF-8 para converter.
end : um iterador apontando para passar o final da sequência codificada UTF-8 para converter.
result : um iterador de saída para o local na sequência UTF-32 onde anexar o resultado da conversão.
Valor de retorno: um iterador apontando para o local após a sequência UTF-32 anexada.
Exemplo de uso:
char * twochars = " xe6x97xa5xd1x88 " ;
vector< int > utf32result;
utf8to32 (twochars, twochars + 5 , back_inserter(utf32result));
assert (utf32result.size() == 2); No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada. Se end não apontar para o passado de uma sequência UTF-8, uma exceção utf8::not_enough_room será lançada.
Disponível na versão 4.0 e posterior. Requer um compilador compilador de C ++ 20.
Converte uma sequência codificada UTF-8 em UTF-32.
std::u32string utf8to32 ( const std::u8string& s); s : Uma string codificada UTF-8. Valor de retorno: uma sequência codificada UTF-32.
Exemplo de uso:
const std::u8string* twochars = u8" xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada.
Disponível na versão 4.0 e posterior. Requer um compilador compilador de C ++ 20.
Converte uma sequência codificada UTF-8 em UTF-32.
std::u32string utf8to32 ( const std::u8string_view& s); s : Uma string codificada UTF-8. Valor de retorno: uma sequência codificada UTF-32.
Exemplo de uso:
const u8string* twochars = u8" xe6x97xa5xd1x88 " ;
const u8string_view stringview{twochars};
u32string utf32result = utf8to32(stringview);
assert (utf32result.size() == 2); No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada.
Disponível na versão 3.0 e posterior. Requer um compilador compilador de C ++ 11.
Converte uma sequência codificada UTF-8 em UTF-32.
std::u32string utf8to32 ( const std::string& s); s : Uma string codificada UTF-8. Valor de retorno: uma sequência codificada UTF-32.
Exemplo de uso:
const char * twochars = " xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada.
Disponível na versão 3.2 e posterior. Requer um compilador compilador de C ++ 17.
Converte uma sequência codificada UTF-8 em UTF-32.
std::u32string utf8to32 (std::string_view s); s : Uma string codificada UTF-8. Valor de retorno: uma sequência codificada UTF-32.
Exemplo de uso:
string_view twochars = " xe6x97xa5xd1x88 " ;
u32string utf32result = utf8to32(twochars);
assert (utf32result.size() == 2); No caso de uma sequência UTF-8 inválida, uma exceção utf8::invalid_utf8 é lançada.
Disponível na versão 1.0 e posterior.
Detecta uma sequência inválida em uma sequência UTF-8.
template < typename octet_iterator>
octet_iterator find_invalid (octet_iterator start, octet_iterator end); octet_iterator : um iterador de entrada.
start : um iterador apontando para o início da string UTF-8 para testar a validade.
end : um iterador apontando para passar o final da sequência UTF-8 para testar a validade.
Valor de retorno: um iterador apontando para o primeiro octeto inválido na sequência UTF-8. Caso nenhum foi encontrado, é igual end .
Exemplo de uso:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
char * invalid = find_invalid(utf_invalid, utf_invalid + 6 );
assert (invalid == utf_invalid + 5 );Essa função é normalmente usada para garantir que uma sequência UTF-8 seja válida antes de processá-la com outras funções. É especialmente importante chamá -lo se antes de fazer alguma das operações desmarcadas .
Disponível na versão 4.0 e posterior.
Detecta uma sequência inválida dentro de uma sequência UTF-8 no estilo C.
const char * find_invalid ( const char * str); str : Uma string codificada UTF-8. Valor de retorno: um ponteiro para o primeiro octeto inválido na sequência UTF-8. Caso não tenha sido encontrado nenhum ponto para o byte zero à direita.
Exemplo de uso:
const char * utf_invalid = " xe6x97xa5xd1x88xfa " ;
const char * invalid = find_invalid(utf_invalid);
assert ((invalid - utf_invalid) == 5);Essa função é normalmente usada para garantir que uma sequência UTF-8 seja válida antes de processá-la com outras funções. É especialmente importante chamá -lo se antes de fazer alguma das operações desmarcadas .
Disponível na versão 3.0 e posterior. Antes de 4.0, era necessário um compilador C ++ 11; O requisito é levantado com 4.0
Detecta uma sequência inválida em uma sequência UTF-8.
std:: size_t find_invalid ( const std::string& s); s : Uma string codificada UTF-8. Valor de retorno: o índice do primeiro octeto inválido na sequência UTF-8. Caso não tenha sido encontrado nenhum, é igual std::string::npos .
Exemplo de uso:
string utf_invalid = " xe6x97xa5xd1x88xfa " ;
auto invalid = find_invalid(utf_invalid);
assert (invalid == 5 );Essa função é normalmente usada para garantir que uma sequência UTF-8 seja válida antes de processá-la com outras funções. É especialmente importante chamá -lo se antes de fazer alguma das operações desmarcadas .
Disponível na versão 3.2 e posterior. Requer um compilador compilador de C ++ 17.
Detecta uma sequência inválida em uma sequência UTF-8.
std:: size_t find_invalid (std::string_view s); s : Uma string codificada UTF-8. Valor de retorno: o índice do primeiro octeto inválido na sequência UTF-8. Caso não tenha sido encontrado, é igual std::string_view::npos .
Exemplo de uso:
string_view utf_invalid = " xe6x97xa5xd1x88xfa " ;
auto invalid = find_invalid(utf_invalid);
assert (invalid == 5 );Essa função é normalmente usada para garantir que uma sequência UTF-8 seja válida antes de processá-la com outras funções. É especialmente importante chamá -lo se antes de fazer alguma das operações desmarcadas .
Disponível na versão 1.0 e posterior.
Verifica se uma sequência de octetos é uma string UTF-8 válida.
template < typename octet_iterator>
bool is_valid (octet_iterator start, octet_iterator end); octet_iterator : um iterador de entrada.
start : um iterador apontando para o início da string UTF-8 para testar a validade.
end : um iterador apontando para passar o final da sequência UTF-8 para testar a validade.
Valor de retorno: true se a sequência for uma string UTF-8 válida; false se não.
Exemplo de uso:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid, utf_invalid + 6 );
assert (bvalid == false ); is_valid é uma abreviação para find_invalid(start, end) == end; . Você pode usá-lo para garantir que uma sequência de bytes seja uma string UTF-8 válida sem a necessidade de saber onde ela falha se não for válida.
Disponível na versão 4.0 e posterior.
Verifica se uma sequência de estilo C contém texto codificado UTF-8 válido.
bool is_valid ( const char * str); str : Uma string codificada UTF-8.
Valor de retorno: true se a string contiver texto codificado UTF-8 válido; false se não.
Exemplo de uso:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Você pode usar is_valid para garantir que uma string contenha texto UTF-8 válido sem a necessidade de saber onde falha se não for válido.
Disponível na versão 3.0 e posterior. Antes de 4.0, era necessário um compilador C ++ 11; O requisito é levantado com 4.0
Verifica se um objeto String contém texto codificado UTF-8 válido.
bool is_valid ( const std::string& s); s : Uma string codificada UTF-8.
Valor de retorno: true se a string contiver texto codificado UTF-8 válido; false se não.
Exemplo de uso:
char utf_invalid[] = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Você pode usar is_valid para garantir que uma string contenha texto UTF-8 válido sem a necessidade de saber onde falha se não for válido.
Disponível na versão 3.2 e posterior. Requer um compilador compilador de C ++ 17.
Verifica se um objeto String contém texto codificado UTF-8 válido.
bool is_valid (std::string_view s); s : Uma string codificada UTF-8.
Valor de retorno: true se a string contiver texto codificado UTF-8 válido; false se não.
Exemplo de uso:
string_view utf_invalid = " xe6x97xa5xd1x88xfa " ;
bool bvalid = is_valid(utf_invalid);
assert (bvalid == false ); Você pode usar is_valid para garantir que uma string contenha texto UTF-8 válido sem a necessidade de saber onde falha se não for válido.
Disponível na versão 2.0 e posterior.
Substitui todas as sequências UTF-8 inválidas em uma string por um marcador de substituição.
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 : um iterador de entrada.
output_iterator : um iterador de saída.
start : Um iterador apontando para o início da string UTF-8 para procurar sequências UTF-8 inválidas.
end : um iterador apontando para passar o final da sequência UTF-8 para procurar sequências UTF-8 inválidas.
out : Um iterador de saída para o intervalo onde o resultado da substituição é armazenado.
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.
