Article
11/18/2011

Encoding Class

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Represents a character encoding.

Inheritance Hierarchy

System.Object
  System.Text.Encoding
    System.Text.UnicodeEncoding
    System.Text.UTF8Encoding

Namespace: System.Text
Assembly: mscorlib (in mscorlib.dll)

Syntax

'Declaration
<ComVisibleAttribute(True)> _
Public MustInherit Class Encoding

[ComVisibleAttribute(true)]
public abstract class Encoding

The Encoding type exposes the following members.

Constructors

	Name	Description
	Encoding	Initializes a new instance of the Encoding class.

Top

Properties

	Name	Description
	BigEndianUnicode	Gets an encoding for the UTF-16 format that uses the big-endian byte order.
	Unicode	Gets an encoding for the UTF-16 format using the little-endian byte order.
	UTF8	Gets an encoding for the UTF-8 format.
	WebName	When overridden in a derived class, gets the name registered with the Internet Assigned Numbers Authority (IANA) for the current encoding.

Top

Methods

	Name	Description
	Clone	When overridden in a derived class, creates a shallow copy of the current Encoding object.
	Convert(Encoding, Encoding, array<Byte[])	Converts an entire byte array from one encoding to another.
	Convert(Encoding, Encoding, array<Byte[], Int32, Int32)	Converts a range of bytes in a byte array from one encoding to another.
	Equals	Determines whether the specified Object is equal to the current instance. (Overrides Object.Equals(Object).)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
	GetByteCount(array<Char[])	When overridden in a derived class, calculates the number of bytes produced by encoding all the characters in the specified character array.
	GetByteCount(String)	When overridden in a derived class, calculates the number of bytes produced by encoding the characters in the specified string.
	GetByteCount(array<Char[], Int32, Int32)	When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified character array.
	GetBytes(array<Char[])	When overridden in a derived class, encodes all the characters in the specified character array into a sequence of bytes.
	GetBytes(String)	When overridden in a derived class, encodes all the characters in the specified string into a sequence of bytes.
	GetBytes(array<Char[], Int32, Int32)	When overridden in a derived class, encodes a set of characters from the specified character array into a sequence of bytes.
	GetBytes(Char, Int32, Byte, Int32)	Security Critical. When overridden in a derived class, encodes a set of characters starting at the specified character pointer into a sequence of bytes that are stored starting at the specified byte pointer.
	GetBytes(array<Char[], Int32, Int32, array<Byte[], Int32)	When overridden in a derived class, encodes a set of characters from the specified character array into the specified byte array.
	GetBytes(String, Int32, Int32, array<Byte[], Int32)	When overridden in a derived class, encodes a set of characters from the specified string into the specified byte array.
	GetCharCount(array<Byte[])	When overridden in a derived class, calculates the number of characters produced by decoding all the bytes in the specified byte array.
	GetCharCount(array<Byte[], Int32, Int32)	When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes from the specified byte array.
	GetChars(array<Byte[])	When overridden in a derived class, decodes all the bytes in the specified byte array into a set of characters.
	GetChars(array<Byte[], Int32, Int32)	When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a set of characters.
	GetChars(array<Byte[], Int32, Int32, array<Char[], Int32)	When overridden in a derived class, decodes a sequence of bytes from the specified byte array into the specified character array.
	GetDecoder	When overridden in a derived class, obtains a decoder that converts an encoded sequence of bytes into a sequence of characters.
	GetEncoder	When overridden in a derived class, obtains an encoder that converts a sequence of Unicode characters into an encoded sequence of bytes.
	GetEncoding	Returns the encoding associated with the specified name.
	GetHashCode	Returns the hash code for the current instance. (Overrides Object.GetHashCode().)
	GetMaxByteCount	When overridden in a derived class, calculates the maximum number of bytes produced by encoding the specified number of characters.
	GetMaxCharCount	When overridden in a derived class, calculates the maximum number of characters produced by decoding the specified number of bytes.
	GetPreamble	When overridden in a derived class, returns a sequence of bytes that specifies the encoding used.
	GetString	When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a string.
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

Remarks

Encoding is the process of transforming a set of Unicode characters into a sequence of bytes. In contrast, decoding is the process of transforming a sequence of encoded bytes into a set of Unicode characters. The .NET Framework for Silverlight supports two encoding methods: UTF8, in which a single character is encoded in one to four bytes; and UTF16 or Unicode, in which a single character is represented as either a two-byte or a four-byte value. Because Encoding is the base class for all encodings, it can also be derived from to create custom encodings for the .NET Framework for Silverlight.

The .NET Framework for Silverlight includes the following implementations of the Encoding class to support Unicode encoding:

The UTF8Encoding class, which uses UTF8 encoding to represent a single character in one to four bytes. A class instance is also available through the UTF8 property.
The UnicodeEncoding class, which uses UTF16 encoding to represent a single character as either a two-byte or a four-byte value. Both little-endian and big-endian byte orders are supported. These encoders are also available through the Unicode property and the BigEndianUnicode property, respectively.

The Encoding class is primarily intended to convert between these three different Unicode encodings. In addition, you can derive from the Encoding class to create a custom encoding that is not supported by the .NET Framework for Silverlight.

Note:
If you require an encoding that is not present in the .NET Framework for Silverlight, you can also use ASP.NET and the .NET Framework to perform the encoding or decoding on a Web server.

Your applications can instantiate an encoding object that represents a specific encoding in several ways:

