Encoder Класс

Определение

Конвертирует набор символов в последовательность байтов.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
Наследование
Encoder
Атрибуты

Примеры

В следующем примере показано, как преобразовать массив символов Юникода в блоки байтов, используя указанную кодировку.The following example demonstrates how to convert an array of Unicode characters into blocks of bytes using a specified encoding. Для сравнения массив символов сначала кодируется с помощью UTF7Encoding.For comparison, the array of characters is first encoded using UTF7Encoding. Затем массив символов кодируется с помощью 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]
'

Комментарии

Чтобы получить экземпляр реализации класса Encoder, приложение должно использовать метод GetEncoder реализации Encoding.To obtain an instance of an implementation of the Encoder class, the application should use the GetEncoder method of an Encoding implementation.

Метод GetByteCount определяет, сколько байт приводит к кодированию набора символов Юникода, а метод GetBytes выполняет фактическую кодировку.The GetByteCount method determines how many bytes result in encoding a set of Unicode characters, and the GetBytes method performs the actual encoding. Существует несколько версий обоих методов, доступных в классе Encoder.There are several versions of both of these methods available in the Encoder class. Дополнительные сведения см. в разделе Encoding.GetBytes.For more information, see Encoding.GetBytes.

Объект Encoder хранит сведения о состоянии между последовательными вызовами методов GetBytes или Convert, чтобы они могли правильно кодировать последовательности символов, охватывающие блоки.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. Encoder также сохраняет замыкающие символы в конце блоков данных и использует замыкающие символы в следующей операции кодирования.The Encoder also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. Например, блок данных может заканчиваться непарным старшим символом-заместителем, а соответствующий младший символ-заместитель может находиться в следующем блоке данных.For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Таким образом, GetDecoder и GetEncoder полезны для передачи по сети и операций с файлами, так как эти операции часто работают с блоками данных, а не с полным потоком данных.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.

Примечание

Когда приложение выполняется с помощью потока данных, необходимо убедиться, что сведения о состоянии сброшены, задав для параметра flush значение true в соответствующем вызове метода.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. Если возникает исключение или приложение переключает потоки, оно должно вызвать Reset, чтобы очистить внутреннее состояние объекта Encoder.If an exception occurs or if the application switches streams, it should call Reset to clear the internal state of the Encoder object.

Рекомендации по версиямVersion Considerations

Объект Decoder или Encoder может быть сериализован во время операции преобразования.A Decoder or Encoder object can be serialized during a conversion operation. Состояние объекта сохраняется, если он десериализуется в той же версии .NET Framework, но теряется, если он десериализуется в другой версии.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.

Примечания для тех, кто реализует этот метод

Когда приложение наследуется от этого класса, оно должно переопределять все члены.When your application inherits from this class, it must override all the members.

Конструкторы

Encoder()

Инициализация нового экземпляра класса Encoder.Initializes a new instance of the Encoder class.

Свойства

Fallback

Получает или задает объект EncoderFallback для текущего объекта Encoder.Gets or sets a EncoderFallback object for the current Encoder object.

FallbackBuffer

Получает объект EncoderFallbackBuffer, связанный с текущим объектом Encoder.Gets the EncoderFallbackBuffer object associated with the current Encoder object.

Методы

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

Преобразует буфер символов Юникода в закодированную последовательность байтов и сохраняет результат в другом буфере.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)

Преобразует массив символов Юникода в закодированную последовательность байтов и сохраняет результат в массиве байтов.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)

Преобразует диапазон символов Юникода в закодированную последовательность байтов и сохраняет результат в другом буфере.Converts a span of Unicode characters to an encoded byte sequence and stores the result in another buffer.

Equals(Object)

Определяет, равен ли указанный объект текущему объекту.Determines whether the specified object is equal to the current object.

(Унаследовано от Object)
GetByteCount(Char*, Int32, Boolean)

При переопределении в производном классе вычисляет количество байтов, полученных при кодировании набора символов, начиная с заданного указателя символа.When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters starting at the specified character pointer. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после расчета.A parameter indicates whether to clear the internal state of the encoder after the calculation.

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

При переопределении в производном классе вычисляет количество байтов, полученных при кодировании набора символов из указанного массива символов.When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified character array. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после расчета.A parameter indicates whether to clear the internal state of the encoder after the calculation.

GetByteCount(ReadOnlySpan<Char>, Boolean)

При переопределении в производном классе вычисляет число байтов, полученных при кодировании набора символов в диапазоне chars.When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters in the 'chars' span. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после расчета.A parameter indicates whether to clear the internal state of the encoder after the calculation.

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

При переопределении в производном классе кодирует набор символов, начало которого задается указателем символов, и все байты, расположенные во внутреннем буфере, в последовательность байтов, которые сохраняются, начиная с заданного указателя байтов.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. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после выполнения преобразования.A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

При переопределении в производном классе кодирует набор символов из заданного массива символов и все символы, расположенные во внутреннем буфере, в указанный массив байтов.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. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после выполнения преобразования.A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

При переопределении в производном классе кодирует набор символов во входном диапазоне символов и любые символы во внутреннем буфере в последовательность байтов, которые сохраняются во входном диапазоне байтов.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. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после выполнения преобразования.A parameter indicates whether to clear the internal state of the encoder after the conversion.

GetHashCode()

Служит в качестве хэш-функции по умолчанию.Serves as the default hash function.

(Унаследовано от Object)
GetType()

Возвращает объект Type для текущего экземпляра.Gets the Type of the current instance.

(Унаследовано от Object)
MemberwiseClone()

Создает неполную копию текущего объекта Object.Creates a shallow copy of the current Object.

(Унаследовано от Object)
Reset()

При переопределении в производном классе возвращает кодировщик в исходное состояние.When overridden in a derived class, sets the encoder back to its initial state.

ToString()

Возвращает строку, представляющую текущий объект.Returns a string that represents the current object.

(Унаследовано от Object)

Методы расширения

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

Применяется к

Дополнительно