Encoder::Convert Method (Char*, Int32, Byte*, Int32, Boolean, Int32%, Int32%, Boolean%)

Converts a buffer of Unicode characters to an encoded byte sequence and stores the result in another buffer.

This API is not CLS-compliant. The CLS-compliant alternative is Convert.

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

[ComVisibleAttribute(false)]
[CLSCompliantAttribute(false)]
public:
virtual void Convert(
	wchar_t* chars, 
	int charCount, 
	unsigned char* bytes, 
	int byteCount, 
	bool flush, 
	[OutAttribute] int% charsUsed, 
	[OutAttribute] int% bytesUsed, 
	[OutAttribute] bool% completed
)

Parameters

chars
Type: System::Char*

The address of a string of UTF-16 encoded characters to convert.

charCount
Type: System::Int32

The number of characters in chars to convert.

bytes
Type: System::Byte*

The address of a buffer to store the converted bytes.

byteCount
Type: System::Int32

The maximum number of bytes in 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 used in 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

charCount or byteCount is less than zero.

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 encode 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.

.NET Framework

Supported in: 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 Phone apps

Supported in: Windows Phone 8.1, Windows Phone Silverlight 8.1, Windows Phone Silverlight 8

  • SecurityCriticalAttribute 

    Requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.

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