Encoder Classe

Definição

Converte um conjunto de caracteres em uma sequência de bytes.Converts a set of characters into a sequence of bytes.

public ref class Encoder abstract
public abstract class Encoder
[System.Serializable]
public abstract class Encoder
[System.Runtime.InteropServices.ComVisible(true)]
[System.Serializable]
public abstract class Encoder
type Encoder = class
Public MustInherit Class Encoder
Herança
Encoder
Atributos

Exemplos

O exemplo a seguir demonstra como converter uma matriz de caracteres Unicode em blocos de bytes usando uma codificação especificada.The following example demonstrates how to convert an array of Unicode characters into blocks of bytes using a specified encoding. Para comparação, a matriz de caracteres é codificada primeiro usando UTF7Encoding.For comparison, the array of characters is first encoded using UTF7Encoding. Em seguida, a matriz de caracteres é codificada usando um Encoder.Next, the array of characters is encoded using an Encoder.

using namespace System;
using namespace System::Text;
using namespace System::Collections;
void ShowArray( Array^ theArray )
{
   IEnumerator^ myEnum = theArray->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Object^ o = safe_cast<Object^>(myEnum->Current);
      Console::Write( "[{0}]", o );
   }

   Console::WriteLine( "\n" );
}

int main()
{
   
   // The characters to encode.
   
   // Pi
   // Sigma
   array<Char>^chars = {L'\u03a0',L'\u03a3',L'\u03a6',L'\u03a9'};
   
   // Encode characters using an Encoding Object*.
   Encoding^ encoding = Encoding::UTF7;
   Console::WriteLine( "Using Encoding\n--------------" );
   
   // Encode complete array for comparison.
   array<Byte>^allCharactersFromEncoding = encoding->GetBytes( chars );
   Console::WriteLine( "All characters encoded:" );
   ShowArray( allCharactersFromEncoding );
   
   // Encode characters, one-by-one.
   // The Encoding Object* will NOT maintain state between calls.
   array<Byte>^firstchar = encoding->GetBytes( chars, 0, 1 );
   Console::WriteLine( "First character:" );
   ShowArray( firstchar );
   array<Byte>^secondchar = encoding->GetBytes( chars, 1, 1 );
   Console::WriteLine( "Second character:" );
   ShowArray( secondchar );
   array<Byte>^thirdchar = encoding->GetBytes( chars, 2, 1 );
   Console::WriteLine( "Third character:" );
   ShowArray( thirdchar );
   array<Byte>^fourthchar = encoding->GetBytes( chars, 3, 1 );
   Console::WriteLine( "Fourth character:" );
   ShowArray( fourthchar );
   
   // Now, encode characters using an Encoder Object*.
   Encoder^ encoder = encoding->GetEncoder();
   Console::WriteLine( "Using Encoder\n-------------" );
   
   // Encode complete array for comparison.
   array<Byte>^allCharactersFromEncoder = gcnew array<Byte>(encoder->GetByteCount( chars, 0, chars->Length, true ));
   encoder->GetBytes( chars, 0, chars->Length, allCharactersFromEncoder, 0, true );
   Console::WriteLine( "All characters encoded:" );
   ShowArray( allCharactersFromEncoder );
   
   // Do not flush state; i.e. maintain state between calls.
   bool bFlushState = false;
   
   // Encode characters one-by-one.
   // By maintaining state, the Encoder will not store extra bytes in the output.
   array<Byte>^firstcharNoFlush = gcnew array<Byte>(encoder->GetByteCount( chars, 0, 1, bFlushState ));
   encoder->GetBytes( chars, 0, 1, firstcharNoFlush, 0, bFlushState );
   Console::WriteLine( "First character:" );
   ShowArray( firstcharNoFlush );
   array<Byte>^secondcharNoFlush = gcnew array<Byte>(encoder->GetByteCount( chars, 1, 1, bFlushState ));
   encoder->GetBytes( chars, 1, 1, secondcharNoFlush, 0, bFlushState );
   Console::WriteLine( "Second character:" );
   ShowArray( secondcharNoFlush );
   array<Byte>^thirdcharNoFlush = gcnew array<Byte>(encoder->GetByteCount( chars, 2, 1, bFlushState ));
   encoder->GetBytes( chars, 2, 1, thirdcharNoFlush, 0, bFlushState );
   Console::WriteLine( "Third character:" );
   ShowArray( thirdcharNoFlush );
   
   // Must flush state on last call to GetBytes().
   bFlushState = true;
   array<Byte>^fourthcharNoFlush = gcnew array<Byte>(encoder->GetByteCount( chars, 3, 1, bFlushState ));
   encoder->GetBytes( chars, 3, 1, fourthcharNoFlush, 0, bFlushState );
   Console::WriteLine( "Fourth character:" );
   ShowArray( fourthcharNoFlush );
}

