Partilhar via

Classe codecvt

  • Artigo

Um modelo de classe que descreve um objeto que pode servir como uma faceta de localidade. Ele pode controlar conversões entre uma sequência de valores usada para codificar caracteres dentro do programa e uma sequência de valores usada para codificar caracteres fora do programa.

Sintaxe

template <class CharType, class Byte, class StateType>
class codecvt : public locale::facet, codecvt_base;

Parâmetros

CharType
O tipo usado em um programa para codificar caracteres.

Byte
Um tipo usado para codificar caracteres fora de um programa.

StateType
Um tipo que pode ser usado para representar estados intermediários de uma conversão entre tipos internos e externos das representações de caractere.

Comentários

O modelo de classe descreve um objeto que pode funcionar como uma faceta de localidade para controlar conversões entre uma sequência de valores do tipo CharType e uma sequência de valores do tipo Byte. A classe StateType caracteriza a transformação – e um objeto da classe StateType armazena todas as informações de estado necessárias durante uma conversão.

A codificação interna usa uma representação com um número fixo de bytes por caractere, geralmente do tipo char ou do tipo wchar_t.

Como qualquer faceta de localidade, a id de objeto estático tem um valor armazenado inicial de zero. A primeira tentativa de acessar seu valor armazenado armazena um valor positivo exclusivo em id.

As versões do modelo do_in e do_out sempre retornam codecvt_base::noconv.

A Biblioteca Padrão C++ define várias especializações explícitas:

template<>
codecvt<wchar_t, char, mbstate_t>

conversões entre sequências wchar_t e char.

template<>
codecvt<char16_t, char, mbstate_t>

conversões entre sequências char16_t codificadas como UTF-16 e sequências char codificadas como UTF-8.

template<>
codecvt<char32_t, char, mbstate_t>

conversões entre sequências char32_t codificadas como UTF-32 (UCS-4) e sequências char codificadas como UTF-8.

Construtores

Construtor Descrição
codecvt O construtor para objetos da classe codecvt que serve como uma faceta de localidade para tratar conversões.

Typedefs

Nome do tipo Descrição
extern_type Um tipo de caractere que é usado para representações externas.
intern_type Um tipo de caractere que é usado para representações internas.
state_type Um tipo de caractere que é usado para representar estados intermediários durante conversões entre representações internas e externas.

Funções de membro

Função de membro Descrição
always_noconv Testa se nenhuma conversão precisa ser feita.
do_always_noconv Uma função virtual chamada para testar se nenhuma conversão precisa ser feita.
do_encoding Uma função virtual que testa se a codificação do fluxo Byte é dependente de estado, se a taxa entre os valores Byte usados e os valores CharType produzidos é constante e, em caso positivo, determina o valor dessa taxa.
do_in Uma função virtual chamada para converter uma sequência de valores Byte internos em uma sequência de valores CharType externos.
do_length Uma função virtual que determina quantos valores de Byte de uma determinada sequência de valores de Byte externos produzem não mais do que determinados valores de CharType internos e retorna esse número de valores de Byte.
do_max_length Uma função virtual que retorna o número máximo de Bytes externos necessários para gerar um CharType interno.
do_out Uma função virtual chamada para converter uma sequência de valores CharType internos em uma sequência de Bytes externos.
do_unshift Uma função virtual chamada para fornecer os valores de Byte necessários em uma conversão dependente de estado para completar o último caractere em uma sequência de valores de Byte.
encoding Testa se a codificação do fluxo Byte é dependente de estado, se a taxa entre os valores Byte usados e os valores CharType produzidos é constante e, em caso positivo, determina o valor dessa taxa.
in Converte uma representação externa de uma sequência de valores Byte em uma representação interna de uma sequência de valores CharType.
length Determina quantos valores de Byte de uma determinada sequência de valores de Byte externos produzem não mais do que determinados valores de CharType internos e retorna esse número de valores de Byte.
max_length Retorna o número máximo de valores de Byte externos necessários para gerar um CharType interno.
out Converte uma sequência de valores de CharType internos em uma sequência de valores de Byte externos.
unshift Fornece os valores de Byte externos necessários em uma conversão dependente de estado para completar o último caractere da sequência de valores de Byte.

