System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
1.0.5000.0
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
System.Text.Encoding
[System.Runtime.CompilerServices.Nullable(0)]
[<System.Runtime.CompilerServices.Nullable(0)>]
[System.Serializable]
[<System.Serializable>]
[System.Runtime.InteropServices.ComVisible(true)]
[<System.Runtime.InteropServices.ComVisible(true)>]
Represents a UTF-7 encoding of Unicode characters.
[!NOTE]
> does not provide error detection. For security reasons, the application should use , , or and enable error detection.
For more information about the UTFs and other encodings supported by , see [Character Encoding in the .NET Framework](/dotnet/standard/base-types/character-encoding).
The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding.
Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding.
corresponds to the Windows code page 65000.
> [!NOTE]
> The state of a UTF-7 encoded object is not preserved if the object is serialized and deserialized using different .NET Framework versions.
## Examples
The following code example demonstrates how to use a to encode a string of Unicode characters and store them in a byte array. Notice that when the byte array is decoded back to a string, no data is lost.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/Overview/snippet.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/Overview/snippet.vb" id="Snippet1":::
]]>
Understanding Encodings
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
Initializes a new instance of the class.
Constructor
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
1.0.5000.0
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.Obsolete("The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead.", DiagnosticId="SYSLIB0001", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
[<System.Obsolete("The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead.", DiagnosticId="SYSLIB0001", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>]
Initializes a new instance of the class.
constructor is equivalent to calling the constructor that takes an `allowOptionals` parameter and specifying `false` for that parameter.
If an instance allows optional characters, Unicode code points are encoded with a corresponding optional character instead of a modified base 64 character. The optional characters are exclamation point ("!"), backward slash ("\\"), vertical line ("|"), double quote ("""), number sign ("#"), dollar sign ("$"), percent sign ("%"), ampersand ("&"), asterisk ("*"), semicolon (";"), left angle bracket ("\<"), right angle bracket (">"), left curly bracket ("{"), right curly bracket ("}"), left square bracket ("["), right square bracket ("]"), equal sign ("="), at sign ("@"), circumflex accent ("^"), underscore ("_"), and grave accent ("`").
> [!NOTE]
> does not provide error detection. For security reasons, your applications are recommended to use , , or and enable error detection.
## Examples
The following code example demonstrates how to create a new instance and display the name of the encoding.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/.ctor/ctor.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/.ctor/ctor.vb" id="Snippet1":::
]]>
Constructor
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
1.0.5000.0
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.Obsolete("The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead.", DiagnosticId="SYSLIB0001", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
[<System.Obsolete("The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead.", DiagnosticId="SYSLIB0001", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>]
to specify that optional characters are allowed; otherwise, .
Initializes a new instance of the class. A parameter specifies whether to allow optional characters.
"), left curly bracket ("{"), right curly bracket ("}"), left square bracket ("["), right square bracket ("]"), equal sign ("="), at sign ("@"), circumflex accent ("^"), underscore ("_"), and grave accent ("`").
> [!NOTE]
> does not provide error detection. For security reasons, your applications are recommended to use , , or and enable error detection.
## Examples
The following code example demonstrates how to create a new instance that allows optional characters.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/.ctor/ctor-boolean.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/.ctor/ctor-boolean.vb" id="Snippet1":::
]]>
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.Runtime.InteropServices.ComVisible(false)]
[<System.Runtime.InteropServices.ComVisible(false)>]
System.Boolean
[System.Diagnostics.CodeAnalysis.NotNullWhen(true)]
[<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>]
An object to compare to the current object.
Gets a value indicating whether the specified object is equal to the current object.
if is a object and is equal to the current object; otherwise, .
objects are equal if they both either allow or disallow optional characters, and if their underlying and properties are equal.
]]>
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
Calculates the number of bytes produced by encoding a set of characters.
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.Runtime.InteropServices.ComVisible(false)]
[<System.Runtime.InteropServices.ComVisible(false)>]
[System.Security.SecuritySafeCritical]
[<System.Security.SecuritySafeCritical>]
System.Int32
The object containing the set of characters to encode.
Calculates the number of bytes produced by encoding the characters in the specified object.
The number of bytes produced by encoding the specified characters.
requires to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
## Examples
The following code example demonstrates how to use the method to return the number of bytes required to encode a character array.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetByteCount/getbytecount-char[]-int32-int32.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetByteCount/getbytecount-char[]-int32-int32.vb" id="Snippet1":::
]]>
is ().
The resulting number of bytes is greater than the maximum number that can be returned as an int.
A fallback occurred (for more information, see Character Encoding in .NET).
-and-
is set to .
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.CLSCompliant(false)]
[<System.CLSCompliant(false)>]
[System.Security.SecurityCritical]
[<System.Security.SecurityCritical>]
[System.Runtime.InteropServices.ComVisible(false)]
[<System.Runtime.InteropServices.ComVisible(false)>]
System.Int32
A pointer to the first character to encode.
The number of characters to encode.
Calculates the number of bytes produced by encoding a set of characters starting at the specified character pointer.
The number of bytes produced by encoding the specified characters.
requires to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
]]>
is ( in Visual Basic .NET).
is less than zero.
-or-
The resulting number of bytes is greater than the maximum number that can be returned as an int.
A fallback occurred (for more information, see Character Encoding in .NET)
-and-
is set to .
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
1.0.5000.0
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.Security.SecuritySafeCritical]
[<System.Security.SecuritySafeCritical>]
System.Int32
The character array containing the set of characters to encode.
The index of the first character to encode.
The number of characters to encode.
Calculates the number of bytes produced by encoding a set of characters from the specified character array.
The number of bytes produced by encoding the specified characters.
to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
## Examples
The following code example demonstrates how to use the method to return the number of bytes required to encode an array of Unicode characters.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetByteCount/getbytecount-char[]-int32-int32.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetByteCount/getbytecount-char[]-int32-int32.vb" id="Snippet1":::
]]>
is ().
or is less than zero.
-or-
and do not denote a valid range in .
-or-
The resulting number of bytes is greater than the maximum number that can be returned as an int.
A fallback occurred (for more information, see Character Encoding in .NET)
-and-
is set to .
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
Encodes a set of characters into a sequence of bytes.
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.CLSCompliant(false)]
[<System.CLSCompliant(false)>]
[System.Security.SecurityCritical]
[<System.Security.SecurityCritical>]
[System.Runtime.InteropServices.ComVisible(false)]
[<System.Runtime.InteropServices.ComVisible(false)>]
System.Int32
A pointer to the first character to encode.
The number of characters to encode.
A pointer to the location at which to start writing the resulting sequence of bytes.
The maximum number of bytes to write.
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.
The actual number of bytes written at the location indicated by .
to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
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 should use the or the provided by the method or the method, respectively.
> [!NOTE]
> does not provide error detection. Invalid characters are encoded as a modified base 64 character. For security reasons, your applications are recommended to use , , or and enable error detection.
]]>
is ().
-or-
is ().
or is less than zero.
is less than the resulting number of bytes.
A fallback occurred (see Character Encoding in .NET for fuller explanation).
-and-
is set to .
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
1.0.5000.0
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.Security.SecuritySafeCritical]
[<System.Security.SecuritySafeCritical>]
System.Int32
The character array containing the set of characters to encode.
The index of the first character to encode.
The number of characters to encode.
The byte array to contain the resulting sequence of bytes.
The index at which to start writing the resulting sequence of bytes.
Encodes a set of characters from the specified character array into the specified byte array.
The actual number of bytes written into .
to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
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 should use the or the provided by the method or the method, respectively.
> [!NOTE]
> does not provide error detection. Invalid characters are encoded as a modified base 64 character. For security reasons, your applications are recommended to use , , or and enable error detection.
## Examples
The following code example demonstrates how to use the method to encode a range of characters from a and store the encoded bytes in a range of elements in a byte array.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.vb" id="Snippet1":::
]]>
is ().
-or-
is ().
or or is less than zero.
-or-
and do not denote a valid range in .
-or-
is not a valid index in .
does not have enough capacity from to the end of the array to accommodate the resulting bytes.
A fallback occurred (see Character Encoding in .NET for fuller explanation).
-and-
is set to .
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.Runtime.InteropServices.ComVisible(false)]
[<System.Runtime.InteropServices.ComVisible(false)>]
[System.Security.SecuritySafeCritical]
[<System.Security.SecuritySafeCritical>]
System.Int32
The containing the set of characters to encode.
The index of the first character to encode.
The number of characters to encode.
The byte array to contain the resulting sequence of bytes.
The index at which to start writing the resulting sequence of bytes.
Encodes a set of characters from the specified into the specified byte array.
The actual number of bytes written into .
to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
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 should use the or the provided by the method or the method, respectively.
> [!NOTE]
> does not provide error detection. Invalid characters are encoded as a modified base 64 character. For security reasons, your applications are recommended to use , , or and enable error detection.
## Examples
The following code example demonstrates how to use the method to encode a range of elements from a Unicode character array, and store the encoded bytes in a range of elements in a byte array.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.vb" id="Snippet1":::
]]>
is ().
-or-
is ().
or or is less than zero.
-or-
and do not denote a valid range in .
-or-
is not a valid index in .
does not have enough capacity from to the end of the array to accommodate the resulting bytes.
A fallback occurred (see Character Encoding in .NET for fuller explanation).
-and-
is set to .
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
Calculates the number of characters produced by decoding a sequence of bytes.
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.CLSCompliant(false)]
[<System.CLSCompliant(false)>]
[System.Security.SecurityCritical]
[<System.Security.SecurityCritical>]
[System.Runtime.InteropServices.ComVisible(false)]
[<System.Runtime.InteropServices.ComVisible(false)>]
System.Int32
A pointer to the first byte to decode.
The number of bytes to decode.
Calculates the number of characters produced by decoding a sequence of bytes starting at the specified byte pointer.
The number of characters produced by decoding the specified sequence of bytes.
to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
]]>
is ().
is less than zero.
-or-
The resulting number of characters is greater than the maximum number that can be returned as an int.
A fallback occurred (for more information, see Character Encoding in .NET).
-and-
is set to .
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
1.0.5000.0
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.Security.SecuritySafeCritical]
[<System.Security.SecuritySafeCritical>]
System.Int32
The byte array containing the sequence of bytes to decode.
The index of the first byte to decode.
The number of bytes to decode.
Calculates the number of characters produced by decoding a sequence of bytes from the specified byte array.
The number of characters produced by decoding the specified sequence of bytes.
to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
## Examples
The following code example demonstrates how to use the method to return the number of characters produced by decoding a range of elements in a byte array.
:::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetCharCount/getcharcount-byte[]-int32-int32.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UnicodeEncoding/GetCharCount/getcharcount-byte[]-int32-int32.vb" id="Snippet1":::
]]>
is ().
or is less than zero.
-or-
and do not denote a valid range in .
-or-
The resulting number of characters is greater than the maximum number that can be returned as an int.
A fallback occurred (for more information, see Character Encoding in .NET)
-and-
is set to .
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
Decodes a sequence of bytes into a set of characters.
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.CLSCompliant(false)]
[<System.CLSCompliant(false)>]
[System.Security.SecurityCritical]
[<System.Security.SecurityCritical>]
[System.Runtime.InteropServices.ComVisible(false)]
[<System.Runtime.InteropServices.ComVisible(false)>]
System.Int32
A pointer to the first byte to decode.
The number of bytes to decode.
A pointer to the location at which to start writing the resulting set of characters.
The maximum number of characters to write.
Decodes a sequence of bytes starting at the specified byte pointer into a set of characters that are stored starting at the specified character pointer.
The actual number of characters written at the location indicated by .
to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
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 should use the or the provided by the method or the method, respectively.
> [!NOTE]
> does not provide error detection. When invalid bytes are encountered, generally emits the invalid bytes. If a byte is larger than hexadecimal 0x7F, the byte value is zero-extended into a Unicode character, the result is stored in the `chars` array, and any shift sequence is terminated. For example, if the byte to encode is hexadecimal 0x81, the resulting character is U+0081. For security reasons, your applications are recommended to use , , or and enable error detection.
]]>
is ().
-or-
is ().
or is less than zero.
is less than the resulting number of characters.
A fallback occurred (for more information, see Character Encoding in .NET)
-and-
is set to .
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
1.0.5000.0
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.Security.SecuritySafeCritical]
[<System.Security.SecuritySafeCritical>]
System.Int32
The byte array containing the sequence of bytes to decode.
The index of the first byte to decode.
The number of bytes to decode.
The character array to contain the resulting set of characters.
The index at which to start writing the resulting set of characters.
Decodes a sequence of bytes from the specified byte array into the specified character array.
The actual number of characters written into .
to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
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 should use the or the provided by the method or the method, respectively.
> [!NOTE]
> does not provide error detection. When invalid bytes are encountered, generally emits the invalid bytes. If a byte is larger than hexadecimal 0x7F, the byte value is zero-extended into a Unicode character, the result is stored in the `chars` array, and any shift sequence is terminated. For example, if the byte to encode is hexadecimal 0x81, the resulting character is U+0081. For security reasons, your applications are recommended to use , , or and enable error detection.
## Examples
The following code example demonstrates how to use the method to decode a range of elements in a byte array and store the result in a character array.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.vb" id="Snippet1":::
]]>
is ().
-or-
is ().
or or is less than zero.
-or-
and do not denote a valid range in .
-or-
is not a valid index in .
does not have enough capacity from to the end of the array to accommodate the resulting characters.
A fallback occurred (for more information, see Character Encoding in .NET)
-and-
is set to .
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
1.0.5000.0
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
System.Text.Decoder
Obtains a decoder that converts a UTF-7 encoded sequence of bytes into a sequence of Unicode characters.
A that converts a UTF-7 encoded sequence of bytes into a sequence of Unicode characters.
method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream.
## Examples
The following code example demonstrates how to use the method to obtain a decoder to convert the UTF-7 encoded bytes into a sequence of characters.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetDecoder/getdecoder-.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetDecoder/getdecoder-.vb" id="Snippet1":::
]]>
Understanding Encodings
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
1.0.5000.0
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
System.Text.Encoder
Obtains an encoder that converts a sequence of Unicode characters into a UTF-7 encoded sequence of bytes.
A that converts a sequence of Unicode characters into a UTF-7 encoded sequence of bytes.
method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream.
## Examples
The following code example demonstrates how to use the method to obtain an encoder to convert a sequence of characters into a UTF-7 encoded sequence of bytes.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetEncoder/getencoder-.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetEncoder/getencoder-.vb" id="Snippet1":::
]]>
Understanding Encodings
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.Runtime.InteropServices.ComVisible(false)]
[<System.Runtime.InteropServices.ComVisible(false)>]
System.Int32
Returns the hash code for the current object.
A 32-bit signed integer hash code.
method is not suitable for distinguishing one object from another. If your application needs a unique hash code, it should override the method.
]]>
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
1.0.5000.0
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
System.Int32
The number of characters to encode.
Calculates the maximum number of bytes produced by encoding the specified number of characters.
The maximum number of bytes produced by encoding the specified number of characters.
to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values.
In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . While UTF-7 is very efficient at encoding ASCII data, one byte per character, it is extremely inefficient for other data. As remarked above, deals with a worst case. If the data to be encoded is largely ASCII, and especially if the ASCII characters cluster together, UTF-7 is significantly more efficient than the number returned by this method suggests.
has no relation to . If your application needs a similar function to use with , it should use .
> [!NOTE]
> `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`.
## Examples
The following code example demonstrates how to use the method to return the maximum number of bytes required to encode a specified number of characters.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetMaxByteCount/getmaxbytecount-int32.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetMaxByteCount/getmaxbytecount-int32.vb" id="Snippet1":::
]]>
is less than zero.
-or-
The resulting number of bytes is greater than the maximum number that can be returned as an int.
A fallback occurred (for more information, see Character Encoding in .NET)
-and-
is set to .
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
1.0.5000.0
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
System.Int32
The number of bytes to decode.
Calculates the maximum number of characters produced by decoding the specified number of bytes.
The maximum number of characters produced by decoding the specified number of bytes.
to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.
is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values.
In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or .
has no relation to . If your application needs a similar function to use with , it should use .
> [!NOTE]
> `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`.
## Examples
The following code example demonstrates how to use the method to return the maximum number of characters produced by decoding a specified number of bytes.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetMaxCharCount/getmaxcharcount-int32.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetMaxCharCount/getmaxcharcount-int32.vb" id="Snippet1":::
]]>
is less than zero.
-or-
The resulting number of characters is greater than the maximum number that can be returned as an int.
A fallback occurred (for more information, see Character Encoding in .NET)
-and-
is set to .
Method
System.Text.Encoding.Extensions
4.0.10.0
4.1.0.0
4.1.1.0
4.1.2.0
5.0.0.0
6.0.0.0
7.0.0.0
8.0.0.0
9.0.0.0
10.0.0.0
11.0.0.0
mscorlib
2.0.0.0
2.0.5.0
4.0.0.0
netstandard
2.0.0.0
2.1.0.0
[System.Runtime.InteropServices.ComVisible(false)]
[<System.Runtime.InteropServices.ComVisible(false)>]
[System.Security.SecuritySafeCritical]
[<System.Security.SecuritySafeCritical>]
System.String
The byte array containing the sequence of bytes to decode.
The index of the first byte to decode.
The number of bytes to decode.
Decodes a range of bytes from a byte array into a string.
A containing the results of decoding the specified sequence of bytes.
or the provided by the method or the method, respectively.
> [!NOTE]
> does not provide error detection. When invalid bytes are encountered, generally emits the invalid bytes. If a byte is larger than hexadecimal 0x7F, the byte value is zero-extended into a Unicode character, the result is stored in the `chars` array, and any shift sequence is terminated. For example, if the byte to encode is hexadecimal 0x81, the resulting character is U+0081. For security reasons, your applications are recommended to use , , or and enable error detection.
## Examples
The following code example encodes a string into an array of bytes, and then decodes the bytes back into a string.
:::code language="csharp" source="~/snippets/csharp/System.Text/UTF7Encoding/GetString/getstring.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/System.Text/UTF7Encoding/GetString/getstring.vb" id="Snippet1":::
]]>
is ().
or is less than zero.
-or-
and do not denote a valid range in .
A fallback occurred (for more information, see Character Encoding in .NET).
-and-
is set to .