UTF8Encoding Класс
Определение
Важно!
Некоторые сведения относятся к предварительной версии продукта, в которую до выпуска могут быть внесены существенные изменения. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.
Представляет кодировку UTF-8 символов Юникода.
public ref class UTF8Encoding : System::Text::Encodingpublic class UTF8Encoding : System.Text.Encoding[System.Serializable]
public class UTF8Encoding : System.Text.Encoding[System.Serializable]
[System.Runtime.InteropServices.ComVisible(true)]
public class UTF8Encoding : System.Text.Encodingtype UTF8Encoding = class
inherit Encoding[<System.Serializable>]
type UTF8Encoding = class
inherit Encoding[<System.Serializable>]
[<System.Runtime.InteropServices.ComVisible(true)>]
type UTF8Encoding = class
inherit EncodingPublic Class UTF8Encoding
Inherits Encoding- Наследование
- Атрибуты
Примеры
В следующем примере объект используется UTF8Encoding для кодирования строки символов Юникода и хранения их в массиве байтов. Строка Юникода содержит два символа: Pi (U+03A0) и Sigma (U+03A3), которые находятся за пределами диапазона символов ASCII. Когда кодированный массив байтов декодируется обратно в строку, символы Pi и Sigma по-прежнему присутствуют.
using System;
using System.Text;
class Example
{
public static void Main()
{
// Create a UTF-8 encoding.
UTF8Encoding utf8 = new UTF8Encoding();
// 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);
// Encode the string.
Byte[] encodedBytes = utf8.GetBytes(unicodeString);
Console.WriteLine();
Console.WriteLine("Encoded bytes:");
for (int ctr = 0; ctr < encodedBytes.Length; ctr++) {
Console.Write("{0:X2} ", encodedBytes[ctr]);
if ((ctr + 1) % 25 == 0)
Console.WriteLine();
}
Console.WriteLine();
// Decode bytes back to string.
String decodedString = utf8.GetString(encodedBytes);
Console.WriteLine();
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 (Σ).
//
// Encoded bytes:
// 54 68 69 73 20 55 6E 69 63 6F 64 65 20 73 74 72 69 6E 67 20 68 61 73 20 32
// 20 63 68 61 72 61 63 74 65 72 73 20 6F 75 74 73 69 64 65 20 74 68 65 20 41
// 53 43 49 49 20 72 61 6E 67 65 3A 20 0D 0A 50 69 20 28 CE A0 29 2C 20 61 6E
// 64 20 53 69 67 6D 61 20 28 CE A3 29 2E
//
// Decoded bytes:
// This Unicode string has 2 characters outside the ASCII range:
// Pi (π), and Sigma (Σ).
Imports System.Text
Class Example
Public Shared Sub Main()
' Create a UTF-8 encoding.
Dim utf8 As New UTF8Encoding()
' 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)
' Encode the string.
Dim encodedBytes As Byte() = utf8.GetBytes(unicodeString)
Console.WriteLine()
Console.WriteLine("Encoded bytes:")
For ctr As Integer = 0 To encodedBytes.Length - 1
Console.Write("{0:X2} ", encodedBytes(ctr))
If (ctr + 1) Mod 25 = 0 Then Console.WriteLine
Next
Console.WriteLine()
' Decode bytes back to string.
Dim decodedString As String = utf8.GetString(encodedBytes)
Console.WriteLine()
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 (Σ).
'
' Encoded bytes:
' 54 68 69 73 20 55 6E 69 63 6F 64 65 20 73 74 72 69 6E 67 20 68 61 73 20 32
' 20 63 68 61 72 61 63 74 65 72 73 20 6F 75 74 73 69 64 65 20 74 68 65 20 41
' 53 43 49 49 20 72 61 6E 67 65 3A 20 0D 0A 50 69 20 28 CE A0 29 2C 20 61 6E
' 64 20 53 69 67 6D 61 20 28 CE A3 29 2E
'
' Decoded bytes:
' This Unicode string has 2 characters outside the ASCII range:
' Pi (π), and Sigma (Σ).
В следующем примере используется та же строка, что и в предыдущем примере, за исключением того, что она записывает кодированные байты в файл и префиксирует поток байтов с меткой порядка байтов (BOM). Затем он считывает файл двумя разными способами: в виде текстового StreamReader файла с помощью объекта, а также в виде двоичного файла. Как и ожидалось, ни новая строка чтения не включает BOM.
using System;
using System.IO;
using System.Text;
public class Example
{
public static void Main()
{
// Create a UTF-8 encoding that supports a BOM.
Encoding utf8 = new UTF8Encoding(true);
// 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 = utf8.GetBytes(unicodeString);
Console.WriteLine("The encoded string has {0} bytes.",
encodedBytes.Length);
Console.WriteLine();
// Write the bytes to a file with a BOM.
var fs = new FileStream(@".\UTF8Encoding.txt", FileMode.Create);
Byte[] bom = utf8.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.
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 = utf8.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 88 bytes.
//
// Wrote 91 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-8 encoding that supports a BOM.
Dim utf8 As New UTF8Encoding(True)
' 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() = utf8.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(".\UTF8Encoding.txt", FileMode.Create)
Dim bom() As Byte = utf8.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(".\UTF8Encoding.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(".\UTF8Encoding.txt", FileMode.Open)
Dim bytes(fs.Length - 1) As Byte
fs.Read(bytes, 0, fs.Length)
fs.Close()
Dim decodedString As String = utf8.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 88 bytes.
'
' Wrote 91 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 (Σ).
Комментарии
Кодировка — это процесс преобразования набора символов Юникода в последовательность байтов. Декодирование — это процесс преобразования последовательности закодированных байтов в набор символов Юникода.
UTF-8 — это кодировка Юникода, представляющая каждую точку кода в виде последовательности от одного до четырех байтов. В отличие от кодировки UTF-16 и UTF-32, кодировка UTF-8 не требует "endianness"; Схема кодирования одинакова независимо от того, является ли процессор большим или маленьким. UTF8Encoding соответствует кодовой странице Windows 65001. Дополнительные сведения о UTFs и других кодировках, поддерживаемых System.Text, см. в разделе "Кодировка символов" в .NET Framework.
Вы можете создать экземпляр UTF8Encoding объекта несколькими способами в зависимости от того, нужно ли ему предоставить метку порядка байтов (BOM) и включить обнаружение ошибок. В следующей таблице перечислены конструкторы и Encoding свойство, возвращающее UTF8Encoding объект.
| Член | БОМ | Определение ошибки |
|---|---|---|
| Encoding.UTF8 | Yes | Нет (резервный вариант замены) |
| UTF8Encoding.UTF8Encoding() | No | Нет (резервный вариант замены) |
| UTF8Encoding.UTF8Encoding(Boolean) | Configurable | Нет (резервный вариант замены) |
| UTF8Encoding.UTF8Encoding(Boolean, Boolean) | Configurable | Configurable |
Метод GetByteCount определяет, сколько байтов приводит к кодированию набора символов Юникода, а GetBytes метод выполняет фактическую кодировку.
Аналогичным образом, GetCharCount метод определяет, сколько символов приводит к декодированию последовательности байтов, а GetCharsGetString методы выполняют фактическое декодирование.
Для кодировщика или декодировщика, который может сохранять сведения о состоянии при кодировании или декодировании данных, охватывающих несколько блоков (например, строка из 1 миллиона символов, закодированных в 100 000 символьных сегментов), используйте GetEncoderGetDecoder и свойства соответственно.
UTF8Encoding При необходимости объект предоставляет метку порядка байтов (BOM), которая представляет собой массив байтов, который можно префиксировать в начале потока байтов, который приводит к процессу кодирования. Если кодированный поток байтов в кодировке UTF-8 предусловлен меткой порядка байтов (BOM), он помогает декодеру определить порядок байтов и формат преобразования или UTF. Обратите внимание, что стандарт Юникода не требует и не рекомендует BOM в потоках в кодировке UTF-8. Дополнительные сведения о порядке байтов и отметке порядка байтов см. в разделе "Стандартный юникод" на домашней странице юникода .
Если кодировщик настроен для предоставления BOM, его можно получить, вызвав GetPreamble метод. В противном случае метод возвращает пустой массив. Обратите внимание, что даже если UTF8Encoding объект настроен для поддержки BOM, необходимо включить BOM в начале закодированного потока байтов в соответствии с соответствующим образом; методы UTF8Encoding кодирования класса не делают это автоматически.
Предостережение
Чтобы включить обнаружение ошибок и сделать экземпляр класса более безопасным, необходимо вызвать UTF8Encoding(Boolean, Boolean) конструктор и задать throwOnInvalidBytes для параметра значение true. При включенном обнаружении ошибок метод, который обнаруживает недопустимую последовательность символов или байтов ArgumentException , вызывает исключение. Без обнаружения ошибок исключение не возникает, а недопустимая последовательность обычно игнорируется.
Note
Состояние закодированного объекта UTF-8 не сохраняется, если объект сериализован и десериализирован с помощью разных версий .NET Framework.
Конструкторы
| Имя | Описание |
|---|---|
| UTF8Encoding() |
Инициализирует новый экземпляр класса UTF8Encoding. |
| UTF8Encoding(Boolean, Boolean) |
Инициализирует новый экземпляр класса UTF8Encoding. Параметры указывают, следует ли предоставлять метку порядка байтов Юникода и вызывать ли исключение при обнаружении недопустимой кодировки. |
| UTF8Encoding(Boolean) |
Инициализирует новый экземпляр класса UTF8Encoding. Параметр указывает, следует ли указать знак порядка байтов Юникода. |
Свойства
| Имя | Описание |
|---|---|
| BodyName |
При переопределении в производном классе получает имя текущей кодировки, которую можно использовать с тегами текста агента почты. (Унаследовано от Encoding) |
| CodePage |
При переопределении в производном классе получает идентификатор кодовой страницы текущего Encoding. (Унаследовано от Encoding) |
| DecoderFallback |
Возвращает или задает DecoderFallback объект для текущего Encoding объекта. (Унаследовано от Encoding) |
| EncoderFallback |
Возвращает или задает EncoderFallback объект для текущего Encoding объекта. (Унаследовано от Encoding) |
| EncodingName |
При переопределении в производном классе получает удобочитаемое пользователем описание текущей кодировки. (Унаследовано от Encoding) |
| HeaderName |
При переопределении в производном классе получает имя текущей кодировки, которую можно использовать с тегами заголовков агента почты. (Унаследовано от Encoding) |
| IsBrowserDisplay |
При переопределении в производном классе получает значение, указывающее, может ли текущая кодировка использоваться клиентами браузера для отображения содержимого. (Унаследовано от Encoding) |
| IsBrowserSave |
При переопределении в производном классе получает значение, указывающее, может ли текущая кодировка использоваться клиентами браузера для сохранения содержимого. (Унаследовано от Encoding) |
| IsMailNewsDisplay |
При переопределении в производном классе получает значение, указывающее, может ли текущая кодировка использоваться почтовыми клиентами и клиентами новостей для отображения содержимого. (Унаследовано от Encoding) |
| IsMailNewsSave |
При переопределении в производном классе получает значение, указывающее, может ли текущая кодировка использоваться почтовыми клиентами и клиентами новостей для сохранения содержимого. (Унаследовано от Encoding) |
| IsReadOnly |
При переопределении в производном классе получает значение, указывающее, доступна ли текущая кодировка только для чтения. (Унаследовано от Encoding) |
| IsSingleByte |
При переопределении в производном классе получает значение, указывающее, использует ли текущая кодировка точки кода с одним байтом. (Унаследовано от Encoding) |
| Preamble |
Возвращает метку порядка байтов Юникода, закодированную в формате UTF-8, если этот объект настроен для предоставления одного. |
| Preamble |
При переопределении в производном классе возвращает диапазон, содержащий последовательность байтов, указывающую используемую кодировку. (Унаследовано от Encoding) |
| WebName |
При переопределении в производном классе получает имя, зарегистрированное в Центр назначения номеров Интернета (IANA) для текущей кодировки. (Унаследовано от Encoding) |
| WindowsCodePage |
При переопределении в производном классе получает кодовую страницу операционной системы Windows, которая наиболее тесно соответствует текущей кодировке. (Унаследовано от Encoding) |
Методы
| Имя | Описание |
|---|---|
| Clone() |
При переопределении в производном классе создает неглубокую копию текущего Encoding объекта. (Унаследовано от Encoding) |
| Equals(Object) |
Определяет, равен ли указанный объект текущему UTF8Encoding объекту. |
| GetByteCount(Char[], Int32, Int32) |
Вычисляет количество байтов, созданных путем кодирования набора символов из указанного массива символов. |
| GetByteCount(Char[]) |
При переопределении в производном классе вычисляет количество байтов, созданных путем кодирования всех символов в указанном массиве символов. (Унаследовано от Encoding) |
| GetByteCount(Char*, Int32) |
Вычисляет количество байтов, созданных путем кодирования набора символов, начиная с указанного указателя символов. |
| GetByteCount(ReadOnlySpan<Char>) |
Вычисляет количество байтов, созданных путем кодирования указанного диапазона символов. |
| GetByteCount(ReadOnlySpan<Char>) |
При переопределении в производном классе вычисляет количество байтов, созданных путем кодирования символов в указанном диапазоне символов. (Унаследовано от Encoding) |
| GetByteCount(String, Int32, Int32) |
При переопределении в производном классе вычисляет количество байтов, созданных путем кодирования набора символов из указанной строки. (Унаследовано от Encoding) |
| GetByteCount(String) |
Вычисляет количество байтов, созданных путем кодирования символов в указанном.String |
| GetBytes(Char[], Int32, Int32, Byte[], Int32) |
Кодирует набор символов из указанного массива символов в указанный массив байтов. |
| GetBytes(Char[], Int32, Int32) |
При переопределении в производном классе кодирует набор символов из указанного массива символов в последовательность байтов. (Унаследовано от Encoding) |
| GetBytes(Char[]) |
При переопределении в производном классе кодирует все символы в указанном массиве символов в последовательность байтов. (Унаследовано от Encoding) |
| GetBytes(Char*, Int32, Byte*, Int32) |
Кодирует набор символов, начиная с указанного указателя символов, в последовательность байтов, хранящихся начиная с указанного указателя байтов. |
| GetBytes(ReadOnlySpan<Char>, Span<Byte>) |
Кодирует указанный диапазон символов в указанный диапазон байтов. |
| GetBytes(ReadOnlySpan<Char>, Span<Byte>) |
При переопределении в производном классе кодируется в диапазон байтов набор символов из указанного диапазона только для чтения. (Унаследовано от Encoding) |
| GetBytes(String, Int32, Int32, Byte[], Int32) |
Кодирует набор символов из указанного в указанный String массив байтов. |
| GetBytes(String, Int32, Int32) |
При переопределении в производном классе кодируется в массив байтов число символов, указанных |
| GetBytes(String) |
Кодирует символы в указанном String объекте в последовательность байтов. |
| GetBytes(String) |
При переопределении в производном классе кодирует все символы в указанной строке в последовательность байтов. (Унаследовано от Encoding) |
| GetCharCount(Byte[], Int32, Int32) |
Вычисляет количество символов, созданных путем декодирования последовательности байтов из указанного массива байтов. |
| GetCharCount(Byte[]) |
При переопределении в производном классе вычисляет количество символов, созданных путем декодирования всех байтов в указанном массиве байтов. (Унаследовано от Encoding) |
| GetCharCount(Byte*, Int32) |
Вычисляет количество символов, созданных путем декодирования последовательности байтов, начиная с указанного указателя байтов. |
| GetCharCount(ReadOnlySpan<Byte>) |
Вычисляет количество символов, созданных путем декодирования указанного диапазона байтов. |
| GetCharCount(ReadOnlySpan<Byte>) |
При переопределении в производном классе вычисляет количество символов, созданных путем декодирования предоставленного диапазона байтов только для чтения. (Унаследовано от Encoding) |
| GetChars(Byte[], Int32, Int32, Char[], Int32) |
Декодирует последовательность байтов из указанного массива байтов в указанный массив символов. |
| GetChars(Byte[], Int32, Int32) |
При переопределении в производном классе декодирует последовательность байтов из указанного массива байтов в набор символов. (Унаследовано от Encoding) |
| GetChars(Byte[]) |
При переопределении в производном классе декодирует все байты в указанном массиве байтов в набор символов. (Унаследовано от Encoding) |
| GetChars(Byte*, Int32, Char*, Int32) |
Декодирует последовательность байтов, начиная с указанного указателя байтов, в набор символов, хранящихся начиная с указанного указателя символов. |
| GetChars(ReadOnlySpan<Byte>, Span<Char>) |
Декодирует указанный диапазон байтов в указанный диапазон символов. |
| GetChars(ReadOnlySpan<Byte>, Span<Char>) |
При переопределении в производном классе декодирует все байты в указанном диапазоне байтов только для чтения в диапазон символов. (Унаследовано от Encoding) |
| GetDecoder() |
Получает декодатор, который преобразует кодировку UTF-8 байтов в последовательность символов Юникода. |
| GetEncoder() |
Получает кодировщик, который преобразует последовательность символов Юникода в кодировке UTF-8 в байтах. |
| GetHashCode() |
Возвращает хэш-код для текущего экземпляра. |
| GetMaxByteCount(Int32) |
Вычисляет максимальное количество байтов, созданных путем кодирования указанного числа символов. |
| GetMaxCharCount(Int32) |
Вычисляет максимальное количество символов, созданных путем декодирования указанного числа байтов. |
| GetPreamble() |
Возвращает метку порядка байтов Юникода, закодированную в формате UTF-8, если UTF8Encoding объект кодирования настроен для предоставления одного. |
| GetString(Byte[], Int32, Int32) |
Декодирует диапазон байтов из массива байтов в строку. |
| GetString(Byte[], Int32, Int32) |
При переопределении в производном классе декодирует последовательность байтов из указанного массива байтов в строку. (Унаследовано от Encoding) |
| GetString(Byte[]) |
При переопределении в производном классе декодирует все байты в указанном массиве байтов в строку. (Унаследовано от Encoding) |
| GetString(Byte*, Int32) |
При переопределении в производном классе декодирует указанное число байтов, начиная с указанного адреса в строку. (Унаследовано от Encoding) |
| GetString(ReadOnlySpan<Byte>) |
При переопределении в производном классе декодирует все байты в указанном диапазоне байтов в строку. (Унаследовано от Encoding) |
| GetType() |
Возвращает Type текущего экземпляра. (Унаследовано от Object) |
| IsAlwaysNormalized() |
Возвращает значение, указывающее, всегда ли текущая кодировка нормализована, используя форму нормализации по умолчанию. (Унаследовано от Encoding) |
| IsAlwaysNormalized(NormalizationForm) |
При переопределении в производном классе получает значение, указывающее, всегда ли текущая кодировка нормализована, используя указанную форму нормализации. (Унаследовано от Encoding) |
| MemberwiseClone() |
Создает неглубокую копию текущей Object. (Унаследовано от Object) |
| ToString() |
Возвращает строку, представляющую текущий объект. (Унаследовано от Object) |
| TryGetBytes(ReadOnlySpan<Char>, Span<Byte>, Int32) |
Кодирует в диапазон байтов набор символов из указанного диапазона только для чтения, если целевой объект достаточно велик. |
| TryGetChars(ReadOnlySpan<Byte>, Span<Char>, Int32) |
Декодирует в диапазон символов набор байтов из указанного диапазона только для чтения, если целевой объект достаточно велик. |
