UTF32Encoding.GetBytes Method (Char*, Int32, Byte*, Int32)

 
System_CAPS_noteNote

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Encodes a set of characters starting at the specified character pointer into a sequence of bytes that are stored starting at the specified byte pointer.

This API is not CLS-compliant.

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

Visual Basic does not support APIs that consume or return unsafe types.

Parameters

chars
Type: System.Char*

A pointer to the first character to encode.

charCount
Type: System.Int32

The number of characters to encode.

bytes
Type: System.Byte*

A pointer to the location at which to start writing the resulting sequence of bytes.

byteCount
Type: System.Int32

The maximum number of bytes to write.

Return Value

Type: System.Int32

The actual number of bytes written at the location indicated by the bytes parameter.

Exception Condition
ArgumentNullException

chars is null.

-or-

bytes is null.

ArgumentOutOfRangeException

charCount or byteCount is less than zero.

ArgumentException

Error detection is enabled, and chars contains an invalid sequence of characters.

-or-

byteCount is less than the resulting number of bytes.

EncoderFallbackException

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

-and-

EncoderFallback is set to EncoderExceptionFallback.

To calculate the exact array size required by GetBytes to store the resulting bytes, you call the GetByteCount method. To calculate the maximum array size, you call the GetMaxByteCount method. The GetByteCount method generally allocates less memory, while the GetMaxByteCount method generally executes faster.

With error detection, an invalid sequence causes this method to throw a ArgumentException. Without error detection, invalid sequences are ignored, and no exception is thrown.

Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively.

System_CAPS_noteNote

To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The GetBytes method does not prepend a preamble to the beginning of a sequence of encoded bytes.

SecurityCriticalAttribute

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

Universal Windows Platform
Available since 10
.NET Framework
Available since 2.0
Return to top
Show: