UnicodeEncoding Constructors

Definition

Namespace:

System.Text

Assemblies:

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

Initializes a new instance of the UnicodeEncoding class.

Overloads

UnicodeEncoding()	Initializes a new instance of the UnicodeEncoding class.
UnicodeEncoding(Boolean, Boolean)	Initializes a new instance of the UnicodeEncoding class. Parameters specify whether to use the big endian byte order and whether the GetPreamble() method returns a Unicode byte order mark.
UnicodeEncoding(Boolean, Boolean, Boolean)	Initializes a new instance of the UnicodeEncoding class. Parameters specify whether to use the big endian byte order, whether to provide a Unicode byte order mark, and whether to throw an exception when an invalid encoding is detected.

UnicodeEncoding()

Source:

UnicodeEncoding.cs

Initializes a new instance of the UnicodeEncoding class.

C#

public UnicodeEncoding();

Examples

The following example demonstrates how to create a new UnicodeEncoding instance and display the name of the encoding.

C#

using System;
using System.Text;

class UnicodeEncodingExample {
    public static void Main() {
        UnicodeEncoding unicode = new UnicodeEncoding();
        String encodingName = unicode.EncodingName;
        Console.WriteLine("Encoding name: " + encodingName);
    }
}

Remarks

This constructor creates an instance that uses the little endian byte order, provides a Unicode byte order mark, and does not throw an exception when an invalid encoding is detected.

Caution

For security reasons, you should enable error detection by calling the UnicodeEncoding(Boolean, Boolean, Boolean) constructor and setting its throwOnInvalidBytes argument to true.

UnicodeEncoding(Boolean, Boolean)

Source:

UnicodeEncoding.cs

Initializes a new instance of the UnicodeEncoding class. Parameters specify whether to use the big endian byte order and whether the GetPreamble() method returns a Unicode byte order mark.

C#

public UnicodeEncoding(bool bigEndian, bool byteOrderMark);

Parameters

bigEndian

Boolean

true to use the big endian byte order (most significant byte first), or false to use the little endian byte order (least significant byte first).

byteOrderMark

Boolean

true to specify that the GetPreamble() method returns a Unicode byte order mark; otherwise, false.

Examples

The following example demonstrates how to create a new UnicodeEncoding instance specifying whether to support little endian or big endian byte ordering and the Unicode byte order mark.

C#

using System;
using System.Text;

class UnicodeEncodingExample {
    public static void Main() {

        // Create a UnicodeEncoding without parameters.
        UnicodeEncoding unicode = new UnicodeEncoding();

        // Create a UnicodeEncoding to support little-endian byte ordering
        // and include the Unicode byte order mark.
        UnicodeEncoding unicodeLittleEndianBOM = 
            new UnicodeEncoding(false, true);
        // Compare this UnicodeEncoding to the UnicodeEncoding without parameters.
        DescribeEquivalence(unicode.Equals(unicodeLittleEndianBOM));

        // Create a UnicodeEncoding to support little-endian byte ordering
        // and not include the Unicode byte order mark.
        UnicodeEncoding unicodeLittleEndianNoBOM =
            new UnicodeEncoding(false, false);
        // Compare this UnicodeEncoding to the UnicodeEncoding without parameters.
        DescribeEquivalence(unicode.Equals(unicodeLittleEndianNoBOM));

        // Create a UnicodeEncoding to support big-endian byte ordering
        // and include the Unicode byte order mark.
        UnicodeEncoding unicodeBigEndianBOM =
            new UnicodeEncoding(true, true);
        // Compare this UnicodeEncoding to the UnicodeEncoding without parameters.
        DescribeEquivalence(unicode.Equals(unicodeBigEndianBOM));

        // Create a UnicodeEncoding to support big-endian byte ordering
        // and not include the Unicode byte order mark.
        UnicodeEncoding unicodeBigEndianNoBOM =
            new UnicodeEncoding(true, false);
        // Compare this UnicodeEncoding to the UnicodeEncoding without parameters.
        DescribeEquivalence(unicode.Equals(unicodeBigEndianNoBOM));
    }

    public static void DescribeEquivalence(Boolean isEquivalent) {
        Console.WriteLine(
            "{0} equivalent encoding.", (isEquivalent ? "An" : "Not an")
        );
    }
}

