UnicodeEncoding Classe

Definição

Namespace:

System.Text

Assemblies:

netstandard.dll, System.Text.Encoding.Extensions.dll

Origem:

UnicodeEncoding.cs

Representa uma codificação UTF-16 de caracteres Unicode.

public ref class UnicodeEncoding : System::Text::Encoding

public class UnicodeEncoding : System.Text.Encoding

type UnicodeEncoding = class
    inherit Encoding

Public Class UnicodeEncoding
Inherits Encoding

Herança

Object

Encoding

UnicodeEncoding

Exemplos

O exemplo a seguir demonstra como codificar uma cadeia de caracteres Unicode em uma matriz de bytes usando um UnicodeEncoding objeto. A matriz de bytes é decodificada em uma cadeia de caracteres para demonstrar que não há perda de dados.

using System;
using System.Text;

class UnicodeEncodingExample {
    public static void Main() {
        // The encoding.
        UnicodeEncoding unicode = new UnicodeEncoding();
        
        // Create a string that contains Unicode characters.
        String unicodeString =
            "This Unicode string contains two characters " +
            "with codes outside the traditional ASCII code range, " +
            "Pi (\u03a0) and Sigma (\u03a3).";
        Console.WriteLine("Original string:");
        Console.WriteLine(unicodeString);

        // Encode the string.
        Byte[] encodedBytes = unicode.GetBytes(unicodeString);
        Console.WriteLine();
        Console.WriteLine("Encoded bytes:");
        foreach (Byte b in encodedBytes) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine();
        
        // Decode bytes back to string.
        // Notice Pi and Sigma characters are still present.
        String decodedString = unicode.GetString(encodedBytes);
        Console.WriteLine();
        Console.WriteLine("Decoded bytes:");
        Console.WriteLine(decodedString);
    }
}

Imports System.Text
Imports Microsoft.VisualBasic.Strings

Class UnicodeEncodingExample
    
    Public Shared Sub Main()
        ' The encoding.
        Dim uni As New UnicodeEncoding()
        
        ' Create a string that contains Unicode characters.
        Dim unicodeString As String = _
            "This Unicode string contains two characters " & _
            "with codes outside the traditional ASCII code range, " & _
            "Pi (" & ChrW(928) & ") and Sigma (" & ChrW(931) & ")."
        Console.WriteLine("Original string:")
        Console.WriteLine(unicodeString)
        
        ' Encode the string.
        Dim encodedBytes As Byte() = uni.GetBytes(unicodeString)
        Console.WriteLine()
        Console.WriteLine("Encoded bytes:")
        Dim b As Byte
        For Each b In  encodedBytes
            Console.Write("[{0}]", b)
        Next b
        Console.WriteLine()
        
        ' Decode bytes back to string.
        ' Notice Pi and Sigma characters are still present.
        Dim decodedString As String = uni.GetString(encodedBytes)
        Console.WriteLine()
        Console.WriteLine("Decoded bytes:")
        Console.WriteLine(decodedString)
    End Sub
End Class

O exemplo a seguir usa a mesma cadeia de caracteres que a anterior, exceto que grava os bytes codificados em um arquivo e prefixa o fluxo de bytes com uma marca de ordem de byte (BOM). Em seguida, ele lê o arquivo de duas maneiras diferentes: como um arquivo de texto usando um StreamReader objeto; e como um arquivo binário. Como seria de esperar, nenhuma cadeia de caracteres recém-lida inclui o BOM.

using System;
using System.IO;
using System.Text;

