Encoder.Convert Method (Char[], Int32, Int32, Byte[], Int32, Int32, Boolean, Int32, Int32, Boolean)

Converts an array of Unicode characters to an encoded byte sequence and stores the result in an array of bytes.

Namespace:  System.Text
Assemblies:   System.Text.Encoding (in System.Text.Encoding.dll)
  mscorlib (in mscorlib.dll)

public virtual void Convert(
	char[] chars,
	int charIndex,
	int charCount,
	byte[] bytes,
	int byteIndex,
	int byteCount,
	bool flush,
	out int charsUsed,
	out int bytesUsed,
	out bool completed
)

Parameters

chars
Type: System.Char[]

An array of characters to convert.

charIndex
Type: System.Int32

The first element of chars to convert.

charCount
Type: System.Int32

The number of elements of chars to convert.

bytes
Type: System.Byte[]

An array where the converted bytes are stored.

byteIndex
Type: System.Int32

The first element of bytes in which data is stored.

byteCount
Type: System.Int32

The maximum number of elements of bytes to use in the conversion.

flush
Type: System.Boolean

true to indicate no further data is to be converted; otherwise, false.

charsUsed
Type: System.Int32

When this method returns, contains the number of characters from chars that were used in the conversion. This parameter is passed uninitialized.

bytesUsed
Type: System.Int32

When this method returns, contains the number of bytes that were produced by the conversion. This parameter is passed uninitialized.

completed
Type: System.Boolean

When this method returns, contains true if all the characters specified by charCount were converted; otherwise, false. This parameter is passed uninitialized.

ExceptionCondition
ArgumentNullException

chars or bytes is null (Nothing).

ArgumentOutOfRangeException

charIndex, charCount, byteIndex, or byteCount is less than zero.

-or-

The length of chars - charIndex is less than charCount.

-or-

The length of bytes - byteIndex is less than byteCount.

ArgumentException

The output buffer is too small to contain any of the converted input. The output buffer should be greater than or equal to the size indicated by the GetByteCount method.

EncoderFallbackException

A fallback occurred (see Character Encoding in the .NET Framework for fuller explanation)

-and-

Fallback is set to EncoderExceptionFallback.

Remember that the Encoder object saves state between calls to Convert. When the application is done with a stream of data, it should set the flush parameter to true to make sure that the state information is flushed. With this setting, the encoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings.

The Convert method is designed to be used in a loop to decode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the encoding operation in a fixed-size buffer. GetBytes will throw an exception if the output buffer isn't large enough, but Convert will fill as much space as possible and return the chars read and bytes written. Also see the Encoding.GetBytes topic for more comments.

The completed output parameter indicates whether all the data in the input buffer was converted and stored in the output buffer. This parameter is set to false if the number of characters specified by the charCount parameter cannot be converted without exceeding the number of bytes specified by the byteCount parameter. In that situation, the application should use the contents of the output buffer or provide a new output buffer, increment the chars parameter by the number of characters specified by the charsUsed parameter, then call the Convert method again to process the remaining input.

The completed parameter can also be set to false, even though the charsUsed and charCount parameters are equal. This situation occurs if there is still data in the Encoder object that has not been stored in the chars buffer.

The following example uses the Convert method to convert a file of UTF-16 characters to UTF-8, then uses the Convert method to convert the UTF-8 characters back to UTF-16 characters.