Remarks

This constructor creates an instance that does not throw an exception when an invalid encoding is detected.

Caution

For security reasons, you should enable error detection by calling the UnicodeEncoding(Boolean, Boolean, Boolean) constructor and setting its throwOnInvalidBytes argument to true.

The byteOrderMark parameter controls the operation of the GetPreamble method. If true, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-16 format. If false, it returns a zero-length byte array. However, setting byteOrderMark to true does not cause the GetBytes method to prefix the BOM at the beginning of the byte array, nor does it cause the GetByteCount method to include the number of bytes in the BOM in the byte count.

See also

• GetPreamble()

UnicodeEncoding(Boolean, Boolean, Boolean)

Source:

UnicodeEncoding.cs

Initializes a new instance of the UnicodeEncoding class. Parameters specify whether to use the big endian byte order, whether to provide a Unicode byte order mark, and whether to throw an exception when an invalid encoding is detected.

C#

public UnicodeEncoding(bool bigEndian, bool byteOrderMark, bool throwOnInvalidBytes);

Parameters

bigEndian

Boolean

true to use the big endian byte order (most significant byte first); false to use the little endian byte order (least significant byte first).

byteOrderMark

Boolean

true to specify that the GetPreamble() method returns a Unicode byte order mark; otherwise, false.

throwOnInvalidBytes

Boolean

true to specify that an exception should be thrown when an invalid encoding is detected; otherwise, false.

Examples

The following example demonstrates the behavior of UnicodeEncoding, both with error detection enabled and without.

C#

using System;
using System.Text;

public class SamplesUnicodeEncoding  {

   public static void Main()  {

      // Create an instance of UnicodeEncoding using little-endian byte order.
      // This will be used for encoding.
      UnicodeEncoding u16LE     = new UnicodeEncoding( false, true );

      // Create two instances of UnicodeEncoding using big-endian byte order: one with error detection and one without.
      // These will be used for decoding.
      UnicodeEncoding u16withED = new UnicodeEncoding( true, true, true );
      UnicodeEncoding u16noED   = new UnicodeEncoding( true, true, false );

      // Create byte arrays from the same string containing the following characters:
      //    Latin Small Letter Z (U+007A)
      //    Latin Small Letter A (U+0061)
      //    Combining Breve (U+0306)
      //    Latin Small Letter AE With Acute (U+01FD)
      //    Greek Small Letter Beta (U+03B2)
      //    Latin Capital Letter U with  Diaeresis (U+00DC)
      String myStr = "za\u0306\u01FD\u03B2\u00DC";

      // Encode the string using little-endian byte order.
      byte[] myBytes = new byte[u16LE.GetByteCount( myStr )];
      u16LE.GetBytes( myStr, 0, myStr.Length, myBytes, 0 );

      // Decode the byte array with error detection.
      Console.WriteLine( "Decoding with error detection:" );
      PrintDecodedString( myBytes, u16withED );

      // Decode the byte array without error detection.
      Console.WriteLine( "Decoding without error detection:" );
      PrintDecodedString( myBytes, u16noED );
   }

   // Decode the bytes and display the string.
   public static void PrintDecodedString( byte[] bytes, Encoding enc )  {

      try  {
         Console.WriteLine( "   Decoded string: {0}", enc.GetString( bytes, 0, bytes.Length ) );
      }
      catch ( System.ArgumentException e )  {
         Console.WriteLine( e.ToString() );
      }

      Console.WriteLine();
   }
}

Remarks

The byteOrderMark parameter controls the operation of the GetPreamble method. If true, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-16 format. If false, it returns a zero-length byte array. However, setting byteOrderMark to true does not cause the GetBytes method to prefix the BOM at the beginning of the byte array, nor does it cause the GetByteCount method to include the number of bytes in the BOM in the byte count.

If the throwOnInvalidBytes parameter is true, a method that detects an invalid byte sequence throws System.ArgumentException. Otherwise, the method does not throw an exception, and the invalid sequence is ignored.

Caution

For security reasons, you should use this constructor to create an instance of the UnicodeEncoding class and turn on error detection by setting throwOnInvalidBytes to true.

See also

• GetPreamble()