public class Example
{
   public static void Main()
   {
        // Create a UTF-16 encoding that supports a BOM.
        Encoding unicode = new UnicodeEncoding();

        // A Unicode string with two characters outside an 8-bit code range.
        String unicodeString =
            "This Unicode string has 2 characters outside the " +
            "ASCII range: \n" +
            "Pi (\u03A0)), and Sigma (\u03A3).";
        Console.WriteLine("Original string:");
        Console.WriteLine(unicodeString);
        Console.WriteLine();

        // Encode the string.
        Byte[] encodedBytes = unicode.GetBytes(unicodeString);
        Console.WriteLine("The encoded string has {0} bytes.\n",
                          encodedBytes.Length);

        // Write the bytes to a file with a BOM.
        var fs = new FileStream(@".\UTF8Encoding.txt", FileMode.Create);
        Byte[] bom = unicode.GetPreamble();
        fs.Write(bom, 0, bom.Length);
        fs.Write(encodedBytes, 0, encodedBytes.Length);
        Console.WriteLine("Wrote {0} bytes to the file.\n", fs.Length);
        fs.Close();

        // Open the file using StreamReader.
        var sr = new StreamReader(@".\UTF8Encoding.txt");
        String newString = sr.ReadToEnd();
        sr.Close();
        Console.WriteLine("String read using StreamReader:");
        Console.WriteLine(newString);
        Console.WriteLine();

        // Open the file as a binary file and decode the bytes back to a string.
        fs = new FileStream(@".\UTF8Encoding.txt", FileMode.Open);
        Byte[] bytes = new Byte[fs.Length];
        fs.Read(bytes, 0, (int)fs.Length);
        fs.Close();

        String decodedString = unicode.GetString(bytes);
        Console.WriteLine("Decoded bytes:");
        Console.WriteLine(decodedString);
   }
}
// The example displays the following output:
//    Original string:
//    This Unicode string has 2 characters outside the ASCII range:
//    Pi (π), and Sigma (Σ).
//
//    The encoded string has 172 bytes.
//
//    Wrote 174 bytes to the file.
//
//    String read using StreamReader:
//    This Unicode string has 2 characters outside the ASCII range:
//    Pi (π), and Sigma (Σ).
//
//    Decoded bytes:
//    This Unicode string has 2 characters outside the ASCII range:
//    Pi (π), and Sigma (Σ).

Imports System.IO
Imports System.Text

Class Example
    Public Shared Sub Main()
        ' Create a UTF-16 encoding that supports a BOM.
        Dim unicode As New UnicodeEncoding()
        
        ' A Unicode string with two characters outside an 8-bit code range.
        Dim unicodeString As String = _
            "This Unicode string has 2 characters outside the " &
            "ASCII range: " & vbCrLf &
            "Pi (" & ChrW(&h03A0) & "), and Sigma (" & ChrW(&h03A3) & ")."
        Console.WriteLine("Original string:")
        Console.WriteLine(unicodeString)
        Console.WriteLine()
        
        ' Encode the string.
        Dim encodedBytes As Byte() = unicode.GetBytes(unicodeString)
        Console.WriteLine("The encoded string has {0} bytes.",
                          encodedBytes.Length)
        Console.WriteLine()
        
        ' Write the bytes to a file with a BOM.
        Dim fs As New FileStream(".\UnicodeEncoding.txt", FileMode.Create)
        Dim bom() As Byte = unicode.GetPreamble()
        fs.Write(bom, 0, bom.Length)
        fs.Write(encodedBytes, 0, encodedBytes.Length)
        Console.WriteLine("Wrote {0} bytes to the file.", fs.Length)
        fs.Close()
        Console.WriteLine()
        
        ' Open the file using StreamReader.
        Dim sr As New StreamReader(".\UnicodeEncoding.txt")
        Dim newString As String = sr.ReadToEnd()
        sr.Close()
        Console.WriteLine("String read using StreamReader:")
        Console.WriteLine(newString)
        Console.WriteLine()
        
        ' Open the file as a binary file and decode the bytes back to a string.
        fs = new FileStream(".\UnicodeEncoding.txt", FileMode.Open)
        Dim bytes(fs.Length - 1) As Byte
        fs.Read(bytes, 0, fs.Length)
        fs.Close()

        Dim decodedString As String = unicode.GetString(bytes)
        Console.WriteLine("Decoded bytes:")
        Console.WriteLine(decodedString)
    End Sub
End Class
' The example displays the following output:
'    Original string:
'    This Unicode string has 2 characters outside the ASCII range:
'    Pi (π), and Sigma (Σ).
'
'    The encoded string has 172 bytes.
'
'    Wrote 174 bytes to the file.
'
'    String read using StreamReader:
'    This Unicode string has 2 characters outside the ASCII range:
'    Pi (π), and Sigma (Σ).
'
'    Decoded bytes:
'    This Unicode string has 2 characters outside the ASCII range:
'    Pi (π), and Sigma (Σ).

Comentários

