• Article

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

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

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

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

Syntax

'Declaration
<ComVisibleAttribute(False)> _
Public Overridable Sub Convert ( _
    chars As Char(), _
    charIndex As Integer, _
    charCount As Integer, _
    bytes As Byte(), _
    byteIndex As Integer, _
    byteCount As Integer, _
    flush As Boolean, _
    <OutAttribute> ByRef charsUsed As Integer, _
    <OutAttribute> ByRef bytesUsed As Integer, _
    <OutAttribute> ByRef completed As Boolean _
)

[ComVisibleAttribute(false)]
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: array<System.Char[]
    An array of characters to convert.
  • charIndex
    Type: System.Int32
    The zero-based index of the first element of chars to convert.
  • charCount
    Type: System.Int32
    The number of elements of chars to convert.
  • bytes
    Type: array<System.Byte[]
    An array where the converted bytes are stored.
  • byteIndex
    Type: System.Int32
    The zero-based index of 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.

Exceptions

Exception Condition
ArgumentNullException

chars or bytes is nulla null reference (Nothing in Visual Basic).
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 Understanding Encodings for fuller explanation).

Remarks

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.

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.

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.