Requisitos

Cabeçalho: <locale>

Namespace: std

codecvt::always_noconv

Testa se nenhuma conversão precisa ser feita.

bool always_noconv() const throw();

Valor de retorno

Um valor booliano será true se nenhuma conversão precisar ser feita; e false se pelo menos uma precisar ser feita.

Comentários

A função membro retorna do_always_noconv.

Exemplo

// codecvt_always_noconv.cpp
// compile with: /EHsc
#include <locale>
#include <iostream>
using namespace std;

int main( )
{
   locale loc ( "German_Germany" );
   bool result1 = use_facet<codecvt<char, char, mbstate_t>>
      ( loc ).always_noconv( );

   if ( result1 )
      cout << "No conversion is needed." << '\n';
   else
      cout << "At least one conversion is required." << '\n';

   bool result2 = use_facet<codecvt<wchar_t, char, mbstate_t>>
      ( loc ).always_noconv( );

   if ( result2 )
      cout << "No conversion is needed." << '\n';
   else
      cout << "At least one conversion is required." << '\n';
}

No conversion is needed.
At least one conversion is required.

codecvt::codecvt

O construtor de objetos da classe codecvt que funciona como uma faceta de localidade para manipular conversões.

explicit codecvt(size_t refs = 0);

Parâmetros

refs
Valor inteiro usado para especificar o tipo de gerenciamento de memória do objeto.

Comentários

Os valores possíveis para o parâmetro refs e sua significância são:

  • 0: o tempo de vida do objeto é gerenciado pelas localidades que o contêm.

  • 1: o tempo de vida do objeto deve ser gerenciado manualmente.

  • 2: Esses valores não são definidos.

O construtor inicializa seu locale::facetobjeto base com locale::facet(refs).

codecvt::do_always_noconv

Uma função virtual chamada para testar se nenhuma conversão precisa ser feita.

virtual bool do_always_noconv() const throw();

Valor de retorno

A função membro virtual protegida retornará true somente se toda chamada para do_in ou do_out retornará noconv.

A versão do modelo sempre retorna true.

Exemplo

Confira o exemplo de always_noconv, que chama do_always_noconv.

codecvt::do_encoding

Uma função virtual que testa se a codificação do fluxo Byte é dependente de estado, se a taxa entre os valores Byte usados e os valores CharType produzidos é constante e, em caso positivo, determina o valor dessa taxa.

virtual int do_encoding() const throw();

Valor de retorno

A função membro virtual protegido retornará:

  • - 1, se a codificação de sequências do tipo extern_type for dependente do estado.

  • 0, se a codificação envolver sequências de comprimentos variáveis.

  • N, se a codificação envolver somente sequências de comprimento N

Exemplo

Consulte o exemplo de encoding, que chama do_encoding.

codecvt::d o_in

Uma função virtual chamada para converter uma sequência de valores Byte externos em uma sequência de valores CharType internos.

virtual result do_in(
    StateType& state,
    const Byte* first1,
    const Byte* last1,
    const Byte*& next1,
    CharType* first2,
    CharType* last2,
    CharType*& next2,) const;

Parâmetros

state
O estado de conversão mantido entre as chamadas para a função membro.

first1
Ponteiro para o início da sequência a ser convertida.

last1
Ponteiro para o fim da sequência a ser convertida.

next1
Ponteiro além do fim da sequência convertida para o primeiro caractere não convertido.

first2
Ponteiro para o início da sequência convertida.

last2
Ponteiro para o fim da sequência convertida.

next2
Ponteiro para CharType que vem após o último CharType convertido para o primeiro caractere inalterado na sequência de destino.