A codificação é o processo de transformação de um conjunto de caracteres Unicode em uma sequência de bytes. A decodificação é o processo de transformar uma sequência de bytes codificados em um conjunto de caracteres Unicode.

O Padrão Unicode atribui um ponto de código (um número) a cada caractere em cada script com suporte. Um UTF (Formato de Transformação Unicode) é uma maneira de codificar esse ponto de código. O Padrão Unicode usa os seguintes UTFs:

• UTF-8, que representa cada ponto de código como uma sequência de um a quatro bytes.

• UTF-16, que representa cada ponto de código como uma sequência de um a dois inteiros de 16 bits.

• UTF-32, que representa cada ponto de código como um inteiro de 32 bits.

Para obter mais informações sobre os UTFs e outras codificações com suporte System.Text, consulte Codificação de Caracteres no .NET Framework.

A UnicodeEncoding classe representa uma codificação UTF-16. O codificador pode usar a ordem de bytes de big endian (primeiro byte mais significativo) ou a ordem de byte de endian (bytes menos significativos primeiro). Por exemplo, a Letra Maiúscula Latina A (ponto de código U+0041) é serializada da seguinte maneira (em hexadecimal):

• Ordem de bytes de big endian: 00 00 00 41

• Ordem de byte de endian pequeno: 41 00 00 00

Geralmente, é mais eficiente armazenar caracteres Unicode usando a ordem de bytes nativa de uma plataforma específica. Por exemplo, é melhor usar a ordem dos bytes de little endian em plataformas little endian, como computadores da Intel. A UnicodeEncoding classe corresponde às páginas de código do Windows 1200 (ordem de bytes little endian) e 1201 (ordem de bytes big endian). Você pode determinar a "endianidade" de uma arquitetura específica chamando o BitConverter.IsLittleEndian método.

Opcionalmente, o UnicodeEncoding objeto fornece uma marca de ordem de bytes (BOM), que é uma matriz de bytes que pode ser prefixada na sequência de bytes resultantes do processo de codificação. Se o preâmbulo contiver uma marca de ordem de byte (BOM), ele ajudará o decodificador a determinar a ordem de bytes e o formato de transformação ou UTF.

Se a UnicodeEncoding instância estiver configurada para fornecer um BOM, você poderá recuperá-la chamando o GetPreamble método; caso contrário, o método retornará uma matriz vazia. Observe que, mesmo que um UnicodeEncoding objeto esteja configurado para suporte a BOM, você deve incluir o BOM no início do fluxo de bytes codificado conforme apropriado; os métodos de codificação da UnicodeEncoding classe não fazem isso automaticamente.

Cuidado

Para habilitar a detecção de erros e tornar a instância de classe mais segura, você deve criar uma instância de um UnicodeEncoding objeto chamando o UnicodeEncoding(Boolean, Boolean, Boolean) construtor e definindo seu throwOnInvalidBytes argumento como true. Com a detecção de erros, um método que detecta uma sequência inválida de caracteres ou bytes lança um ArgumentException. Sem a detecção de erros, nenhuma exceção é gerada e a sequência inválida geralmente é ignorada.

Você pode criar uma instância de um UnicodeEncoding objeto de várias maneiras, dependendo se deseja que ele forneça uma marca de ordem de byte (BOM), quer você queira codificação big-endian ou little-endian e se deseja habilitar a detecção de erros. A tabela a seguir lista os UnicodeEncoding construtores e as Encoding propriedades que retornam um UnicodeEncoding objeto.

Membro	Endianidade	LBM - Lista de materiais	Detecção de erro
BigEndianUnicode	Big-endian	Sim	Não (fallback de substituição)
Encoding.Unicode	Little-endian (ordem de bytes do menos significativo para o mais significativo)	Sim	Não (fallback de substituição)
UnicodeEncoding.UnicodeEncoding()	Little-endian (ordem de bytes do menos significativo para o mais significativo)	Sim	Não (fallback de substituição)
UnicodeEncoding(Boolean, Boolean)	Configurable	Configurable	Não (fallback de substituição)
UnicodeEncoding.UnicodeEncoding(Boolean, Boolean, Boolean)	Configurable	Configurable	Configurable

O GetByteCount método determina quantos bytes resultam na codificação de um conjunto de caracteres Unicode e o GetBytes método executa a codificação real.

