Condividi tramite


Classe codecvt

Modello di classe che descrive un oggetto che può fungere da facet delle impostazioni locali. Può controllare le conversioni tra una sequenza di valori utilizzata per codificare i caratteri all'interno del programma e una sequenza di valori usati per codificare i caratteri all'esterno del programma.

Sintassi

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

Parametri

CharType
Tipo utilizzato all'interno di un programma per codificare i caratteri.

Byte
Tipo utilizzato per codificare i caratteri all'esterno di un programma.

StateType
Tipo che può essere utilizzato per rappresentare gli stati intermedi di una conversione tra tipi di rappresentazioni di caratteri interni ed esterni.

Osservazioni:

Il modello di classe descrive un oggetto che può fungere da facet delle impostazioni locali, per controllare le conversioni tra una sequenza di valori di tipo CharType e una sequenza di valori di tipo Byte. La classe StateType caratterizza la trasformazione e un oggetto della classe StateType archivia tutte le informazioni necessarie sullo stato durante una conversione.

Nella codifica interna viene utilizzata una rappresentazione con un numero fisso di byte per carattere, in genere il tipo char o wchar_t.

Come in qualsiasi facet delle impostazioni locali, l'oggetto statico id ha un valore archiviato iniziale uguale a zero. Il primo tentativo di accedere al valore archiviato consente di archiviare un valore positivo univoco in id.

Le versioni del modello di do_in e do_out restituiscono codecvt_base::noconvsempre .

Nella libreria standard C++ vengono definite diverse specializzazioni esplicite:

template<>
codecvt<wchar_t, char, mbstate_t>

Esegue la conversione tra le sequenze wchar_t e char.

template<>
codecvt<char16_t, char, mbstate_t>

esegue la conversione tra le sequenze char16_t codificate come UTF-16 e le sequenze char codificate come UTF-8.

template<>
codecvt<char32_t, char, mbstate_t>

esegue la conversione tra le sequenze char32_t codificate come UTF-32 (UCS-4) e le sequenze char codificate come UTF-8.

Costruttori

Costruttore Descrizione
codecvt Costruttore per gli oggetti della classe codecvt utilizzato come facet delle impostazioni locali per gestire le conversioni.

Typedef

Nome tipo Descrizione
extern_type Tipo di carattere utilizzato per le rappresentazioni esterne.
intern_type Tipo di carattere utilizzato per le rappresentazioni interne.
state_type Tipo di carattere utilizzato per rappresentare gli stati intermedi durante le conversione tra le rappresentazioni interne ed esterne.

Funzioni membro

Funzione membro Descrizione
always_noconv Verifica che non sia necessario eseguire alcuna conversione.
do_always_noconv Funzione virtuale chiamata per verificare che non sia necessario eseguire alcuna conversione.
do_encoding Funzione virtuale che verifica se la codifica del Byte flusso dipende dallo stato, se il rapporto tra i Byte valori usati e i CharType valori prodotti è costante e, in tal caso, determina il valore di tale rapporto.
do_in Funzione virtuale chiamata per convertire una sequenza di valori interni Byte in una sequenza di valori esterni CharType .
do_length Funzione virtuale che determina il numero Byte di valori di una determinata sequenza di valori esterni Byte produce non più di un determinato numero di valori interni CharType e restituisce tale numero di Byte valori.
do_max_length Funzione virtuale che restituisce il numero massimo di byte esterni necessari per produrre un CharType interno.
do_out Funzione virtuale chiamata per convertire una sequenza di valori interni CharType in una sequenza di byte esterni.
do_unshift Funzione virtuale chiamata per fornire i Byte valori necessari in una conversione dipendente dallo stato per completare l'ultimo carattere in una sequenza di Byte valori.
encoding Verifica se la codifica del Byte flusso dipende dallo stato, se il rapporto tra i Byte valori utilizzati e i CharType valori prodotti è costante e, in tal caso, determina il valore di tale rapporto.
in Converte una rappresentazione esterna di una sequenza di Byte valori in una rappresentazione interna di una sequenza di CharType valori.
length Determina il numero Byte di valori di una determinata sequenza di valori esterni Byte che producono non più di un determinato numero di valori interni CharType e restituisce tale numero di Byte valori.
max_length Restituisce il numero massimo di valori esterni Byte necessari per produrre un oggetto interno CharType.
out Converte una sequenza di valori interni CharType in una sequenza di valori esterni Byte .
unshift Fornisce i valori esterni Byte necessari in una conversione dipendente dallo stato per completare l'ultimo carattere nella sequenza di Byte valori.

Requisiti

Intestazione: <locale>

Spazio dei nomi: std

codecvt::always_noconv

Verifica se non è necessario eseguire conversioni.

bool always_noconv() const throw();

Valore restituito

Valore booleano che è true se non è necessario eseguire alcuna conversione. false Se è necessario eseguire almeno un'operazione.

Osservazioni:

La funzione membro restituiscedo_always_noconv.

Esempio

// 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

Costruttore per gli oggetti della classe codecvt usato come facet delle impostazioni locali per gestire le conversioni.

explicit codecvt(size_t refs = 0);

Parametri

refs
Valore Integer che consente di specificare il tipo di gestione della memoria per l'oggetto.

Osservazioni:

I valori possibili per il parametro refs e i relativi significati sono:

  • 0: la durata dell'oggetto è gestita dalle impostazioni locali che lo contengono.

  • 1: la durata dell'oggetto deve essere gestita manualmente.

  • 2: questi valori non sono definiti.

Il costruttore inizializza il relativo locale::facet oggetto di base con locale::facet(refs).

codecvt::do_always_noconv

Funzione virtuale chiamata per verificare se non è necessario eseguire alcuna conversione.

virtual bool do_always_noconv() const throw();

Valore restituito

La funzione membro virtuale protetta restituisce true solo se ogni chiamata a do_in o do_out restituisce noconv.

La versione del modello restituisce truesempre .

Esempio

Vedere l'esempio per always_noconv, che chiama do_always_noconv.

codecvt::do_encoding

Funzione virtuale che verifica se la codifica del Byte flusso dipende dallo stato, se il rapporto tra i Byte valori usati e i CharType valori prodotti è costante e, in tal caso, determina il valore di tale rapporto.

virtual int do_encoding() const throw();

Valore restituito

La funzione membro protetto virtuale restituisce:

  • -1, se la codifica delle sequenze di tipo extern_type dipende dallo stato.

  • 0 se la codifica implica le sequenze di lunghezza variabile.

  • N, se la codifica prevede solo sequenze di lunghezza N

Esempio

Vedere l'esempio di encoding, che chiama do_encoding.

codecvt::d o_in

Funzione virtuale chiamata per convertire una sequenza di valori esterni Byte in una sequenza di valori interni CharType .

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

Parametri

state
Lo stato della conversione che viene mantenuto tra le chiamate alla funzione membro.

first1
Puntatore all'inizio della sequenza da convertire.

last1
Puntatore alla fine della sequenza da convertire.

next1
Puntatore oltre la fine della sequenza convertita, al primo carattere non convertito.

first2
Puntatore all'inizio della sequenza convertita.

last2
Puntatore alla fine della sequenza convertita.

next2
Puntatore all'oggetto CharType che segue l'ultimo oggetto convertito CharTypenel primo carattere non modificato nella sequenza di destinazione.

Valore restituito

Indica l'esito positivo, l'esecuzione parziale o l'esito negativo dell'operazione. La funzione restituisce:

  • codecvt_base::error se la sequenza di origine non è corretta.

  • codecvt_base::noconv se la funzione non esegue alcuna conversione.

  • codecvt_base::ok se la conversione ha esito positivo.

  • codecvt_base::partial se l'origine non è sufficiente o se la destinazione non è abbastanza grande, perché la conversione abbia esito positivo.