/* This code example produces the following output.

Using Encoding
--------------
All characters encoded:
[43][65][54][65][68][111][119][79][109][65][54][107][45]

First character:
[43][65][54][65][45]

Second character:
[43][65][54][77][45]

Third character:
[43][65][54][89][45]

Fourth character:
[43][65][54][107][45]

Using Encoder
-------------
All characters encoded:
[43][65][54][65][68][111][119][79][109][65][54][107][45]

First character:
[43][65][54]

Second character:
[65][68][111]

Third character:
[119][79][109]

Fourth character:
[65][54][107][45]


*/
using System;
using System.Text;

class EncoderTest {
    public static void Main() {
        // The characters to encode.
        Char[] chars = new Char[] {
            '\u0023', // #
            '\u0025', // %
            '\u03a0', // Pi
            '\u03a3'  // Sigma
        };

        // Encode characters using an Encoding object.
        Encoding encoding = Encoding.UTF7;
        Console.WriteLine("Using Encoding\n--------------");

        // Encode complete array for comparison.
        Byte[] allCharactersFromEncoding = encoding.GetBytes(chars);
        Console.WriteLine("All characters encoded:");
        ShowArray(allCharactersFromEncoding);

        // Encode characters, one-by-one.
        // The Encoding object will NOT maintain state between calls.
        Byte[] firstchar = encoding.GetBytes(chars, 0, 1);
        Console.WriteLine("First character:");
        ShowArray(firstchar);

        Byte[] secondchar = encoding.GetBytes(chars, 1, 1);
        Console.WriteLine("Second character:");
        ShowArray(secondchar);

        Byte[] thirdchar = encoding.GetBytes(chars, 2, 1);
        Console.WriteLine("Third character:");
        ShowArray(thirdchar);

        Byte[] fourthchar = encoding.GetBytes(chars, 3, 1);
        Console.WriteLine("Fourth character:");
        ShowArray(fourthchar);

        // Now, encode characters using an Encoder object.
        Encoder encoder = encoding.GetEncoder();
        Console.WriteLine("Using Encoder\n-------------");

        // Encode complete array for comparison.
        Byte[] allCharactersFromEncoder = new Byte[encoder.GetByteCount(chars, 0, chars.Length, true)];
        encoder.GetBytes(chars, 0, chars.Length, allCharactersFromEncoder, 0, true);
        Console.WriteLine("All characters encoded:");
        ShowArray(allCharactersFromEncoder);

        // Do not flush state; i.e. maintain state between calls.
        bool bFlushState = false;

        // Encode characters one-by-one.
        // By maintaining state, the Encoder will not store extra bytes in the output.
        Byte[] firstcharNoFlush = new Byte[encoder.GetByteCount(chars, 0, 1, bFlushState)];
        encoder.GetBytes(chars, 0, 1, firstcharNoFlush, 0, bFlushState);
        Console.WriteLine("First character:");
        ShowArray(firstcharNoFlush);

        Byte[] secondcharNoFlush = new Byte[encoder.GetByteCount(chars, 1, 1, bFlushState)];
        encoder.GetBytes(chars, 1, 1, secondcharNoFlush, 0, bFlushState);
        Console.WriteLine("Second character:");
        ShowArray(secondcharNoFlush);

        Byte[] thirdcharNoFlush = new Byte[encoder.GetByteCount(chars, 2, 1, bFlushState)];
        encoder.GetBytes(chars, 2, 1, thirdcharNoFlush, 0, bFlushState);
        Console.WriteLine("Third character:");
        ShowArray(thirdcharNoFlush);

        // Must flush state on last call to GetBytes().
        bFlushState = true;
        
        Byte[] fourthcharNoFlush = new Byte[encoder.GetByteCount(chars, 3, 1, bFlushState)];
        encoder.GetBytes(chars, 3, 1, fourthcharNoFlush, 0, bFlushState);
        Console.WriteLine("Fourth character:");
        ShowArray(fourthcharNoFlush);
    }

    public static void ShowArray(Array theArray) {
        foreach (Object o in theArray) {
            Console.Write("[{0}]", o);
        }
        Console.WriteLine("\n");
    }
}