Da mesma forma, o GetCharCount método determina quantos caracteres resultam na decodificação de uma sequência de bytes e os GetChars métodos e GetString executam a decodificação real.

Para um codificador ou decodificador que é capaz de salvar informações de estado ao codificar ou decodificar dados que abrangem vários blocos (como cadeia de caracteres de 1 milhão de caracteres que é codificada em segmentos de 100.000 caracteres), use o e GetDecoder as GetEncoder propriedades, respectivamente.

Construtores

Nome	Description
UnicodeEncoding()	Inicializa uma nova instância da classe UnicodeEncoding.
UnicodeEncoding(Boolean, Boolean, Boolean)	Inicializa uma nova instância da classe UnicodeEncoding. Os parâmetros especificam se a ordem de bytes do big endian deve ser usada, se uma marca de ordem de bytes Unicode deve ser fornecida e se uma exceção será gerada quando uma codificação inválida for detectada.
UnicodeEncoding(Boolean, Boolean)	Inicializa uma nova instância da classe UnicodeEncoding. Os parâmetros especificam se a ordem de bytes do big endian deve ser usada e se o GetPreamble() método retorna uma marca de ordem de bytes Unicode.

Campos

Nome	Description
CharSize	Representa o tamanho do caractere Unicode em bytes. Esse campo é uma constante.

Propriedades

Nome	Description
BodyName	Quando substituído em uma classe derivada, obtém um nome para a codificação atual que pode ser usada com marcas de corpo do agente de email. (Herdado de Encoding)
CodePage	Quando substituído em uma classe derivada, obtém o identificador de página de código do atual Encoding. (Herdado de Encoding)
DecoderFallback	Obtém ou define o DecoderFallback objeto para o objeto atual Encoding . (Herdado de Encoding)
EncoderFallback	Obtém ou define o EncoderFallback objeto para o objeto atual Encoding . (Herdado de Encoding)
EncodingName	Quando substituído em uma classe derivada, obtém a descrição legível por humanos da codificação atual. (Herdado de Encoding)
HeaderName	Quando substituído em uma classe derivada, obtém um nome para a codificação atual que pode ser usada com marcas de cabeçalho do agente de email. (Herdado de Encoding)
IsBrowserDisplay	Quando substituído em uma classe derivada, obtém um valor que indica se a codificação atual pode ser usada por clientes do navegador para exibir conteúdo. (Herdado de Encoding)
IsBrowserSave	Quando substituído em uma classe derivada, obtém um valor que indica se a codificação atual pode ser usada por clientes do navegador para salvar conteúdo. (Herdado de Encoding)
IsMailNewsDisplay	Quando substituído em uma classe derivada, obtém um valor que indica se a codificação atual pode ser usada por clientes de email e notícias para exibir conteúdo. (Herdado de Encoding)
IsMailNewsSave	Quando substituído em uma classe derivada, obtém um valor que indica se a codificação atual pode ser usada por clientes de email e notícias para salvar conteúdo. (Herdado de Encoding)
IsReadOnly	Quando substituído em uma classe derivada, obtém um valor que indica se a codificação atual é somente leitura. (Herdado de Encoding)
IsSingleByte	Quando substituído em uma classe derivada, obtém um valor que indica se a codificação atual usa pontos de código de byte único. (Herdado de Encoding)
Preamble	Obtém uma marca de ordem de bytes Unicode codificada no formato UTF-16, se esse objeto estiver configurado para fornecer um.
WebName	Quando substituído em uma classe derivada, obtém o nome registrado com a IANA (Autoridade de Números Atribuídos à Internet) para a codificação atual. (Herdado de Encoding)
WindowsCodePage	Quando substituído em uma classe derivada, obtém a página de código do sistema operacional Windows que corresponde mais de perto à codificação atual. (Herdado de Encoding)

Métodos

