Table 12-9: Methods of the Encoding-Derived Classes Method
Description mark (BOM) byte. When you start reading from a stream, the BOM bytes automatically help detect what encoding was used when the stream was written so that the correct decoder can be used. For most Encodingderived classes, this method returns an array of 0 bytes—that is, no preamble bytes. A UTF8Encoding object can be explicitly constructed so that this method returns a 3-byte array of 0xEF, 0xBB, 0xBF. A UnicodeEncoding object can be explicitly constructed so that this method returns a 2-byte array of 0xFE, 0xFF for big endian encoding or a 2-byte array of 0xFF, 0xFE for little endian encoding.
Convert
Converts an array of bytes specified in a source encoding to an array of bytes specified by a destination encoding. Internally, this static method calls the source encoding object’s GetChars method and passes the result to the destination encoding object’s GetBytes method. The resulting byte array is returned to the caller.
Equals
Returns true if two Encoding-derived objects represent the same code page and preamble setting.
GetHashCode
Returns the encoding object’s code page.
Encoding/Decoding Streams of Characters and Bytes Imagine that you’re reading a UTF-16 encoded string via a System.Net.Sockets.NetworkStream object. The bytes will very likely stream in as chunks of data. In other words, you might first read 5 bytes from the stream, followed by 7 bytes. In UTF-16, each character consists of 2 bytes. So calling Encoding’s GetString method passing the first array of 5 bytes will return a string consisting of just two characters. If you later call GetString passing in the next 7 bytes that come in from the stream, GetString will return a string consisting of three characters and all the code points will have the wrong values! This data corruption problem occurs because none of the Encoding-derived classes maintains any state in between calls to their methods. If you’ll be encoding or decoding characters/bytes in chunks, you must do some additional work so that state is maintained between calls, preventing any loss of data. To decode chunks of bytes, you should obtain a reference to an Encoding-derived object (as described in the previous section) and call its GetDecoder method. This method returns a reference to a newly constructed object whose type is derived from the System.Text.Decoder class. Like the Encoding class, the Decoder class is an abstract base class. If you look in the .NET Framework SDK documentation, you won’t find any classes that represent concrete implementations of the Decoder class. However, the FCL does define a bunch of Decoder-derived classes, such as UTF8Decoder. These classes are all internal to the FCL, but the GetDecoder method can construct instances of these classes and return them to your application code.