Valor de retorno

Um retorno que indica o êxito, êxito parcial ou falha da operação. A função retornará:

  • codecvt_base::error se a sequência de origem estiver mal formada.

  • codecvt_base::noconv se a função não realizar nenhuma conversão.

  • codecvt_base::ok se a conversão for bem-sucedida.

  • codecvt_base::partial se a fonte for insuficiente ou se o destino não for grande o suficiente para que a conversão seja bem-sucedida.

Comentários

state deve representar o estado de conversão inicial no início de uma nova sequência de origem. A função altera seu valor armazenado conforme necessário para refletir o estado atual de uma conversão bem-sucedida. Caso contrário, seu valor armazenado não é especificado.

Exemplo

Confira o exemplo de in, que chama do_in.

codecvt::do_length

Uma função virtual que determina quantos valores de Byte de uma determinada sequência de valores de Byte externos produzem não mais do que determinados valores de CharType internos e retorna esse número de valores de Byte.

virtual int do_length(
    const StateType& state,
    const Byte* first1,
    const Byte* last1,
    size_t len2) const;

Parâmetros

state
O estado de conversão mantido entre as chamadas para a função membro.

first1
Ponteiro para o início da sequência externa.

last1
Ponteiro para o fim da sequência externa.

len2
O número máximo de valores de Byte que podem ser retornados pela função membro.

Valor de retorno

Um inteiro que representa uma contagem do número máximo de conversões, não maior que len2, definido pela sequência de origem externa em [first1, last1).

Comentários

A função membro virtual protegida efetivamente chama do_in( state, first1, last1, next1, buf, buf + len2, next2) para estado (uma cópia do estado), alguns buf de buffer e next1, além de next2 de ponteiro.

Em seguida, ele retorna next2 - buf. Ela conta o número máximo de conversões, não maior do que len2, definido pela sequência de origem em [first1, last1).

A versão do modelo sempre retorna o menor de last1 - first1 elen2.

Exemplo

Confira o exemplo de length, que chama do_length.

codecvt::do_max_length

Uma função virtual que retorna o número máximo de valores de Byte externos necessários para gerar um CharType interno.

virtual int do_max_length() const throw();

Valor de retorno

O número máximo de valores de Byte necessários para produzir um CharType.

Comentários

A função membro virtual protegida retorna o maior valor permitido que pode ser retornado por do_length( first1, last1, 1) para valores válidos arbitrários de first1 e last1.

Exemplo

Confira o exemplo de max_length, que chama do_max_length.

codecvt::do_out

Uma função virtual chamada para converter uma sequência de valores CharType internos em uma sequência de valores Byte externos.