/* This code example produces the following output.

Using Encoding
--------------
All characters encoded:
[43][65][67][77][65][74][81][79][103][65][54][77][45]

First character:
[43][65][67][77][45]

Second character:
[43][65][67][85][45]

Third character:
[43][65][54][65][45]

Fourth character:
[43][65][54][77][45]

Using Encoder
-------------
All characters encoded:
[43][65][67][77][65][74][81][79][103][65][54][77][45]

First character:
[43][65][67]

Second character:
[77][65][74]

Third character:
[81][79][103]

Fourth character:
[65][54][77][45]


*/
Imports System.Text
Imports Microsoft.VisualBasic.Strings

Class EncoderTest
    
    Public Shared Sub Main()
        ' Unicode characters.
        ' ChrW(35)  = #
        ' ChrW(37)  = %
        ' ChrW(928) = Pi
        ' ChrW(931) = Sigma
        Dim chars() As Char = {ChrW(35), ChrW(37), ChrW(928), ChrW(931)}
        
        ' Encode characters using an Encoding object.
        Dim encoding As Encoding = Encoding.UTF7
        Console.WriteLine( _
            "Using Encoding" & _
            ControlChars.NewLine & _
            "--------------" _
        )
        
        ' Encode complete array for comparison.
        Dim allCharactersFromEncoding As Byte() = encoding.GetBytes(chars)
        Console.WriteLine("All characters encoded:")
        ShowArray(allCharactersFromEncoding)
        
        ' Encode characters, one-by-one.
        ' The Encoding object will NOT maintain state between calls.
        Dim firstchar As Byte() = encoding.GetBytes(chars, 0, 1)
        Console.WriteLine("First character:")
        ShowArray(firstchar)
        
        Dim secondchar As Byte() = encoding.GetBytes(chars, 1, 1)
        Console.WriteLine("Second character:")
        ShowArray(secondchar)
        
        Dim thirdchar As Byte() = encoding.GetBytes(chars, 2, 1)
        Console.WriteLine("Third character:")
        ShowArray(thirdchar)
        
        Dim fourthchar As Byte() = encoding.GetBytes(chars, 3, 1)
        Console.WriteLine("Fourth character:")
        ShowArray(fourthchar)
        
        
        ' Now, encode characters using an Encoder object.
        Dim encoder As Encoder = encoding.GetEncoder()
        Console.WriteLine( _
            "Using Encoder" & _
            ControlChars.NewLine & _
            "-------------" _
        )
        
        ' Encode complete array for comparison.
        Dim allCharactersFromEncoder( _
            encoder.GetByteCount(chars, 0, chars.Length, True) _
        ) As Byte
        encoder.GetBytes(chars, 0, chars.Length, allCharactersFromEncoder, 0, True)
        Console.WriteLine("All characters encoded:")
        ShowArray(allCharactersFromEncoder)
        
        ' Do not flush state; i.e. maintain state between calls.
        Dim bFlushState As Boolean = False
        
        ' Encode characters one-by-one.
        ' By maintaining state, the Encoder will not store extra bytes in the output.
        Dim firstcharNoFlush( _
            encoder.GetByteCount(chars, 0, 1, bFlushState) _
        ) As Byte
        encoder.GetBytes(chars, 0, 1, firstcharNoFlush, 0, bFlushState)
        Console.WriteLine("First character:")
        ShowArray(firstcharNoFlush)
        
        Dim secondcharNoFlush( _
            encoder.GetByteCount(chars, 1, 1, bFlushState) _
        ) As Byte
        encoder.GetBytes(chars, 1, 1, secondcharNoFlush, 0, bFlushState)
        Console.WriteLine("Second character:")
        ShowArray(secondcharNoFlush)
        
        Dim thirdcharNoFlush( _
            encoder.GetByteCount(chars, 2, 1, bFlushState) _
        ) As Byte
        encoder.GetBytes(chars, 2, 1, thirdcharNoFlush, 0, bFlushState)
        Console.WriteLine("Third character:")
        ShowArray(thirdcharNoFlush)
        
        ' Must flush state on last call to GetBytes().
        bFlushState = True
        
        Dim fourthcharNoFlush( _
            encoder.GetByteCount(chars, 3, 1, bFlushState) _
        ) As Byte
        encoder.GetBytes(chars, 3, 1, fourthcharNoFlush, 0, bFlushState)
        Console.WriteLine("Fourth character:")
        ShowArray(fourthcharNoFlush)
    End Sub
    
    
    Public Shared Sub ShowArray(theArray As Array)
        Dim o As Object
        For Each o In  theArray
            Console.Write("[{0}]", o)
        Next o
        Console.WriteLine(ControlChars.NewLine)
    End Sub