Osservazioni:

state deve rappresentare lo stato di conversione iniziale all'inizio di una nuova sequenza di origine. La funzione modifica il valore archiviato in base alle necessità per riflettere lo stato corrente di una corretta conversione. In caso contrario, il valore archiviato non è specificato.

Esempio

Vedere l'esempio per in, che chiama do_in.

codecvt::do_length

Funzione virtuale che determina il numero Byte di valori di una determinata sequenza di valori esterni Byte produce non più di un determinato numero di valori interni CharType e restituisce tale numero di Byte valori.

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

Parametri

state
Lo stato della conversione che viene mantenuto tra le chiamate alla funzione membro.

first1
Puntatore all'inizio della sequenza esterna.

last1
Puntatore alla fine della sequenza esterna.

len2
Numero massimo di Byte valori che possono essere restituiti dalla funzione membro.

Valore restituito

Intero che rappresenta un conteggio del numero massimo di conversioni, non maggiore di len2, definito dalla sequenza di origine esterna in [ first1, last1).

Osservazioni:

La funzione membro virtuale protetta chiama do_in( state, first1, last1, next1, buf, buf + len2, next2) efficacemente lo stato (una copia dello stato), alcuni bufpuntatori next1 e buffer e next2.

Restituisce quindi next2 - buf. Conta il numero massimo di conversioni, non maggiore di len2, definito dalla sequenza di origine in [ first1, last1).

La versione del modello restituisce sempre il valore minore di last1 - first1 e .len2

Esempio

Vedere l'esempio per length, che chiama do_length.

codecvt::do_max_length

Funzione virtuale che restituisce il numero massimo di valori esterni Byte necessari per produrre un oggetto interno CharType.

virtual int do_max_length() const throw();

Valore restituito

Numero massimo di Byte valori necessari per produrre un oggetto CharType.

Osservazioni:

La funzione membro virtuale protetta restituisce il valore massimo consentito che può essere restituito da do_length( first1, last1, 1) per valori arbitrari validi di first1 e last1.

Esempio

Vedere l'esempio per max_length, che chiama do_max_length.

codecvt::do_out

Funzione virtuale chiamata per convertire una sequenza di valori interni CharType in una sequenza di valori esterni Byte .

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

Parametri

state
Lo stato della conversione che viene mantenuto tra le chiamate alla funzione membro.

first1
Puntatore all'inizio della sequenza da convertire.

last1
Puntatore alla fine della sequenza da convertire.

next1
Riferimento a un puntatore al primo oggetto non CharTypeconvertito dopo l'ultima CharType conversione.

first2
Puntatore all'inizio della sequenza convertita.

last2
Puntatore alla fine della sequenza convertita.

next2
Riferimento a un puntatore al primo oggetto non Byteconvertito dopo l'ultima Byte conversione.

Valore restituito

La funzione restituisce:

  • codecvt_base::error se la sequenza di origine non è corretta.

  • codecvt_base::noconv se la funzione non esegue alcuna conversione.

  • codecvt_base::ok se la conversione ha esito positivo.

  • codecvt_base::partial se l'origine non è sufficiente o se la destinazione non è abbastanza grande per l'esito positivo della conversione.

Osservazioni:

state deve rappresentare lo stato di conversione iniziale all'inizio di una nuova sequenza di origine. La funzione modifica il valore archiviato in base alle necessità per riflettere lo stato corrente di una corretta conversione. In caso contrario, il valore archiviato non è specificato.

Esempio

Vedere l'esempio di out, che chiama do_out.

codecvt::do_unshift

Funzione virtuale chiamata per fornire i Byte valori necessari in una conversione dipendente dallo stato per completare l'ultimo carattere in una sequenza di Byte valori.

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

Parametri

state
Lo stato della conversione che viene mantenuto tra le chiamate alla funzione membro.

first2
Puntatore alla prima posizione nell'intervallo di destinazione.

last2
Puntatore all'ultima posizione nell'intervallo di destinazione.