Nome	Description
Clone()	Quando substituído em uma classe derivada, cria uma cópia superficial do objeto atual Encoding . (Herdado de Encoding)
Equals(Object)	Determina se o especificado Object é igual ao objeto atual UnicodeEncoding .
GetByteCount(Char[], Int32, Int32)	Calcula o número de bytes produzidos codificando um conjunto de caracteres da matriz de caracteres especificada.
GetByteCount(Char[])	Quando substituído em uma classe derivada, calcula o número de bytes produzidos pela codificação de todos os caracteres na matriz de caracteres especificada. (Herdado de Encoding)
GetByteCount(Char*, Int32)	Calcula o número de bytes produzidos codificando um conjunto de caracteres começando no ponteiro de caractere especificado.
GetByteCount(ReadOnlySpan<Char>)	Quando substituído em uma classe derivada, calcula o número de bytes produzidos pela codificação dos caracteres no intervalo de caracteres especificado. (Herdado de Encoding)
GetByteCount(String, Int32, Int32)	Quando substituído em uma classe derivada, calcula o número de bytes produzidos pela codificação de um conjunto de caracteres da cadeia de caracteres especificada. (Herdado de Encoding)
GetByteCount(String)	Calcula o número de bytes produzidos codificando os caracteres na cadeia de caracteres especificada.
GetBytes(Char[], Int32, Int32, Byte[], Int32)	Codifica um conjunto de caracteres da matriz de caracteres especificada na matriz de bytes especificada.
GetBytes(Char[], Int32, Int32)	Quando substituído em uma classe derivada, codifica um conjunto de caracteres da matriz de caracteres especificada em uma sequência de bytes. (Herdado de Encoding)
GetBytes(Char[])	Quando substituído em uma classe derivada, codifica todos os caracteres na matriz de caracteres especificada em uma sequência de bytes. (Herdado de Encoding)
GetBytes(Char*, Int32, Byte*, Int32)	Codifica um conjunto de caracteres começando no ponteiro de caractere especificado em uma sequência de bytes que são armazenados a partir do ponteiro de bytes especificado.
GetBytes(ReadOnlySpan<Char>, Span<Byte>)	Quando substituído em uma classe derivada, codifica em um intervalo de bytes um conjunto de caracteres do intervalo somente leitura especificado. (Herdado de Encoding)
GetBytes(String, Int32, Int32, Byte[], Int32)	Codifica um conjunto de caracteres do especificado String na matriz de bytes especificada.
GetBytes(String, Int32, Int32)	Quando substituído em uma classe derivada, codifica em uma matriz de bytes o número de caracteres especificado pela count cadeia de caracteres especificada, começando pelo especificado index. (Herdado de Encoding)
GetBytes(String)	Quando substituído em uma classe derivada, codifica todos os caracteres na cadeia de caracteres especificada em uma sequência de bytes. (Herdado de Encoding)
GetCharCount(Byte[], Int32, Int32)	Calcula o número de caracteres produzidos decodificação de uma sequência de bytes da matriz de bytes especificada.
GetCharCount(Byte[])	Quando substituído em uma classe derivada, calcula o número de caracteres produzidos pela decodificação de todos os bytes na matriz de bytes especificada. (Herdado de Encoding)
GetCharCount(Byte*, Int32)	Calcula o número de caracteres produzidos decodificação de uma sequência de bytes começando no ponteiro de bytes especificado.
GetCharCount(ReadOnlySpan<Byte>)	Quando substituído em uma classe derivada, calcula o número de caracteres produzidos pela decodificação do intervalo de bytes somente leitura fornecido. (Herdado de Encoding)
GetChars(Byte[], Int32, Int32, Char[], Int32)	Decodifica uma sequência de bytes da matriz de bytes especificada na matriz de caracteres especificada.
GetChars(Byte[], Int32, Int32)	Quando substituído em uma classe derivada, decodifica uma sequência de bytes da matriz de bytes especificada em um conjunto de caracteres. (Herdado de Encoding)
GetChars(Byte[])	Quando substituído em uma classe derivada, decodifica todos os bytes na matriz de bytes especificada em um conjunto de caracteres. (Herdado de Encoding)
GetChars(Byte*, Int32, Char*, Int32)	Decodifica uma sequência de bytes começando no ponteiro de bytes especificado em um conjunto de caracteres armazenados a partir do ponteiro de caractere especificado.
GetChars(ReadOnlySpan<Byte>, Span<Char>)	Quando substituído em uma classe derivada, decodifica todos os bytes no intervalo de bytes somente leitura especificado em um intervalo de caracteres. (Herdado de Encoding)
GetDecoder()	Obtém um decodificador que converte uma sequência de bytes codificada em UTF-16 em uma sequência de caracteres Unicode.
GetEncoder()	Obtém um codificador que converte uma sequência de caracteres Unicode em uma sequência de bytes codificada em UTF-16.
GetHashCode()	Retorna o código hash da instância atual.
GetMaxByteCount(Int32)	Calcula o número máximo de bytes produzidos codificando o número especificado de caracteres.
GetMaxCharCount(Int32)	Calcula o número máximo de caracteres produzidos decodificação do número especificado de bytes.
GetPreamble()	Retorna uma marca de ordem de byte Unicode codificada no formato UTF-16, se o construtor dessa instância solicitar uma marca de ordem de byte.
GetString(Byte[], Int32, Int32)	Decodifica um intervalo de bytes de uma matriz de bytes em uma cadeia de caracteres.
GetString(Byte[])	Quando substituído em uma classe derivada, decodifica todos os bytes na matriz de bytes especificada em uma cadeia de caracteres. (Herdado de Encoding)
GetString(Byte*, Int32)	Quando substituído em uma classe derivada, decodifica um número especificado de bytes começando em um endereço especificado em uma cadeia de caracteres. (Herdado de Encoding)
GetString(ReadOnlySpan<Byte>)	Quando substituído em uma classe derivada, decodifica todos os bytes no intervalo de bytes especificado em uma cadeia de caracteres. (Herdado de Encoding)
GetType()	Obtém o Type da instância atual. (Herdado de Object)
IsAlwaysNormalized()	Obtém um valor que indica se a codificação atual está sempre normalizada, usando o formulário de normalização padrão. (Herdado de Encoding)
IsAlwaysNormalized(NormalizationForm)	Quando substituído em uma classe derivada, obtém um valor que indica se a codificação atual está sempre normalizada, usando o formulário de normalização especificado. (Herdado de Encoding)
MemberwiseClone()	Cria uma cópia superficial do Objectatual. (Herdado de Object)
ToString()	Retorna uma cadeia de caracteres que representa o objeto atual. (Herdado de Object)
TryGetBytes(ReadOnlySpan<Char>, Span<Byte>, Int32)	Codifica em um intervalo de bytes um conjunto de caracteres do intervalo somente leitura especificado se o destino for grande o suficiente. (Herdado de Encoding)
TryGetChars(ReadOnlySpan<Byte>, Span<Char>, Int32)	Decodifica em um intervalo de caracteres um conjunto de bytes do intervalo somente leitura especificado se o destino for grande o suficiente. (Herdado de Encoding)