End Class

'This code example produces the following output.
'
'Using Encoding
'--------------
'All characters encoded:
'[43][65][67][77][65][74][81][79][103][65][54][77][45]
'
'First character:
'[43][65][67][77][45]
'
'Second character:
'[43][65][67][85][45]
'
'Third character:
'[43][65][54][65][45]
'
'Fourth character:
'[43][65][54][77][45]
'
'Using Encoder
'-------------
'All characters encoded:
'[43][65][67][77][65][74][81][79][103][65][54][77][45][0]
'
'First character:
'[43][65][67][0]
'
'Second character:
'[77][65][74][0]
'
'Third character:
'[81][79][103][0]
'
'Fourth character:
'[65][54][77][45][0]
'

Comentários

Para obter uma instância de uma implementação da classe Encoder, o aplicativo deve usar o método GetEncoder de uma implementação de Encoding.To obtain an instance of an implementation of the Encoder class, the application should use the GetEncoder method of an Encoding implementation.

O método GetByteCount determina quantos bytes resultam na codificação de um conjunto de caracteres Unicode e o método GetBytes executa a codificação real.The GetByteCount method determines how many bytes result in encoding a set of Unicode characters, and the GetBytes method performs the actual encoding. Há várias versões de ambos os métodos disponíveis na classe Encoder.There are several versions of both of these methods available in the Encoder class. Para obter mais informações, consulte Encoding.GetBytes.For more information, see Encoding.GetBytes.

Um objeto Encoder mantém informações de estado entre chamadas sucessivas para GetBytes ou Convert métodos para que ele possa codificar corretamente Sequências de caracteres que abranjam blocos.A Encoder object maintains state information between successive calls to GetBytes or Convert methods so that it can correctly encode character sequences that span blocks. O Encoder também preserva os caracteres à direita no final dos blocos de dados e usa os caracteres à direita na próxima operação de codificação.The Encoder also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. Por exemplo, um bloco de dados pode terminar com um substituto alto inigualável e o substituto baixo correspondente pode estar no próximo bloco de dados.For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Portanto, GetDecoder e GetEncoder são úteis para operações de arquivo e transmissão de rede, pois essas operações geralmente lidam com blocos de dados em vez de um fluxo de dados completo.Therefore, GetDecoder and GetEncoder are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream.

Observação

Quando o aplicativo é concluído com um fluxo de dados, ele deve garantir que as informações de estado sejam liberadas definindo o parâmetro flush como true na chamada de método apropriada.When the application is done with a stream of data it should make sure that the state information is flushed by setting the flush parameter to true in the appropriate method call. Se ocorrer uma exceção ou se o aplicativo alternar fluxos, ele deverá chamar Reset para limpar o estado interno do objeto Encoder.If an exception occurs or if the application switches streams, it should call Reset to clear the internal state of the Encoder object.

Considerações da versãoVersion Considerations

Um objeto Decoder ou Encoder pode ser serializado durante uma operação de conversão.A Decoder or Encoder object can be serialized during a conversion operation. O estado do objeto será retido se for desserializado na mesma versão do .NET Framework, mas perdido se for desserializado em outra versão.The state of the object is retained if it is deserialized in the same version of the .NET Framework, but lost if it is deserialized in another version.

Notas aos Implementadores

Quando seu aplicativo herda dessa classe, ele deve substituir todos os membros.When your application inherits from this class, it must override all the members.

Construtores

Encoder()

Inicia uma nova instância da classe Encoder.Initializes a new instance of the Encoder class.

Propriedades

Fallback

Obtém ou define um objeto EncoderFallback para o objeto Encoder atual.Gets or sets a EncoderFallback object for the current Encoder object.

FallbackBuffer

Obtém o objeto EncoderFallbackBuffer associado ao objeto Encoder atual.Gets the EncoderFallbackBuffer object associated with the current Encoder object.

Métodos

Convert(Char*, Int32, Byte*, Int32, Boolean, Int32, Int32, Boolean)

Converte um buffer de caracteres Unicode em uma sequência de bytes codificados e armazena o resultado em outro buffer.Converts a buffer of Unicode characters to an encoded byte sequence and stores the result in another buffer.

Convert(Char[], Int32, Int32, Byte[], Int32, Int32, Boolean, Int32, Int32, Boolean)