next2
Puntatore al primo elemento non modificato nella sequenza di destinazione.

Valore restituito

La funzione restituisce:

  • codecvt_base::error se lo stato rappresenta uno stato non valido

  • codecvt_base::noconv se la funzione non esegue alcuna conversione

  • codecvt_base::ok se la conversione ha esito positivo

  • codecvt_base::partial se la destinazione non è abbastanza grande perché la conversione abbia esito positivo

Osservazioni:

La funzione membro virtuale protetta tenta di convertire l'elemento CharTypedi origine (0) in una sequenza di destinazione archiviata all'interno di [ first2, last2), ad eccezione dell'elemento Bytedi terminazione (0). Archivia sempre in next2 un puntatore al primo elemento non modificato nella sequenza di destinazione.

State deve rappresentare lo stato di conversione iniziale all'inizio di una nuova sequenza di origine. La funzione modifica il valore archiviato in base alle necessità per riflettere lo stato corrente di una corretta conversione. In genere, la conversione dell'elemento CharTypedi origine (0) lascia lo stato corrente nello stato di conversione iniziale.

Esempio

Vedere l'esempio per unshift, che chiama do_unshift.

codecvt::encoding

Verifica se la codifica del Byte flusso dipende dallo stato, se il rapporto tra i Byte valori utilizzati e i CharType valori prodotti è costante e, in tal caso, determina il valore di tale rapporto.

int encoding() const throw();

Valore restituito

Se il valore restituito è positivo, tale valore è il numero costante di Byte caratteri necessari per produrre il CharType carattere.

La funzione membro protetto virtuale restituisce:

  • -1, se la codifica delle sequenze di tipo extern_type dipende dallo stato.

  • 0 se la codifica implica le sequenze di lunghezza variabile.

  • N, se la codifica prevede solo sequenze di lunghezza N.

Osservazioni:

La funzione membro restituisce do_encoding.

Esempio

// 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

Tipo di carattere utilizzato per le rappresentazioni esterne.

typedef Byte extern_type;

Osservazioni:

Il tipo è un sinonimo del parametro di modello Byte.

codecvt::in

Converte una rappresentazione esterna di una sequenza di Byte valori in una rappresentazione interna di una sequenza di CharType valori.

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

Parametri

state
Lo stato della conversione che viene mantenuto tra le chiamate alla funzione membro.

first1
Puntatore all'inizio della sequenza da convertire.

last1
Puntatore alla fine della sequenza da convertire.

next1
Puntatore oltre la fine della sequenza convertita, al primo carattere non convertito.

first2
Puntatore all'inizio della sequenza convertita.

last2
Puntatore alla fine della sequenza convertita.

next2
Puntatore all'oggetto CharType che segue l'ultimo oggetto convertito Chartype nel primo carattere non modificato nella sequenza di destinazione.

Valore restituito

Indica l'esito positivo, l'esecuzione parziale o l'esito negativo dell'operazione. La funzione restituisce:

  • codecvt_base::error se la sequenza di origine non è corretta.

  • codecvt_base::noconv se la funzione non esegue alcuna conversione.

  • codecvt_base::ok se la conversione ha esito positivo.

  • codecvt_base::partial se l'origine non è sufficiente o se la destinazione non è abbastanza grande per l'esito positivo della conversione.

Osservazioni:

state deve rappresentare lo stato di conversione iniziale all'inizio di una nuova sequenza di origine. La funzione modifica il valore archiviato in base alle necessità per riflettere lo stato corrente di una corretta conversione. Dopo una conversione parziale, state deve essere impostata in modo da riprendere la conversione quando arrivano nuovi caratteri.

La funzione membro restituiscedo_in( state, first1, last1, next1, first2, last2, next2).

Esempio

// 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

Tipo di carattere utilizzato per le rappresentazioni interne.

typedef CharType intern_type;

Osservazioni:

Il tipo è un sinonimo del parametro di modello CharType.

codecvt::length

Determina il numero Byte di valori di una determinata sequenza di valori esterni Byte che producono non più di un determinato numero di valori interni CharType e restituisce tale numero di Byte valori.

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

Parametri

state
Lo stato della conversione che viene mantenuto tra le chiamate alla funzione membro.

first1
Puntatore all'inizio della sequenza esterna.

last1
Puntatore alla fine della sequenza esterna.

len2
Il numero massimo di byte che può essere restituito dalla funzione membro.

Valore restituito

Valore Integer che rappresenta il calcolo del numero massimo di conversioni, non maggiore len2, definito dalla sequenza di origine esterna in [ first1, last1).

Osservazioni:

La funzione membro restituiscedo_length( state, first1, last1, len2).

Esempio

// 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

Restituisce il numero massimo di valori esterni Byte necessari per produrre un oggetto interno CharType.

int max_length() const throw();

Valore restituito

Numero massimo di Byte valori necessari per produrre un oggetto CharType.

Osservazioni:

La funzione membro restituiscedo_max_length.

Esempio

// 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 una sequenza di valori interni CharType in una sequenza di valori esterni Byte .

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

Parametri

state
Lo stato della conversione che viene mantenuto tra le chiamate alla funzione membro.

first1
Puntatore all'inizio della sequenza da convertire.

last1
Puntatore alla fine della sequenza da convertire.

next1
Riferimento a un puntatore al primo oggetto non convertito CharType dopo l'ultima CharType conversione.

first2
Puntatore all'inizio della sequenza convertita.

last2
Puntatore alla fine della sequenza convertita.

next2
Riferimento a un puntatore al primo oggetto non convertito Byte dopo l'ultimo oggetto convertito Byte.

Valore restituito

La funzione membro restituiscedo_out( state, first1, last1, next1, first2, last2, next2).

Osservazioni:

Per ulteriori informazioni, vedere codecvt::do_out.

Esempio

// 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

Tipo di carattere utilizzato per rappresentare gli stati intermedi durante le conversione tra le rappresentazioni interne ed esterne.

typedef StateType state_type;

Osservazioni:

Il tipo è un sinonimo del parametro di modello StateType.

codecvt::unshift

Fornisce i Byte valori necessari in una conversione dipendente dallo stato per completare l'ultimo carattere in una sequenza di Byte valori.

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

Parametri

state
Lo stato della conversione che viene mantenuto tra le chiamate alla funzione membro.

first2
Puntatore alla prima posizione nell'intervallo di destinazione.

last2
Puntatore all'ultima posizione nell'intervallo di destinazione.

next2
Puntatore al primo elemento non modificato nella sequenza di destinazione.

Valore restituito

La funzione restituisce:

  • codecvt_base::error se lo stato rappresenta uno stato non valido.

  • codecvt_base::noconv se la funzione non esegue alcuna conversione.

  • codecvt_base::ok se la conversione ha esito positivo.

  • codecvt_base::partial se la destinazione non è abbastanza grande perché la conversione abbia esito positivo.

Osservazioni:

La funzione membro virtuale protetta tenta di convertire l'elemento CharTypedi origine (0) in una sequenza di destinazione archiviata all'interno di [ first2, last2), ad eccezione dell'elemento Bytedi terminazione (0). Archivia sempre in next2 un puntatore al primo elemento non modificato nella sequenza di destinazione.

state deve rappresentare lo stato di conversione iniziale all'inizio di una nuova sequenza di origine. La funzione modifica il valore archiviato in base alle necessità per riflettere lo stato corrente di una corretta conversione. In genere, la conversione dell'elemento CharTypedi origine (0) lascia lo stato corrente nello stato di conversione iniziale.

La funzione membro restituiscedo_unshift( state, first2, last2, next2 ).

Vedi anche

<locale>
Tabelle codici
Nomi delle impostazioni locali, lingue e stringhe relative a paesi
Thread Safety in the C++ Standard Library (Sicurezza dei thread nella libreria standard C++)