Métodos de Extensão

Nome	Description
GetBytes(Encoding, ReadOnlySequence<Char>, IBufferWriter<Byte>)	Decodifica o especificado ReadOnlySequence<T> para bytes usando o especificado Encoding e grava o resultado em writer.
GetBytes(Encoding, ReadOnlySequence<Char>, Span<Byte>)	Codifica o especificado ReadOnlySequence<T> para bytes usando o especificado Encoding e gera o resultado para bytes.
GetBytes(Encoding, ReadOnlySequence<Char>)	Codifica o especificado ReadOnlySequence<T> em uma Byte matriz usando o especificado Encoding.
GetBytes(Encoding, ReadOnlySpan<Char>, IBufferWriter<Byte>)	Codifica o especificado ReadOnlySpan<T> para bytes usando o especificado Encoding e grava o resultado writerem .
GetChars(Encoding, ReadOnlySequence<Byte>, IBufferWriter<Char>)	Decodifica o especificado ReadOnlySequence<T> para chars usando o especificado Encoding e grava o resultado em writer.
GetChars(Encoding, ReadOnlySequence<Byte>, Span<Char>)	Decodifica o especificado ReadOnlySequence<T> para chars usando o especificado Encoding e gera o resultado para chars.
GetChars(Encoding, ReadOnlySpan<Byte>, IBufferWriter<Char>)	Decodifica o especificado ReadOnlySpan<T> para chars usando o especificado Encoding e grava o resultado em writer.
GetString(Encoding, ReadOnlySequence<Byte>)	Decodifica o especificado ReadOnlySequence<T> em um String usando o .Encoding

Confira também

• Encoding
• Encoder
• Decoder
• UTF32Encoding
• UTF8Encoding
• UTF7Encoding
• ASCIIEncoding
• UnicodeCategory
• CharUnicodeInfo
• Noções básicas sobre codificações