By calling one of the overloads of that encoding's class constructor.
By retrieving the value of the BigEndianUnicode, Unicode, or UTF8 properties, depending on the encoding desired.
By calling the GetEncoding method with the name of an encoding to obtain that encoding.

The GetByteCount method determines how many bytes result from encoding a set of Unicode characters, and the GetBytes method performs the actual encoding. The Encoding.GetBytes method expects discrete conversions (that is, each method call converts the bytes passed to it without including the unconverted bytes from the previous method call). In contrast, the GetBytes method, because it preserves state between method calls, can decode a single input stream in multiple method calls.

Several versions of GetByteCount and GetBytes are supported. The following are some programming considerations for using these methods:

The application might need to encode a stream, such as an input stream from the user. This can be done by using multiple calls to the GetBytes method because it maintains state between calls.
For string input, you should call the overloads of the GetBytes method that encode the strings passed to them.
If your application must convert a large amount of data, it should reuse the output buffer. In this case, the GetBytes version that supports byte arrays is the best choice.
Consider using the Encoder.Convert method instead of GetByteCount. The conversion method converts as much data as possible, and throws an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice.

The GetCharCount method determines how many characters result from decoding a sequence of bytes, and the Encoding.GetChars method performs the actual decoding. The Encoding.GetChars method expects discrete conversions (that is, it treats each method call independently of the previous method call). In contrast, the GetChars method preserves state so that it can decode undecoded bytes from the previous method call. This makes it suitable for decoding a stream of bytes.

Several versions of GetCharCount and GetChars are supported. The following are some programming considerations for use of these methods:

The application might need to decode multiple input bytes and process the bytes using multiple calls. In this case, your application probably needs to maintain state between calls.
If the application handles string outputs, it is recommended to use the GetString method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting String type is to be preferred.
If your application must convert a large amount of data, it should reuse the output buffer. In this case, the Encoding.GetChars(array<Byte[], Int32, Int32, array<Char[], Int32) version that supports output character buffers is the best choice.
Consider using the Decoder.Convert method instead of GetCharCount. The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice.

If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, your application should use the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively, of a derived class.

The UTF-16 encoder can use the big-endian byte order (most significant byte first) or the little-endian byte order (least significant byte first). For example, the Latin Capital Letter A (U+0041) is encoded as follows (in hexadecimal):

UTF-16 big-endian byte order: 00 41
UTF-16 little-endian byte order: 41 00

It is generally more efficient to store Unicode characters using the native byte order. For example, it is better to use the little-endian byte order on little-endian platforms, such as Intel computers, and the big-endian order on big-endian platforms.

The GetPreamble method retrieves an array of bytes that includes the byte order mark (BOM). If this byte array is prefixed to an encoded stream, it helps the decoder to identify the encoding format used.

For more information on byte order and the byte order mark, see The Unicode Standard at the Unicode home page.

Examples

The following code example converts a string from one encoding to another.

Imports System.Text

Class Example
   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      Dim unicodeString As String = "This string contains the unicode character Pi(" & ChrW(&H3A0) & ")"

      ' Create two different encodings.
      Dim utf8 As Encoding = Encoding.UTF8
      Dim unicode As Encoding = Encoding.Unicode

      ' Convert the string into a byte[].
      Dim unicodeBytes As Byte() = unicode.GetBytes(unicodeString)

      ' Perform the conversion from one encoding to the other.
      Dim utf8Bytes As Byte() = Encoding.Convert(unicode, utf8, unicodeBytes)

      ' Convert the new byte[] into a char[] and then into a string.
      Dim utf8Chars(utf8.GetCharCount(utf8Bytes, 0, utf8Bytes.Length) - 1) As Char
      utf8.GetChars(utf8Bytes, 0, utf8Bytes.Length, utf8Chars, 0)
      Dim utf8String As New String(utf8Chars)

      ' Display the strings created before and after the conversion.
      outputBlock.Text += String.Format("Original string: {0}", unicodeString) & vbCrLf
      outputBlock.Text += String.Format("Ascii converted string: {0}", utf8String) & vbCrLf
   End Sub
End Class
' The example displays the following output:
'    Original string: This string contains the unicode character Pi (Π)
'    Ascii converted string: This string contains the unicode character Pi (?)

using System;
using System.Text;

class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      string unicodeString = "This string contains the unicode character Pi (\u03a0)";

      // Create two different encodings.
      Encoding utf8 = Encoding.UTF8;
      Encoding unicode = Encoding.Unicode;

      // Convert the string into a byte[].
      byte[] unicodeBytes = unicode.GetBytes(unicodeString);

      // Perform the conversion from one encoding to the other.
      byte[] utf8Bytes = Encoding.Convert(unicode, utf8, unicodeBytes);

      // Convert the new byte[] into a char[] and then into a string.
      char[] utf8Chars = new char[utf8.GetCharCount(utf8Bytes, 0, utf8Bytes.Length)];
      utf8.GetChars(utf8Bytes, 0, utf8Bytes.Length, utf8Chars, 0);
      string utf8String = new string(utf8Chars);

      // Display the strings created before and after the conversion.
      outputBlock.Text += String.Format("Original string: {0}", unicodeString) + "\n";
      outputBlock.Text += String.Format("Ascii converted string: {0}", utf8String) + "\n";
   }
}
// The example displays the following output:
//    Original string: This string contains the unicode character Pi (Π)
//    Ascii converted string: This string contains the unicode character Pi (?)

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Partager via