virtual result do_out(
    StateType& state,
    const CharType* first1,
    const CharType* last1,
    const CharType*& next1,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

Parâmetros

state
O estado de conversão mantido entre as chamadas para a função membro.

first1
Ponteiro para o início da sequência a ser convertida.

last1
Ponteiro para o fim da sequência a ser convertida.

next1
Referência a um ponteiro para o primeiro CharType não convertido depois do último CharType convertido.

first2
Ponteiro para o início da sequência convertida.

last2
Ponteiro para o fim da sequência convertida.

next2
Referência a um ponteiro para o primeiro Byte não convertido depois do último Byte convertido.

Valor de retorno

A função retornará:

  • codecvt_base::error se a sequência de origem estiver mal formada.

  • codecvt_base::noconv se a função não realizar nenhuma conversão.

  • codecvt_base::ok se a conversão for bem-sucedida.

  • codecvt_base::partial se a fonte for insuficiente ou se o destino não for grande o suficiente para que a conversão seja bem-sucedida.

Comentários

state deve representar o estado de conversão inicial no início de uma nova sequência de origem. A função altera seu valor armazenado conforme necessário para refletir o estado atual de uma conversão bem-sucedida. Caso contrário, seu valor armazenado não é especificado.

Exemplo

Consulte o exemplo de out, que chama do_out.

codecvt::do_unshift

Uma função virtual chamada para fornecer os valores de Byte necessários em uma conversão dependente de estado para completar o último caractere em uma sequência de valores de Byte.

virtual result do_unshift(
    StateType& state,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

Parâmetros

state
O estado de conversão mantido entre as chamadas para a função membro.

first2
Ponteiro para a primeira posição no intervalo de destino.

last2
Ponteiro para a última posição no intervalo de destino.

next2
Ponteiro para o primeiro elemento inalterado na sequência de destino.

Valor de retorno

A função retornará:

  • codecvt_base::error se o estado representar um estado inválido

  • codecvt_base::noconv se a função não realizar nenhuma conversão

  • codecvt_base::ok se a conversão for bem-sucedida

  • codecvt_base::partial se a fonte for insuficiente ou se o destino não for grande o suficiente para que a conversão seja bem-sucedida

Comentários

A função membro virtual protegido tenta converter o elemento de origem CharType(0) para uma sequência de destino que ele armazena no [ first2, last2), exceto para o elemento de terminação Byte(0). Ela sempre armazena em next2 um ponteiro para um elemento inalterado na sequência de destino.

State deve representar o estado de conversão inicial no início de uma nova sequência de origem. A função altera seu valor armazenado conforme necessário para refletir o estado atual de uma conversão bem-sucedida. Normalmente, converter o elemento de origem CharType(0) deixa o estado atual no estado de conversão inicial.

Exemplo

Confira o exemplo de unshift, que chama do_unshift.

codecvt::encoding

Testa se a codificação do fluxo Byte é dependente de estado, se a taxa entre os valores Byte usados e os valores CharType produzidos é constante e, em caso positivo, determina o valor dessa taxa.

int encoding() const throw();

Valor de retorno

Se o valor retornado for positivo, esse valor será o número constante de Byte caracteres necessários para produzir o caractere CharType.

A função membro virtual protegido retornará:

  • - 1, se a codificação de sequências do tipo extern_type for dependente do estado.

  • 0, se a codificação envolver sequências de comprimentos variáveis.

  • N, se a codificação envolver somente sequências de comprimento N.

Comentários

A função membro retorna do_encoding.

Exemplo

// codecvt_encoding.cpp
// compile with: /EHsc
#include <locale>
#include <iostream>
using namespace std;

int main( )
{
   locale loc ( "German_Germany" );
   int result1 = use_facet<codecvt<char, char, mbstate_t>> ( loc ).encoding ( );
   cout << result1 << '\n';
   result1 = use_facet<codecvt<wchar_t, char, mbstate_t>> ( loc ).encoding( );
   cout << result1 << '\n';
   result1 = use_facet<codecvt<char, wchar_t, mbstate_t>> ( loc ).encoding( );
   cout << result1 << '\n';
}

1
1
1

codecvt::extern_type

Um tipo de caractere que é usado para representações externas.

typedef Byte extern_type;

Comentários

O tipo é um sinônimo do parâmetro de modeloByte.

codecvt::in

Converte uma representação externa de uma sequência de valores Byte em uma representação interna de uma sequência de valores CharType.

result in(
    StateType& state,
    const Byte* first1,
    const Byte* last1,
    const Byte*& next1,
    CharType* first2,
    CharType* last2,
    CharType*& next2,) const;

Parâmetros

state
O estado de conversão mantido entre as chamadas para a função membro.

first1
Ponteiro para o início da sequência a ser convertida.

last1
Ponteiro para o fim da sequência a ser convertida.

next1
Ponteiro além do fim da sequência de convertida para o primeiro caractere não convertido.

first2
Ponteiro para o início da sequência convertida.

last2
Ponteiro para o fim da sequência convertida.

next2
Ponteiro para CharType que vem após o último Chartype convertido para o primeiro caractere inalterado na sequência de destino.

Valor de retorno

Um retorno que indica o êxito, êxito parcial ou falha da operação. A função retornará:

  • codecvt_base::error se a sequência de origem estiver mal formada.

  • codecvt_base::noconv se a função não realizar nenhuma conversão.

  • codecvt_base::ok se a conversão for bem-sucedida.

  • codecvt_base::partial se a fonte for insuficiente ou se o destino não for grande o suficiente para que a conversão seja bem-sucedida.

Comentários

state deve representar o estado de conversão inicial no início de uma nova sequência de origem. A função altera seu valor armazenado, conforme necessário, para refletir o estado atual de uma conversão bem-sucedida. Depois de uma conversão parcial, state deve ser definido de modo a permitir que a conversão seja retomada com a chegada de novos caracteres.

A função membro retorna do_in( state, first1, last1, next1, first2, last2, next2).

Exemplo

// codecvt_in.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
using namespace std;
#define LEN 90
int main( )
{
   const char* pszExt = "This is the string to be converted!";
   wchar_t pwszInt [LEN+1];
   memset(&pwszInt[0], 0, (sizeof(wchar_t))*(LEN+1));
   const char* pszNext;
   wchar_t* pwszNext;
   mbstate_t state = {0}; // zero-initialization represents the initial conversion state for mbstate_t
   locale loc("C");//English_Britain");//German_Germany
   int res = use_facet<codecvt<wchar_t, char, mbstate_t>>
     ( loc ).in( state,
          pszExt, &pszExt[strlen(pszExt)], pszNext,
          pwszInt, &pwszInt[strlen(pszExt)], pwszNext );
   pwszInt[strlen(pszExt)] = 0;
   wcout << ( res!=codecvt_base::error ?  L"It worked! " : L"It didn't work! " )
       << L"The converted string is:\n ["
       << &pwszInt[0]
       << L"]" << '\n';
   exit(-1);
}

It worked! The converted string is:
[This is the string to be converted!]

codecvt::intern_type

Um tipo de caractere que é usado para representações internas.

typedef CharType intern_type;

Comentários

O tipo é um sinônimo do parâmetro de modeloCharType.

codecvt::comprimento

Determina quantos valores de Byte de uma determinada sequência de valores de Byte externos produzem não mais do que determinados valores de CharType internos e retorna esse número de valores de Byte.

int length(
    const StateType& state,
    const Byte* first1,
    const Byte* last1,
    size_t len2) const;

Parâmetros

state
O estado de conversão mantido entre as chamadas para a função membro.

first1
Ponteiro para o início da sequência externa.

last1
Ponteiro para o fim da sequência externa.

len2
O número máximo de Bytes que podem ser retornados pela função membro.

Valor de retorno

Um inteiro que representa uma contagem do número máximo de conversões, não maior que len2, definido pela sequência de origem externa em [ first1, last1).

Comentários

A função membro retorna do_length( state, first1, last1, len2).

Exemplo

// codecvt_length.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
using namespace std;
#define LEN 90
int main( )
{
   const char* pszExt = "This is the string whose length is to be measured!";
   mbstate_t state = {0}; // zero-initialization represents the initial conversion state for mbstate_t
   locale loc("C"); // English_Britain"); //German_Germany
   int res = use_facet<codecvt<wchar_t, char, mbstate_t>>
     ( loc ).length( state,
          pszExt, &pszExt[strlen(pszExt)], LEN );
   cout << "The length of the string is: ";
   wcout << res;
   cout << "." << '\n';
   exit(-1);
}

The length of the string is: 50.

codecvt::max_length

Retorna o número máximo de valores de Byte externos necessários para gerar um CharType interno.

int max_length() const throw();

Valor de retorno

O número máximo de valores de Byte necessários para produzir um CharType.

Comentários

A função membro retorna do_max_length.

Exemplo

// codecvt_max_length.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
using namespace std;

int main( )
{
   locale loc( "C");//English_Britain" );//German_Germany
   int res = use_facet<codecvt<char, char, mbstate_t>>
     ( loc ).max_length( );
   wcout << res << '\n';
}

1

codecvt::out

Converte uma sequência de valores de CharType internos em uma sequência de valores de Byte externos.

result out(
    StateType& state,
    const CharType* first1,
    const CharType* last1,
    const CharType*& next1,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

Parâmetros

state
O estado de conversão mantido entre as chamadas para a função membro.

first1
Ponteiro para o início da sequência a ser convertida.

last1
Ponteiro para o fim da sequência a ser convertida.

next1
Referência a um ponteiro para o primeiro CharType não convertido depois do último CharType convertido.

first2
Ponteiro para o início da sequência convertida.

last2
Ponteiro para o fim da sequência convertida.

next2
Referência a um ponteiro para o primeiro Byte não convertido depois do último Byte convertido.

Valor de retorno

A função membro retorna do_out( state, first1, last1, next1, first2, last2, next2).

Comentários

Para obter mais informações, consulte codecvt::do_out.

Exemplo

// codecvt_out.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
#include <wchar.h>
using namespace std;
#define LEN 90
int main( )
{
    char pszExt[LEN + 1];
    const wchar_t* pwszInt = L"This is the wchar_t string to be converted.";
    memset(&pszExt[0], 0, (sizeof(char)) * (LEN + 1));
    char* pszNext;
    const wchar_t* pwszNext;
    mbstate_t state;
    locale loc("C");//English_Britain");//German_Germany
    int res = use_facet<codecvt<wchar_t, char, mbstate_t>>
        (loc).out(state,
            pwszInt, &pwszInt[wcslen(pwszInt)], pwszNext,
            pszExt, &pszExt[wcslen(pwszInt)], pszNext);
    pszExt[wcslen(pwszInt)] = 0;
    cout << (res != codecvt_base::error ? "It worked: " : "It didn't work: ")
        << "The converted string is:\n ["
        << &pszExt[0]
        << "]" << '\n';

}

It worked: The converted string is:
[This is the wchar_t string to be converted.]

codecvt::state_type

Um tipo de caractere que é usado para representar estados intermediários durante conversões entre representações internas e externas.

typedef StateType state_type;

Comentários

O tipo é um sinônimo do parâmetro de modeloStateType.

codecvt::unshift

Fornece os valores de Byte necessários em uma conversão dependente de estado para completar o último caractere da sequência de valores de Byte.

result unshift(
    StateType& state,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

Parâmetros

state
O estado de conversão mantido entre as chamadas para a função membro.

first2
Ponteiro para a primeira posição no intervalo de destino.

last2
Ponteiro para a última posição no intervalo de destino.

next2
Ponteiro para o primeiro elemento inalterado na sequência de destino.

Valor de retorno

A função retornará:

  • codecvt_base::error se o estado representar um estado inválido.

  • codecvt_base::noconv se a função não realizar nenhuma conversão.

  • codecvt_base::ok se a conversão for bem-sucedida.

  • codecvt_base::partial se a fonte for insuficiente ou se o destino não for grande o suficiente para que a conversão seja bem-sucedida.

Comentários

A função membro virtual protegido tenta converter o elemento de origem CharType(0) para uma sequência de destino que ele armazena no [ first2, last2), exceto para o elemento de terminação Byte(0). Ela sempre armazena em next2 um ponteiro para um elemento inalterado na sequência de destino.

state deve representar o estado de conversão inicial no início de uma nova sequência de origem. A função altera seu valor armazenado, conforme necessário, para refletir o estado atual de uma conversão bem-sucedida. Normalmente, converter o elemento de origem CharType(0) deixa o estado atual no estado de conversão inicial.

A função membro retorna do_unshift( state, first2, last2, next2 ).

Confira também

<locale>
Páginas de código
Nomes de localidades, idiomas e cadeias de caracteres de país/região
Acesso Thread-Safe na Biblioteca Padrão C++