Converte uma matriz de caracteres Unicode em uma sequência de bytes codificados e armazena o resultado em uma matriz de bytes.Converts an array of Unicode characters to an encoded byte sequence and stores the result in an array of bytes.

Convert(ReadOnlySpan<Char>, Span<Byte>, Boolean, Int32, Int32, Boolean)

Converte um intervalo de caracteres Unicode em uma sequência de bytes codificados e armazena o resultado em outro buffer.Converts a span of Unicode characters to an encoded byte sequence and stores the result in another buffer.

Equals(Object)

Determina se o objeto especificado é igual ao objeto atual.Determines whether the specified object is equal to the current object.

(Herdado de Object)
GetByteCount(Char*, Int32, Boolean)

Quando substituído em uma classe derivada, calcula o número de bytes produzidos pela codificação de um conjunto de caracteres começando no ponteiro de caracteres especificado.When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters starting at the specified character pointer. Um parâmetro indica se o estado interno do codificador após o cálculo deve ser limpo.A parameter indicates whether to clear the internal state of the encoder after the calculation.

GetByteCount(Char[], Int32, Int32, Boolean)

Quando substituído em uma classe derivada, calcula o número de bytes produzidos pela codificação de um conjunto de caracteres da matriz de caracteres especificada.When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified character array. Um parâmetro indica se o estado interno do codificador após o cálculo deve ser limpo.A parameter indicates whether to clear the internal state of the encoder after the calculation.

GetByteCount(ReadOnlySpan<Char>, Boolean)

Quando substituído em uma classe derivada, calcula o número de bytes produzidos pela codificação de um conjunto de caracteres no intervalo de “caracteres”.When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters in the 'chars' span. Um parâmetro indica se o estado interno do codificador após o cálculo deve ser limpo.A parameter indicates whether to clear the internal state of the encoder after the calculation.

GetBytes(Char*, Int32, Byte*, Int32, Boolean)

Quando substituído em uma classe derivada, decodifica um conjunto de caracteres começando no ponteiro de caracteres especificados e quaisquer caracteres no buffer na sequência de bytes que são armazenados no ponteiro de bytes indicado.When overridden in a derived class, encodes a set of characters starting at the specified character pointer and any characters in the internal buffer into a sequence of bytes that are stored starting at the specified byte pointer. Um parâmetro indica se você deseja limpar o estado interno do codificador após a conversão.A parameter indicates whether to clear the internal state of the encoder after the conversion.

GetBytes(Char[], Int32, Int32, Byte[], Int32, Boolean)

Quando substituído em uma classe derivada, codifica um conjunto de caracteres da matriz de caracteres especificada e quaisquer caracteres no buffer interno na matriz de bytes especificada.When overridden in a derived class, encodes a set of characters from the specified character array and any characters in the internal buffer into the specified byte array. Um parâmetro indica se você deseja limpar o estado interno do codificador após a conversão.A parameter indicates whether to clear the internal state of the encoder after the conversion.

GetBytes(ReadOnlySpan<Char>, Span<Byte>, Boolean)

Quando substituído em uma classe derivada, codifica um conjunto de caracteres no intervalo de caracteres de entrada e quaisquer caracteres no buffer interno em uma sequência de bytes que são armazenados no intervalo de bytes de entrada.When overridden in a derived class, encodes a set of characters in the input characters span and any characters in the internal buffer into a sequence of bytes that are stored in the input byte span. Um parâmetro indica se você deseja limpar o estado interno do codificador após a conversão.A parameter indicates whether to clear the internal state of the encoder after the conversion.

GetHashCode()

Serve como a função de hash padrão.Serves as the default hash function.

(Herdado de Object)
GetType()

Obtém o Type da instância atual.Gets the Type of the current instance.

(Herdado de Object)
MemberwiseClone()

Cria uma cópia superficial do Object atual.Creates a shallow copy of the current Object.

(Herdado de Object)
Reset()

Quando substituído em uma classe derivada, define o codificador de volta para o estado inicial.When overridden in a derived class, sets the encoder back to its initial state.

ToString()

Retorna uma cadeia de caracteres que representa o objeto atual.Returns a string that represents the current object.

(Herdado de Object)

Métodos de Extensão

Convert(Encoder, ReadOnlySequence<Char>, IBufferWriter<Byte>, Boolean, Int64, Boolean)
Convert(Encoder, ReadOnlySpan<Char>, IBufferWriter<Byte>, Boolean, Int64, Boolean)

Aplica-se a

Veja também