// This code example demonstrates the Encoder.Convert() and Decoder.Convert methods.  
// This example uses files for input and output, but any source that can be expressed 
// as a stream can be used instead. 

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

    public class Sample
    {
    static void Main(string[] args)
        {
// Create a large file of UTF-16 encoded Unicode characters. The file is named Example.txt,  
// and is used as input to the Encoder.Convert() method. 

            CreateTestFile("Example.txt");


// Using an input file of UTF-16 encoded characters named Example.txt, create an output file  
// of UTF-8 encoded bytes named UTF8.txt.

            EncoderConvert("Example.txt", "UTF8.txt", Encoding.UTF8);

// Using an input file of UTF-8 encoded bytes named UTF8.txt, create an output file  
// of UTF-16 encoded characters named UTF16.txt.

            DecoderConvert("UTF8.txt", "UTF16.txt", Encoding.UTF8);
        }

// -------------------------------------------------------------------------------------------- 
// Use the Encoder.Convert() method to convert a file of characters to a file of encoded bytes. 
// -------------------------------------------------------------------------------------------- 
        static void EncoderConvert(String inputFileName, String outputFileName, Encoding enc)
        {
// Convert an input file of characters to an output file of encoded bytes. 
// StreamWriter could convert the input file for us, but we'll perform the conversion  
// ourselves.

            FileStream fs = new FileStream(outputFileName, FileMode.Create);
            BinaryWriter outputFile = new BinaryWriter(fs);

// StreamReader will detect Unicode encoding from the Byte Order Mark that heads the input file.
            StreamReader inputFile = new StreamReader(inputFileName);

// Get an Encoder.
            Encoder encoder = enc.GetEncoder();

// Guarantee the output buffer large enough to convert a few characters. 
            int UseBufferSize = 64;
            if (UseBufferSize < enc.GetMaxByteCount(10))
                    UseBufferSize = enc.GetMaxByteCount(10);
            byte[] bytes = new byte[UseBufferSize];

// Intentionally make the input character buffer larger than the output byte buffer so the  
// conversion loop executes more than one cycle.  

            char[] chars = new char[UseBufferSize * 4];
            int charsRead;
            do
            {
// Read at most the number of characters that will fit in the input buffer. The return  
// value is the actual number of characters read, or zero if no characters remain. 
                charsRead = inputFile.Read(chars, 0, UseBufferSize * 4);

                bool completed = false;
                int charIndex = 0;
                int charsUsed;
                int bytesUsed;

                while (!completed)
                {
// If this is the last input data, flush the encoder's internal buffer and state. 

                    bool flush = (charsRead == 0);
                    encoder.Convert(chars, charIndex, charsRead - charIndex,
                                    bytes, 0, UseBufferSize, flush,
                                    out charsUsed, out bytesUsed, out completed);

// The conversion produced the number of bytes indicated by bytesUsed. Write that number 
// of bytes to the output file.
                    outputFile.Write(bytes, 0, bytesUsed);

// Increment charIndex to the next block of characters in the input buffer, if any, to convert.
                    charIndex += charsUsed;
                }
            }
            while(charsRead != 0);

            outputFile.Close();
            fs.Close();
            inputFile.Close();
        }

// -------------------------------------------------------------------------------------------- 
// Use the Decoder.Convert() method to convert a file of encoded bytes to a file of characters. 
// -------------------------------------------------------------------------------------------- 
        static void DecoderConvert(String inputFileName, String outputFileName, Encoding enc)
        {
// Convert an input file of of encoded bytes to an output file characters. 
// StreamWriter could convert the input file for us, but we'll perform the conversion  
// ourselves.

            StreamWriter outputFile = new StreamWriter(outputFileName, false, Encoding.Unicode);

// Read the input as a binary file so we can detect the Byte Order Mark.
            FileStream fs = new FileStream(inputFileName, FileMode.Open);
            BinaryReader inputFile = new BinaryReader(fs);

// Get a Decoder.
            Decoder decoder = enc.GetDecoder();

// Guarantee the output buffer large enough to convert a few characters. 
            int UseBufferSize = 64;
            if (UseBufferSize < enc.GetMaxCharCount(10))
                    UseBufferSize = enc.GetMaxCharCount(10);
            char[] chars = new char[UseBufferSize];

// Intentionally make the input byte buffer larger than the output character buffer so the  
// conversion loop executes more than one cycle.  

            byte[] bytes = new byte[UseBufferSize * 4];
            int bytesRead;
            do
            {
// Read at most the number of bytes that will fit in the input buffer. The  
// return value is the actual number of bytes read, or zero if no bytes remain. 

                bytesRead = inputFile.Read(bytes, 0, UseBufferSize * 4);

                bool completed = false;
                int byteIndex = 0;
                int bytesUsed;
                int charsUsed;

                while (!completed)
                {
// If this is the last input data, flush the decoder's internal buffer and state. 

                    bool flush = (bytesRead == 0);
                    decoder.Convert(bytes, byteIndex, bytesRead - byteIndex,
                                    chars, 0, UseBufferSize, flush,
                                    out bytesUsed, out charsUsed, out completed);

// The conversion produced the number of characters indicated by charsUsed. Write that number 
// of characters to the output file.

                    outputFile.Write(chars, 0, charsUsed);

// Increment byteIndex to the next block of bytes in the input buffer, if any, to convert.
                    byteIndex += bytesUsed;
                }
            }
            while(bytesRead != 0);

            outputFile.Close();
            fs.Close();
            inputFile.Close();
        }        

// -------------------------------------------------------------------------------------------- 
// Create a large file of UTF-16 encoded Unicode characters.  
// -------------------------------------------------------------------------------------------- 
        static void CreateTestFile(String FileName)
        {
// StreamWriter defaults to UTF-8 encoding so explicitly specify Unicode, that is,  
// UTF-16, encoding.
            StreamWriter file = new StreamWriter(FileName, false, Encoding.Unicode);

// Write a line of text 100 times. 
            for (int i = 0; i < 100; i++)
            {
                file.WriteLine("This is an example input file used by the convert example.");
            }

// Write Unicode characters from U+0000 to, but not including, the surrogate character range. 
            for (char c = (char)0; c < (char)0xD800; c++)
            {
                file.Write(c);
            }
            file.Close();
        }
    }

/*
This code example produces the following results:

(Execute the -dir- console window command and examine the files created.)

Example.txt, which contains 122,594 bytes (61,297 UTF-16 encoded characters).
UTF8.txt, which contains 169,712 UTF-8 encoded bytes.
UTF16.txt, which contains 122,594 bytes (61,297 UTF-16 encoded characters).

(Execute the -comp- console window command and compare the two Unicode files.)

>comp example.txt utf16.txt /L
Comparing example.txt and utf16.txt...
Files compare OK

(The two files are equal.)

*/

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

Supported in: Windows Phone 8.1

Supported in: Windows Phone Silverlight 8.1

Supported in: Windows Phone Silverlight 8

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft