From f8ffc2dc51b81503e7b2b20731e6b96145fac3e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20S=C3=A1nchez=20L=C3=B3pez?= <1175054+carlossanlop@users.noreply.github.com> Date: Thu, 17 Aug 2023 10:01:49 -0700 Subject: [PATCH 1/5] Port System.Text documentation --- xml/System.Text/ASCIIEncoding.xml | 3732 +++---- xml/System.Text/Ascii.xml | 1787 ++-- xml/System.Text/CompositeFormat.xml | 215 +- xml/System.Text/Encoding.xml | 12082 ++++++++++----------- xml/System.Text/Rune.xml | 5073 ++++----- xml/System.Text/StringBuilder.xml | 14458 +++++++++++++------------- xml/System.Text/UTF8Encoding.xml | 4678 ++++----- 7 files changed, 21036 insertions(+), 20989 deletions(-) diff --git a/xml/System.Text/ASCIIEncoding.xml b/xml/System.Text/ASCIIEncoding.xml index 5db5e39659c..9ff107309d3 100644 --- a/xml/System.Text/ASCIIEncoding.xml +++ b/xml/System.Text/ASCIIEncoding.xml @@ -1,1865 +1,1867 @@ - - - - - - - - - - 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 - - - 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.Serializable] - [<System.Serializable>] - - - [System.Runtime.InteropServices.ComVisible(true)] - [<System.Runtime.InteropServices.ComVisible(true)>] - - - - Represents an ASCII character encoding of Unicode characters. - - corresponds to the Windows code page 20127. Because ASCII is a 7-bit encoding, ASCII characters are limited to the lowest 128 Unicode characters, from U+0000 to U+007F. If you use the default encoder returned by the property or the constructor, characters outside that range are replaced with a question mark (?) before the encoding operation is performed. Because the class supports only a limited character set, the , , and classes are better suited for globalized applications. The following considerations can help you to decide whether to use : - -- Some protocols require ASCII or a subset of ASCII. In these cases ASCII encoding is appropriate. - -- If an 8-bit encoding is expected, then ASCII probably isn't the correct choice. Instead, consider using UTF8 instead of ASCII. For the characters U+0000 through U+007F, the results are identical, but all Unicode characters are representable in UTF-8, which avoids data loss. - -> [!CAUTION] -> does not provide error detection. For security reasons, you should use , , or and enable error detection. - - 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. - - Note that the default constructor by itself might not have the appropriate behavior for your application. You might want to consider setting the or property to or to prevent sequences with the 8th bit set. Custom behavior might also be appropriate for these cases. - - - -## Examples - The following example demonstrates how to encode Unicode characters into ASCII. Notice the loss of data that occurs when your application uses to encode Unicode characters outside of the ASCII range. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding Example/CPP/snippet.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/Overview/snippet.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding Example/VB/snippet.vb" id="Snippet1"::: - - ]]> - - - - Understanding Encodings - - - - - - - - - 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 - - - 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 - - - - Initializes a new instance of the class. - - [!CAUTION] -> The class does not provide error detection. For security reasons, you should use the , , or class and enable error detection. - - If you choose to use ASCII encoding, this constructor may not provide the appropriate fallback behavior for your application. It uses the and classes to replace every character outside the range of U+0000 through U+007F with a question mark (?). Instead, you can call the or method and pass it and objects to use exception fallback. - -> [!NOTE] -> supports only the Unicode character values between U+0000 and U+007F. Therefore, , , and are better suited for globalized applications. - - - -## Examples - The following example demonstrates how to create a new instance and display the name of the encoding. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.ctor Example/CPP/ctor.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/.ctor/ctor.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.ctor Example/VB/ctor.vb" id="Snippet1"::: - - ]]> - - - - - - 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.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Int32 - - - - - - The span that contains the set of characters to encode. - Calculates the number of bytes produced by encoding the specified character span. - The number of bytes produced by encoding the specified character span. - - to store the resulting bytes, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. - - ]]> - - - - - - - - - - - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Int32 - - - - - - The containing the set of characters to encode. - Calculates the number of bytes produced by encoding the characters in the specified . - 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 example demonstrates how to use the method to return the number of bytes required to encode a string using . - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetByteCount2 Example/CPP/getbytecount-string.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetByteCount/getbytecount-string.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetByteCount2 Example/VB/getbytecount-string.vb" id="Snippet1"::: - - ]]> - - - is . - The resulting number of bytes is greater than the maximum number that can be returned as an integer. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - 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 - - - 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. - - 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 . - - is less than zero. - - -or- - - The resulting number of bytes is greater than the maximum number that can be returned as an integer. - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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 example demonstrates how to use the method to return the number of bytes required to encode an array of Unicode characters using . - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetByteCount1 Example/CPP/getbytecount-char[]-int32-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetByteCount/getbytecount-char[]-int32-int32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetByteCount1 Example/VB/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 integer. - 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.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Int32 - - - - - - - The character span to encode. - The span to contain the resulting set of bytes. - Encodes the specified character span into the specified byte span. - The actual number of bytes written into . - - to store the resulting bytes, use . To calculate the maximum size, 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, can 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, use the or the provided by the method or the method, respectively. - - does not provide error detection. Any Unicode character greater than `U+007F` is encoded as the ASCII question mark ("?"). - -> [!CAUTION] -> For security reasons, you should use , , or and enable error detection. - - ]]> - - - - - - - - - - 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 - - - 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, can 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. - - does not provide error detection. Any Unicode character greater than U+007F is translated to an ASCII question mark ("?"). - -> [!CAUTION] -> For security reasons, your application is 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 (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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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, can 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. - - does not provide error detection. Any Unicode character greater than U+007F is encoded as the ASCII question mark ("?"). - -> [!CAUTION] -> For security reasons, your application is recommended to use , , or and enable error detection. - - - -## Examples - The following example demonstrates how to use the method to encode a range of characters from a string and store the encoded characters in a range of elements in a byte array. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetBytes1 Example/CPP/getbytes-string-int32-int32-byte[]-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetBytes/getbytes-string-int32-int32-byte[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetBytes1 Example/VB/getbytes-string-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 (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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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, can 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. - - does not provide error detection. Any Unicode character greater than U+007F is encoded as the ASCII question mark ("?"). - -> [!CAUTION] -> For security reasons, your application is recommended to use , , or and enable error detection. - - - -## Examples - The following 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetBytes2/CPP/getbytes-char[]-int32-int32-byte[]-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetBytes2/VB/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 (for more information, see Character Encoding in .NET) - - -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.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Int32 - - - - - - The span containing the set of bytes to decode. - Calculates the number of characters produced by decoding the specified byte span. - The number of characters produced by decoding the specified byte span. - - to store the resulting characters, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. - - ]]> - - - - - - - - - - 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 - - - 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, 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 . - - is less than zero. - - -or- - - The resulting number of bytes is greater than the maximum number that can be returned as an integer. - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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, 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 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetCharCount Example/CPP/getcharcount-byte[]-int32-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetCharCount/getcharcount-byte[]-int32-int32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetCharCount Example/VB/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 bytes is greater than the maximum number that can be returned as an integer. - 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.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Int32 - - - - - - - The span containing the bytes to decode. - The span to contain the resulting set of characters. - Decodes the specified byte span into the specified character span. - The actual number of characters written into . - - to store the resulting characters, use . To calculate the maximum size, 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, can 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, you should use the or the provided by the method or the method, respectively. - - does not provide error detection. Any byte greater than hexadecimal `0x7F` is decoded as the Unicode question mark ("?"). - -> [!CAUTION] -> For security reasons, you should use , , or and enable error detection. - - ]]> - - - - - - - - - - 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 - - - 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, 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, can 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. - - does not provide error detection. Any byte greater than hexadecimal 0x7F is decoded as the Unicode question mark ("?"). - -> [!CAUTION] -> For security reasons, your application is 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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, 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, can 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. - - does not provide error detection. Any byte greater than hexadecimal 0x7F is decoded as the Unicode question mark ("?"). - -> [!CAUTION] -> For security reasons, your application is recommended to use , , or and enable error detection. - - - -## Examples - The following example demonstrates how to decode a range of elements from a byte array and store the result in a set of elements in a Unicode character array. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetChars Example/CPP/getchars-byte[]-int32-int32-char[]-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetChars Example/VB/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 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Text.Decoder - - - - Obtains a decoder that converts an ASCII encoded sequence of bytes into a sequence of Unicode characters. - A that converts an ASCII 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. - - ]]> - - - - - - - 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 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Text.Encoder - - - - Obtains an encoder that converts a sequence of Unicode characters into an ASCII encoded sequence of bytes. - An that converts a sequence of Unicode characters into an ASCII encoded sequence of bytes. - - method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, an maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. 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. - - ]]> - - - - - - 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 - - - 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. - - method calculates the exact array size required by the method to store the resulting bytes, whereas the method calculates the maximum array size. The method generally allocates less memory, but the method generally executes faster. - - is a worst-case number, including the worst case for the currently selected . If you choose a replacement fallback with a potentially large string, can return large values. - - The method considers potential leftover surrogates from a previous encoding operation. As a result, if the object uses the default replacement fallback, or if a custom replacement fallback has been defined with a single possible fallback character, the method returns `charCount` + 1. If the object uses a replacement fallback with more than one possible fallback character, the method returns *n* * (`charCount` + 1), where *n* is the maximum number of fallback characters. - - 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 example demonstrates how to use the method to calculate the bytes required to encode a specified number of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetMaxByteCount Example/CPP/getmaxbytecount-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetMaxByteCount/getmaxbytecount-int32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetMaxByteCount Example/VB/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 integer. - - - - - - - - - - - - - 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 - - - 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. - - method calculates the exact array size required by the method to store the resulting characters, whereas the method calculates the maximum array size. The method generally allocates less memory, while the method generally executes faster. - - retrieves a worst-case number, including the worst case for the currently selected . If a decoder fallback is present that has a maximum fallback length of *n*, the method returns *n* * `byteCount`. - - 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 example demonstrates how to use the method to calculate the maximum number of characters needed to decode a specified number of bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetMaxCharCount Example/CPP/getmaxcharcount-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetMaxCharCount/getmaxcharcount-int32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetMaxCharCount Example/VB/getmaxcharcount-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 integer. - - - - - - - - - - - - - - Method - - mscorlib - 1.0.5000.0 - - - System.Text.Encoding.Extensions - - - netstandard - - - System.String - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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. - - does not provide error detection. Any byte greater than hexadecimal 0x7F is decoded as the Unicode question mark ("?"). - -> [!CAUTION] -> For security reasons, you should use the , , or classes and enable error detection instead of using the class. - - - -## Examples - The following example demonstrates how to use the method to convert a byte array into a . - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetString1 Example/CPP/getstring-byte[].cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetString/getstring-byte[].cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetString1 Example/VB/getstring-byte[].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 . - - - - - - - - - - - - - - Property - - 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 - - - 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 - - - Gets a value indicating whether the current encoding uses single-byte code points. - This property is always . - - property to determine the size of a byte array for encoding operations and the size of a character array for decoding operations (for example, so that the size of the byte array is * the number of characters to be encoded), you should call the or method for encoding operations and the or method for decoding operations. These methods takes the object's replacement fallback strategy into account when calculating the required array size. - - ]]> - - - - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 8.0.0.0 - - - netstandard - - - System.Boolean - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 8.0.0.0 - - - netstandard - - - System.Boolean - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - + + + + + + + + + + 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 + + + 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.Serializable] + [<System.Serializable>] + + + [System.Runtime.InteropServices.ComVisible(true)] + [<System.Runtime.InteropServices.ComVisible(true)>] + + + + Represents an ASCII character encoding of Unicode characters. + + corresponds to the Windows code page 20127. Because ASCII is a 7-bit encoding, ASCII characters are limited to the lowest 128 Unicode characters, from U+0000 to U+007F. If you use the default encoder returned by the property or the constructor, characters outside that range are replaced with a question mark (?) before the encoding operation is performed. Because the class supports only a limited character set, the , , and classes are better suited for globalized applications. The following considerations can help you to decide whether to use : + +- Some protocols require ASCII or a subset of ASCII. In these cases ASCII encoding is appropriate. + +- If an 8-bit encoding is expected, then ASCII probably isn't the correct choice. Instead, consider using UTF8 instead of ASCII. For the characters U+0000 through U+007F, the results are identical, but all Unicode characters are representable in UTF-8, which avoids data loss. + +> [!CAUTION] +> does not provide error detection. For security reasons, you should use , , or and enable error detection. + + 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. + + Note that the default constructor by itself might not have the appropriate behavior for your application. You might want to consider setting the or property to or to prevent sequences with the 8th bit set. Custom behavior might also be appropriate for these cases. + + + +## Examples + The following example demonstrates how to encode Unicode characters into ASCII. Notice the loss of data that occurs when your application uses to encode Unicode characters outside of the ASCII range. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding Example/CPP/snippet.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/Overview/snippet.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding Example/VB/snippet.vb" id="Snippet1"::: + + ]]> + + + + Understanding Encodings + + + + + + + + + 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 + + + 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 + + + + Initializes a new instance of the class. + + [!CAUTION] +> The class does not provide error detection. For security reasons, you should use the , , or class and enable error detection. + + If you choose to use ASCII encoding, this constructor may not provide the appropriate fallback behavior for your application. It uses the and classes to replace every character outside the range of U+0000 through U+007F with a question mark (?). Instead, you can call the or method and pass it and objects to use exception fallback. + +> [!NOTE] +> supports only the Unicode character values between U+0000 and U+007F. Therefore, , , and are better suited for globalized applications. + + + +## Examples + The following example demonstrates how to create a new instance and display the name of the encoding. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.ctor Example/CPP/ctor.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/.ctor/ctor.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.ctor Example/VB/ctor.vb" id="Snippet1"::: + + ]]> + + + + + + 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.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Int32 + + + + + + The span that contains the set of characters to encode. + Calculates the number of bytes produced by encoding the specified character span. + The number of bytes produced by encoding the specified character span. + + to store the resulting bytes, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. + + ]]> + + + + + + + + + + + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Int32 + + + + + + The containing the set of characters to encode. + Calculates the number of bytes produced by encoding the characters in the specified . + 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 example demonstrates how to use the method to return the number of bytes required to encode a string using . + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetByteCount2 Example/CPP/getbytecount-string.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetByteCount/getbytecount-string.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetByteCount2 Example/VB/getbytecount-string.vb" id="Snippet1"::: + + ]]> + + + is . + The resulting number of bytes is greater than the maximum number that can be returned as an integer. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + 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 + + + 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. + + 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 . + + is less than zero. + + -or- + + The resulting number of bytes is greater than the maximum number that can be returned as an integer. + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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 example demonstrates how to use the method to return the number of bytes required to encode an array of Unicode characters using . + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetByteCount1 Example/CPP/getbytecount-char[]-int32-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetByteCount/getbytecount-char[]-int32-int32.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetByteCount1 Example/VB/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 integer. + 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.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Int32 + + + + + + + The character span to encode. + The span to contain the resulting set of bytes. + Encodes the specified character span into the specified byte span. + The actual number of bytes written into . + + to store the resulting bytes, use . To calculate the maximum size, 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, can 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, use the or the provided by the method or the method, respectively. + + does not provide error detection. Any Unicode character greater than `U+007F` is encoded as the ASCII question mark ("?"). + +> [!CAUTION] +> For security reasons, you should use , , or and enable error detection. + + ]]> + + + + + + + + + + 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 + + + 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, can 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. + + does not provide error detection. Any Unicode character greater than U+007F is translated to an ASCII question mark ("?"). + +> [!CAUTION] +> For security reasons, your application is 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 (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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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, can 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. + + does not provide error detection. Any Unicode character greater than U+007F is encoded as the ASCII question mark ("?"). + +> [!CAUTION] +> For security reasons, your application is recommended to use , , or and enable error detection. + + + +## Examples + The following example demonstrates how to use the method to encode a range of characters from a string and store the encoded characters in a range of elements in a byte array. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetBytes1 Example/CPP/getbytes-string-int32-int32-byte[]-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetBytes/getbytes-string-int32-int32-byte[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetBytes1 Example/VB/getbytes-string-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 (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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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, can 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. + + does not provide error detection. Any Unicode character greater than U+007F is encoded as the ASCII question mark ("?"). + +> [!CAUTION] +> For security reasons, your application is recommended to use , , or and enable error detection. + + + +## Examples + The following 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetBytes2/CPP/getbytes-char[]-int32-int32-byte[]-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetBytes2/VB/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 (for more information, see Character Encoding in .NET) + + -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.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Int32 + + + + + + The span containing the set of bytes to decode. + Calculates the number of characters produced by decoding the specified byte span. + The number of characters produced by decoding the specified byte span. + + to store the resulting characters, use . To calculate the maximum size, use . The method generally allows allocation of less memory, while the method generally executes faster. + + ]]> + + + + + + + + + + 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 + + + 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, 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 . + + is less than zero. + + -or- + + The resulting number of bytes is greater than the maximum number that can be returned as an integer. + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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, 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 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetCharCount Example/CPP/getcharcount-byte[]-int32-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetCharCount/getcharcount-byte[]-int32-int32.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetCharCount Example/VB/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 bytes is greater than the maximum number that can be returned as an integer. + 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.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Int32 + + + + + + + The span containing the bytes to decode. + The span to contain the resulting set of characters. + Decodes the specified byte span into the specified character span. + The actual number of characters written into . + + to store the resulting characters, use . To calculate the maximum size, 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, can 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, you should use the or the provided by the method or the method, respectively. + + does not provide error detection. Any byte greater than hexadecimal `0x7F` is decoded as the Unicode question mark ("?"). + +> [!CAUTION] +> For security reasons, you should use , , or and enable error detection. + + ]]> + + + + + + + + + + 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 + + + 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, 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, can 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. + + does not provide error detection. Any byte greater than hexadecimal 0x7F is decoded as the Unicode question mark ("?"). + +> [!CAUTION] +> For security reasons, your application is 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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, 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, can 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. + + does not provide error detection. Any byte greater than hexadecimal 0x7F is decoded as the Unicode question mark ("?"). + +> [!CAUTION] +> For security reasons, your application is recommended to use , , or and enable error detection. + + + +## Examples + The following example demonstrates how to decode a range of elements from a byte array and store the result in a set of elements in a Unicode character array. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetChars Example/CPP/getchars-byte[]-int32-int32-char[]-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetChars Example/VB/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 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Text.Decoder + + + + Obtains a decoder that converts an ASCII encoded sequence of bytes into a sequence of Unicode characters. + A that converts an ASCII 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. + + ]]> + + + + + + + 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 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Text.Encoder + + + + Obtains an encoder that converts a sequence of Unicode characters into an ASCII encoded sequence of bytes. + An that converts a sequence of Unicode characters into an ASCII encoded sequence of bytes. + + method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, an maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. 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. + + ]]> + + + + + + 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 + + + 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. + + method calculates the exact array size required by the method to store the resulting bytes, whereas the method calculates the maximum array size. The method generally allocates less memory, but the method generally executes faster. + + is a worst-case number, including the worst case for the currently selected . If you choose a replacement fallback with a potentially large string, can return large values. + + The method considers potential leftover surrogates from a previous encoding operation. As a result, if the object uses the default replacement fallback, or if a custom replacement fallback has been defined with a single possible fallback character, the method returns `charCount` + 1. If the object uses a replacement fallback with more than one possible fallback character, the method returns *n* * (`charCount` + 1), where *n* is the maximum number of fallback characters. + + 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 example demonstrates how to use the method to calculate the bytes required to encode a specified number of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetMaxByteCount Example/CPP/getmaxbytecount-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetMaxByteCount/getmaxbytecount-int32.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetMaxByteCount Example/VB/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 integer. + + + + + + + + + + + + + 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 + + + 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. + + method calculates the exact array size required by the method to store the resulting characters, whereas the method calculates the maximum array size. The method generally allocates less memory, while the method generally executes faster. + + retrieves a worst-case number, including the worst case for the currently selected . If a decoder fallback is present that has a maximum fallback length of *n*, the method returns *n* * `byteCount`. + + 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 example demonstrates how to use the method to calculate the maximum number of characters needed to decode a specified number of bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetMaxCharCount Example/CPP/getmaxcharcount-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetMaxCharCount/getmaxcharcount-int32.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetMaxCharCount Example/VB/getmaxcharcount-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 integer. + + + + + + + + + + + + + + Method + + mscorlib + 1.0.5000.0 + + + System.Text.Encoding.Extensions + + + netstandard + + + System.String + + + + + + To be added. + To be added. + To be added. + To be added. + + + + + + + + + + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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. + + does not provide error detection. Any byte greater than hexadecimal 0x7F is decoded as the Unicode question mark ("?"). + +> [!CAUTION] +> For security reasons, you should use the , , or classes and enable error detection instead of using the class. + + + +## Examples + The following example demonstrates how to use the method to convert a byte array into a . + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetString1 Example/CPP/getstring-byte[].cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/ASCIIEncoding/GetString/getstring-byte[].cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.GetString1 Example/VB/getstring-byte[].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 . + + + + + + + + + + + + + + Property + + 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 + + + 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 + + + Gets a value indicating whether the current encoding uses single-byte code points. + This property is always . + + property to determine the size of a byte array for encoding operations and the size of a character array for decoding operations (for example, so that the size of the byte array is * the number of characters to be encoded), you should call the or method for encoding operations and the or method for decoding operations. These methods takes the object's replacement fallback strategy into account when calculating the required array size. + + ]]> + + + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 8.0.0.0 + + + netstandard + + + System.Boolean + + + + + + + + To be added. + To be added. + To be added. + To be added. + To be added. + To be added. + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 8.0.0.0 + + + netstandard + + + System.Boolean + + + + + + + + To be added. + To be added. + To be added. + To be added. + To be added. + To be added. + + + + + diff --git a/xml/System.Text/Ascii.xml b/xml/System.Text/Ascii.xml index 38efced686e..3b3d848d770 100644 --- a/xml/System.Text/Ascii.xml +++ b/xml/System.Text/Ascii.xml @@ -1,886 +1,901 @@ - - - - - - - - - System.Runtime - 8.0.0.0 - - - System.Object - - - - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Range - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Range - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Range - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Range - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Range - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Range - - - - - - To be added. - To be added. - To be added. - To be added. - - - - + + + + + + + + + System.Runtime + 8.0.0.0 + + + System.Object + + + + To be added. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + + The buffer to compare with . + The buffer to compare with . + Determines whether the provided buffers contain equal ASCII characters. + + if the corresponding elements in and were equal and ASCII. otherwise. + If both buffers contain equal, but non-ASCII characters, the method returns . + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + + To be added. + To be added. + To be added. + To be added. + To be added. + + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + + To be added. + To be added. + To be added. + To be added. + To be added. + + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + + To be added. + To be added. + To be added. + To be added. + To be added. + + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + + The buffer to compare with . + The buffer to compare with . + Determines whether the provided buffers contain equal ASCII characters, ignoring case considerations. + + if the corresponding elements in and were equal ignoring case considerations and ASCII. otherwise. + If both buffers contain equal, but non-ASCII characters, the method returns . + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + + To be added. + To be added. + To be added. + To be added. + To be added. + + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + + To be added. + To be added. + To be added. + To be added. + To be added. + + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + + To be added. + To be added. + To be added. + To be added. + To be added. + + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + The source buffer from which UTF-16 text is read. + The destination buffer to which ASCII text is written. + The number of bytes actually written to . It's the same as the number of chars actually read from . + Copies text from a source buffer to a destination buffer, converting from UTF-16 to ASCII during the copy. + An describing the result of the operation. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + The value to inspect. + Determines whether the provided value is ASCII byte. + + if is ASCII, otherwise. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + The value to inspect. + Determines whether the provided value is ASCII char. + + if is ASCII, otherwise. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + The value to inspect. + Determines whether the provided value contains only ASCII bytes. + + if contains only ASCII bytes or is empty; otherwise. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + The value to inspect. + Determines whether the provided value contains only ASCII chars. + + if contains only ASCII chars or is empty; otherwise. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + The source buffer from which ASCII text is read. + The destination buffer to which lowercase text is written. + The number of bytes actually written to . It's the same as the number of bytes actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to lowercase during the copy. + An describing the result of the operation. + In-place conversion is prohibited, please use for that. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + The source buffer from which ASCII text is read. + The destination buffer to which lowercase text is written. + The number of characters actually written to . It's the same as the number of bytes actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to lowercase during the copy. + An describing the result of the operation. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + The source buffer from which ASCII text is read. + The destination buffer to which lowercase text is written. + The number of bytes actually written to . It's the same as the number of characters actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to lowercase during the copy. + An describing the result of the operation. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + The source buffer from which ASCII text is read. + The destination buffer to which lowercase text is written. + The number of characters actually written to . It's the same as the number of characters actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to lowercase during the copy. + An describing the result of the operation. + In-place conversion is prohibited, please use for that. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + The ASCII text buffer. + The number of processed bytes. + Performs in-place uppercase conversion. + An describing the result of the operation. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + The ASCII text buffer. + The number of processed characters. + Performs in-place uppercase conversion. + An describing the result of the operation. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + The source buffer from which ASCII text is read. + The destination buffer to which uppercase text is written. + The number of bytes actually written to . It's the same as the number of bytes actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to uppercase during the copy. + An describing the result of the operation. + In-place conversion is prohibited, please use for that. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + The source buffer from which ASCII text is read. + The destination buffer to which uppercase text is written. + The number of characters actually written to . It's the same as the number of bytes actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to uppercase during the copy. + An describing the result of the operation. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + The source buffer from which ASCII text is read. + The destination buffer to which uppercase text is written. + The number of bytes actually written to . It's the same as the number of characters actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to uppercase during the copy. + An describing the result of the operation. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + The source buffer from which ASCII text is read. + The destination buffer to which uppercase text is written. + The number of characters actually written to . It's the same as the number of characters actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to uppercase during the copy. + An describing the result of the operation. + In-place conversion is prohibited, please use for that. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + The ASCII text buffer. + The number of processed bytes. + Performs in-place lowercase conversion. + An describing the result of the operation. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + The ASCII text buffer. + The number of processed characters. + Performs in-place lowercase conversion. + An describing the result of the operation. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + The source buffer from which ASCII text is read. + The destination buffer to which UTF-16 text is written. + The number of chars actually written to . It's the same as the number of bytes actually read from + Copies text from a source buffer to a destination buffer, converting from ASCII to UTF-16 during the copy. + An describing the result of the operation. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Range + + + + + + The ASCII buffer. + Trims all leading and trailing ASCII whitespaces from the buffer. + The Range of the untrimmed data. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Range + + + + + + To be added. + To be added. + To be added. + To be added. + + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Range + + + + + + The ASCII buffer. + Trims all trailing ASCII whitespaces from the buffer. + The Range of the untrimmed data. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Range + + + + + + To be added. + To be added. + To be added. + To be added. + + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Range + + + + + + The ASCII buffer. + Trims all leading ASCII whitespaces from the buffer. + The Range of the untrimmed data. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Range + + + + + + To be added. + To be added. + To be added. + To be added. + + + + + diff --git a/xml/System.Text/CompositeFormat.xml b/xml/System.Text/CompositeFormat.xml index a79dd66e79c..669fcd6ee9d 100644 --- a/xml/System.Text/CompositeFormat.xml +++ b/xml/System.Text/CompositeFormat.xml @@ -1,106 +1,109 @@ - - - - - - - - - System.Runtime - 8.0.0.0 - - - System.Object - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - To be added. - To be added. - - - - - - - - - - Property - - System.Runtime - 8.0.0.0 - - - System.String - - - To be added. - To be added. - To be added. - - - - - - - - - - Property - - System.Runtime - 8.0.0.0 - - - System.Int32 - - - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Text.CompositeFormat - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - - - - To be added. - To be added. - To be added. - To be added. - - - - + + + + + + + + + System.Runtime + 8.0.0.0 + + + System.Object + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + Represents a parsed composite format string. + To be added. + + + + + + + + + + Property + + System.Runtime + 8.0.0.0 + + + System.String + + + Gets the original composite format string used to create this instance. + To be added. + To be added. + + + + + + + + + + Property + + System.Runtime + 8.0.0.0 + + + System.Int32 + + + Gets the minimum number of arguments that must be passed to a formatting operation using this . + To be added. + It's permissible to supply more arguments than this value, but it's an error to pass fewer. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Text.CompositeFormat + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + + + + The string to parse. + Parse the composite format string . + The parsed . + To be added. + + is . + A format item in is invalid. + + + + diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index 4a9f7f4e673..94ea19af445 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -1,6040 +1,6042 @@ - - - - - - - - - - - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - - - - - - - - - - - - System.Object - - - - System.ICloneable - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Serializable] - [<System.Serializable>] - - - [System.Runtime.InteropServices.ComVisible(true)] - [<System.Runtime.InteropServices.ComVisible(true)>] - - - - Represents a character encoding. - - , see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - -Note that is intended to operate on Unicode characters instead of arbitrary binary data, such as byte arrays. If you must encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - -.NET provides the following implementations of the class to support current Unicode encodings and other encodings: - -- encodes Unicode characters as single 7-bit ASCII characters. This encoding only supports character values between U+0000 and U+007F. Code page 20127. Also available through the property. - -- encodes Unicode characters using the UTF-7 encoding. This encoding supports all Unicode character values. Code page 65000. Also available through the property. - -- encodes Unicode characters using the UTF-8 encoding. This encoding supports all Unicode character values. Code page 65001. Also available through the property. - -- encodes Unicode characters using the UTF-16 encoding. Both little endian and big endian byte orders are supported. Also available through the property and the property. - -- encodes Unicode characters using the UTF-32 encoding. Both little endian (code page 12000) and big endian (code page 12001) byte orders are supported. Also available through the property. - -The class is primarily intended to convert between different encodings and Unicode. Often one of the derived Unicode classes is the correct choice for your app. - -Use the method to obtain other encodings, and call the method to get a list of all encodings. - -### List of encodings - -The following table lists the encodings supported by .NET. It lists each encoding's code page number and the values of the encoding's and properties. A check mark in the **.NET Framework support**, **.NET Core support**, or **.NET 5 and later support** column indicates that the code page is natively supported by that .NET implementation, regardless of the underlying platform. For .NET Framework, the availability of other encodings listed in the table depends on the operating system. For .NET Core and .NET 5 and later versions, other encodings are available by using the class or by deriving from the class. - -> [!NOTE] -> Code pages whose property corresponds to an international standard do not necessarily comply in full with that standard. - -|Code page|Name|Display name|.NET Framework support| .NET Core support | .NET 5 and later support | -|---------|----|------------|----------------------|-------------------|----------------------------| -|37|IBM037|IBM EBCDIC (US-Canada)|||| -|437|IBM437|OEM United States|||| -|500|IBM500|IBM EBCDIC (International)|||| -|708|ASMO-708|Arabic (ASMO 708)|||| -|720|DOS-720|Arabic (DOS)|||| -|737|ibm737|Greek (DOS)|||| -|775|ibm775|Baltic (DOS)|||| -|850|ibm850|Western European (DOS)|||| -|852|ibm852|Central European (DOS)|||| -|855|IBM855|OEM Cyrillic|||| -|857|ibm857|Turkish (DOS)|||| -|858|IBM00858|OEM Multilingual Latin I|||| -|860|IBM860|Portuguese (DOS)|||| -|861|ibm861|Icelandic (DOS)|||| -|862|DOS-862|Hebrew (DOS)|||| -|863|IBM863|French Canadian (DOS)|||| -|864|IBM864|Arabic (864)|||| -|865|IBM865|Nordic (DOS)|||| -|866|cp866|Cyrillic (DOS)|||| -|869|ibm869|Greek, Modern (DOS)|||| -|870|IBM870|IBM EBCDIC (Multilingual Latin-2)|||| -|874|windows-874|Thai (Windows)|||| -|875|cp875|IBM EBCDIC (Greek Modern)|||| -|932|shift_jis|Japanese (Shift-JIS)|||| -|936|gb2312|Chinese Simplified (GB2312)|✓||| -|949|ks_c_5601-1987|Korean|||| -|950|big5|Chinese Traditional (Big5)|||| -|1026|IBM1026|IBM EBCDIC (Turkish Latin-5)|||| -|1047|IBM01047|IBM Latin-1|||| -|1140|IBM01140|IBM EBCDIC (US-Canada-Euro)|||| -|1141|IBM01141|IBM EBCDIC (Germany-Euro)|||| -|1142|IBM01142|IBM EBCDIC (Denmark-Norway-Euro)|||| -|1143|IBM01143|IBM EBCDIC (Finland-Sweden-Euro)|||| -|1144|IBM01144|IBM EBCDIC (Italy-Euro)|||| -|1145|IBM01145|IBM EBCDIC (Spain-Euro)|||| -|1146|IBM01146|IBM EBCDIC (UK-Euro)|||| -|1147|IBM01147|IBM EBCDIC (France-Euro)|||| -|1148|IBM01148|IBM EBCDIC (International-Euro)|||| -|1149|IBM01149|IBM EBCDIC (Icelandic-Euro)|||| -|1200|utf-16|Unicode|✓|✓|✓| -|1201|unicodeFFFE|Unicode (Big endian)|✓|✓|✓| -|1250|windows-1250|Central European (Windows)|||| -|1251|windows-1251|Cyrillic (Windows)|||| -|1252|Windows-1252|Western European (Windows)|✓|||| -|1253|windows-1253|Greek (Windows)|||| -|1254|windows-1254|Turkish (Windows)|||| -|1255|windows-1255|Hebrew (Windows)|||| -|1256|windows-1256|Arabic (Windows)|||| -|1257|windows-1257|Baltic (Windows)|||| -|1258|windows-1258|Vietnamese (Windows)|||| -|1361|Johab|Korean (Johab)|||| -|10000|macintosh|Western European (Mac)|||| -|10001|x-mac-japanese|Japanese (Mac)|||| -|10002|x-mac-chinesetrad|Chinese Traditional (Mac)|||| -|10003|x-mac-korean|Korean (Mac)|✓||| -|10004|x-mac-arabic|Arabic (Mac)|||| -|10005|x-mac-hebrew|Hebrew (Mac)|||| -|10006|x-mac-greek|Greek (Mac)|||| -|10007|x-mac-cyrillic|Cyrillic (Mac)|||| -|10008|x-mac-chinesesimp|Chinese Simplified (Mac)|✓||| -|10010|x-mac-romanian|Romanian (Mac)|||| -|10017|x-mac-ukrainian|Ukrainian (Mac)|||| -|10021|x-mac-thai|Thai (Mac)|||| -|10029|x-mac-ce|Central European (Mac)|||| -|10079|x-mac-icelandic|Icelandic (Mac)|||| -|10081|x-mac-turkish|Turkish (Mac)|||| -|10082|x-mac-croatian|Croatian (Mac)|||| -|12000|utf-32|Unicode (UTF-32)|✓|✓|✓| -|12001|utf-32BE|Unicode (UTF-32 Big endian)|✓|✓|✓| -|20000|x-Chinese-CNS|Chinese Traditional (CNS)|||| -|20001|x-cp20001|TCA Taiwan|||| -|20002|x-Chinese-Eten|Chinese Traditional (Eten)|||| -|20003|x-cp20003|IBM5550 Taiwan|||| -|20004|x-cp20004|TeleText Taiwan|||| -|20005|x-cp20005|Wang Taiwan|||| -|20105|x-IA5|Western European (IA5)|||| -|20106|x-IA5-German|German (IA5)|||| -|20107|x-IA5-Swedish|Swedish (IA5)|||| -|20108|x-IA5-Norwegian|Norwegian (IA5)|||| -|20127|us-ascii|US-ASCII|✓|✓|✓| -|20261|x-cp20261|T.61|||| -|20269|x-cp20269|ISO-6937|||| -|20273|IBM273|IBM EBCDIC (Germany)|||| -|20277|IBM277|IBM EBCDIC (Denmark-Norway)|||| -|20278|IBM278|IBM EBCDIC (Finland-Sweden)|||| -|20280|IBM280|IBM EBCDIC (Italy)|||| -|20284|IBM284|IBM EBCDIC (Spain)|||| -|20285|IBM285|IBM EBCDIC (UK)|||| -|20290|IBM290|IBM EBCDIC (Japanese katakana)|||| -|20297|IBM297|IBM EBCDIC (France)|||| -|20420|IBM420|IBM EBCDIC (Arabic)|||| -|20423|IBM423|IBM EBCDIC (Greek)|||| -|20424|IBM424|IBM EBCDIC (Hebrew)|||| -|20833|x-EBCDIC-KoreanExtended|IBM EBCDIC (Korean Extended)|||| -|20838|IBM-Thai|IBM EBCDIC (Thai)|||| -|20866|koi8-r|Cyrillic (KOI8-R)|||| -|20871|IBM871|IBM EBCDIC (Icelandic)|||| -|20880|IBM880|IBM EBCDIC (Cyrillic Russian)|||| -|20905|IBM905|IBM EBCDIC (Turkish)|||| -|20924|IBM00924|IBM Latin-1|||| -|20932|EUC-JP|Japanese (JIS 0208-1990 and 0212-1990)|||| -|20936|x-cp20936|Chinese Simplified (GB2312-80)|✓||| -|20949|x-cp20949|Korean Wansung|✓||| -|21025|cp1025|IBM EBCDIC (Cyrillic Serbian-Bulgarian)|||| -|21866|koi8-u|Cyrillic (KOI8-U)|||| -|28591|iso-8859-1|Western European (ISO)|✓|✓|✓| -|28592|iso-8859-2|Central European (ISO)|||| -|28593|iso-8859-3|Latin 3 (ISO)|||| -|28594|iso-8859-4|Baltic (ISO)|||| -|28595|iso-8859-5|Cyrillic (ISO)|||| -|28596|iso-8859-6|Arabic (ISO)|||| -|28597|iso-8859-7|Greek (ISO)|||| -|28598|iso-8859-8|Hebrew (ISO-Visual)|✓||| -|28599|iso-8859-9|Turkish (ISO)|||| -|28603|iso-8859-13|Estonian (ISO)|||| -|28605|iso-8859-15|Latin 9 (ISO)|||| -|29001|x-Europa|Europa|||| -|38598|iso-8859-8-i|Hebrew (ISO-Logical)|✓||| -|50220|iso-2022-jp|Japanese (JIS)|✓||| -|50221|csISO2022JP|Japanese (JIS-Allow 1 byte Kana)|✓||| -|50222|iso-2022-jp|Japanese (JIS-Allow 1 byte Kana - SO/SI)|✓||| -|50225|iso-2022-kr|Korean (ISO)|✓||| -|50227|x-cp50227|Chinese Simplified (ISO-2022)|✓||| -|51932|euc-jp|Japanese (EUC)|✓||| -|51936|EUC-CN|Chinese Simplified (EUC)|✓||| -|51949|euc-kr|Korean (EUC)|✓||| -|52936|hz-gb-2312|Chinese Simplified (HZ)|✓||| -|54936|GB18030|Chinese Simplified (GB18030)|✓||| -|57002|x-iscii-de|ISCII Devanagari|✓||| -|57003|x-iscii-be|ISCII Bengali|✓||| -|57004|x-iscii-ta|ISCII Tamil|✓||| -|57005|x-iscii-te|ISCII Telugu|✓||| -|57006|x-iscii-as|ISCII Assamese|✓||| -|57007|x-iscii-or|ISCII Oriya|✓||| -|57008|x-iscii-ka|ISCII Kannada|✓||| -|57009|x-iscii-ma|ISCII Malayalam|✓||| -|57010|x-iscii-gu|ISCII Gujarati|✓||| -|57011|x-iscii-pa|ISCII Punjabi|✓||| -|65000|utf-7|Unicode (UTF-7)|✓|✓|| -|65001|utf-8|Unicode (UTF-8)|✓|✓|✓| - - The following example calls the and methods to get the Greek (Windows) code page encoding. It compares the objects returned by the method calls to show that they are equal, and then maps displays the Unicode code point and the corresponding code page value for each character in the Greek alphabet. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/getencoding1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding/vb/getencoding1.vb" id="Snippet1"::: - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - The UTF-16 and the UTF-32 encoders can use the big endian byte order (most significant byte first) or the little endian byte order (least significant byte first). For example, the Latin Capital Letter A (U+0041) is serialized as follows (in hexadecimal): - -- UTF-16 big endian byte order: 00 41 - -- UTF-16 little endian byte order: 41 00 - -- UTF-32 big endian byte order: 00 00 00 41 - -- UTF-32 little endian byte order: 41 00 00 00 - - It is generally more efficient to store Unicode characters using the native byte order. For example, it is better to use the little endian byte order on little endian platforms, such as Intel computers. - - The method retrieves an array of bytes that includes the byte order mark (BOM). If this byte array is prefixed to an encoded stream, it helps the decoder to identify the encoding format used. - - For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://home.unicode.org/). - - Note that the encoding classes allow errors to: - -- Silently change to a "?" character. - -- Use a "best fit" character. - -- Change to an application-specific behavior through use of the and classes with the U+FFFD Unicode replacement character. - - You should throw an exception on any data stream error. An app either uses a "throwonerror" flag when applicable or uses the and classes. Best fit fallback is often not recommended because it can cause data loss or confusion and is slower than simple character replacements. For ANSI encodings, the best fit behavior is the default. - -## Examples - The following example converts a string from one encoding to another. - -> [!NOTE] -> The `byte[]` array is the only type in this example that contains the encoded data. The .NET `Char` and `String` types are themselves Unicode, so the call decodes the data back to Unicode. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: - - ]]> - - How to use character encoding classes in .NET - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - Initializes a new instance of the class. - - - - - - - - - Constructor - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - Initializes a new instance of the class. - - - - - - - - - - - - - - - Constructor - - System.Text.Encoding - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - - - - The code page identifier of the preferred encoding. - - -or- - - 0, to use the default encoding. - Initializes a new instance of the class that corresponds to the specified code page. - - object that uses best-fit fallback for both encoding and decoding operations. Both the and properties are read-only and cannot be modified. To control the fallback strategy for a class derived from , call the constructor. - - ]]> - - - is less than zero. - - - - - - - - - - - - - Constructor - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - - - - - - The encoding code page identifier. - An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. - An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. - Initializes a new instance of the class that corresponds to the specified code page with the specified encoder and decoder fallback strategies. - - class constructors create read-only encoding objects that don't allow encoder or decoder fallback to be set after the object is created. - - If either `encoderFallback` or `decoderFallback` is null, best-fit fallback is used as the corresponding fallback strategy. - - ]]> - - - is less than zero. - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.Encoding - - - Gets an encoding for the ASCII (7-bit) character set. - An encoding for the ASCII (7-bit) character set. - - object that is returned by this property might not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the method to instantiate an object whose fallback is either an or a , as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/ASCII/encoding.ascii2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.ascii/vb/encoding.ascii2.vb" id="Snippet1"::: - -## Examples - -The following example demonstrates the effect of the ASCII encoding on characters that are outside the ASCII range. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.ASCII Example/CPP/ascii.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/ASCII/ascii.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.ASCII Example/VB/ascii.vb" id="Snippet1"::: - - ]]> - - - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - Gets an encoding for the UTF-16 format that uses the big endian byte order. - An encoding object for the UTF-16 format that uses the big endian byte order. - - object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a big endian object whose fallback is either an or a , as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/bigendianunicode1.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/VB/bigendianunicode1.vb" id="Snippet2"::: - - The returned object has , , and properties, which yield the name "unicodeFFFE". Although the UTF-16 big endian byte order mark is hexadecimal FEFF, the name "unicodeFFFE" was chosen because the byte order mark appears as hexadecimal FFFE on little endian Windows computers. - -## Examples - The following example reads a text file with a UTF-16 encoding using the big endian byte order. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/CPP/bigendianunicode.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/bigendianunicode.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/VB/bigendianunicode.vb" id="Snippet1"::: - - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - - ]]> - - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - 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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.String - - - When overridden in a derived class, gets a name for the current encoding that can be used with mail agent body tags. - A name for the current that can be used with mail agent body tags. - - -or- - - An empty string (""), if the current cannot be used. - - with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding; most other applications that need to describe an encoding should use its . - - In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. - -## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - - - - - Method - - M:System.ICloneable.Clone - - - System.Text.Encoding - 4.0.10.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 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Object - - - - When overridden in a derived class, creates a shallow copy of the current object. - A copy of the current object. - - object is read-only. Therefore, the properties of the clone can be modified. - - A shallow copy of an object is a copy of the object only. If the object contains references to other objects, the shallow copy does not create copies of the referred objects. It refers to the original objects instead. In contrast, a deep copy of an object creates a copy of the object and a copy of everything directly or indirectly referenced by that object. - - ]]> - - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - When overridden in a derived class, gets the code page identifier of the current . - The code page identifier of the current . - - . It displays but does not compare against it. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: - - ]]> - - - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - Converts a byte array from one encoding to another. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Byte[] - - - - - - - - The encoding format of . - The target encoding format. - The bytes to convert. - Converts an entire byte array from one encoding to another. - An array of type containing the results of converting from to . - - property uses replacement fallback and the Pi character is not part of the ASCII character set, the Pi character is replaced with a question mark, as the output from the example shows. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: - - ]]> - - - is . - - -or- - - is . - - -or- - - is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - **srcEncoding.** is set to . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - **dstEncoding.** is set to . - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Byte[] - - - - - - - - - - The encoding of the source array, . - The encoding of the output array. - The array of bytes to convert. - The index of the first element of to convert. - The number of bytes to convert. - Converts a range of bytes in a byte array from one encoding to another. - An array of type containing the result of converting a range of bytes in from to . - To be added. - - is . - - -or- - - is . - - -or- - - is . - - and do not specify a valid range in the byte array. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - **srcEncoding.** is set to . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - **dstEncoding.** is set to . - - - - - - - - - Method - - System.Runtime - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - mscorlib - - - netstandard - - - System.IO.Stream - - - - - - - - - The stream to wrap. - The encoding associated with . - The encoding associated with the that's returned by this method. - - if disposing the returned by this method should not dispose . - Creates a that serves to transcode data between an inner and an outer , similar to . - A stream that transcodes the contents of as . - - 's and properties will reflect whether `innerStream` is readable or writable. If `innerStream` is full-duplex, the returned will be as well. However, the returned is not seekable, even if `innerStream`'s property returns `true`. - - ]]> - - - - - - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.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 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Text.DecoderFallback - - - Gets or sets the object for the current object. - The decoder fallback object for the current object. - - object represents an error handler that is invoked when an encoded byte sequence cannot be decoded into a character. Any one of the following handler types is supported: - -- A best-fit fallback handler, which replaces bytes that cannot be decoded with some suitable replacement character. - -- A replacement fallback handler, which replaces bytes that cannot be decoded with some arbitrary replacement character. .NET includes one replacement fallback handler, , which by default replaces bytes that cannot be decoded with a question mark ("?") character. - -- An exception fallback handler, which throws an exception when bytes cannot be decoded. .NET includes one exception fallback handler, , which throws a when bytes cannot be decoded. - - ]]> - - The value in a set operation is . - A value cannot be assigned in a set operation because the current object is read-only. - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - 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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - [get: System.Security.SecuritySafeCritical] - [<get: System.Security.SecuritySafeCritical>] - - - - System.Text.Encoding - - - Gets the default encoding for this .NET implementation. - The default encoding for this .NET implementation. - - [!WARNING] -> Different computers can use different encodings as the default, and the default encoding can change on a single computer. If you use the encoding to encode and decode data streamed between computers or retrieved at different times on the same computer, it may translate that data incorrectly. In addition, the encoding returned by the property uses best-fit fallback to map unsupported characters to characters supported by the code page. For these reasons, using the default encoding is not recommended. To ensure that encoded bytes are decoded properly, you should use a Unicode encoding, such as or . You could also use a higher-level protocol to ensure that the same format is used for encoding and decoding. - -### The Default property in .NET Framework - -In .NET Framework on the Windows desktop, the property always gets the system's active code page and creates a object that corresponds to it. The active code page may be an ANSI code page, which includes the ASCII character set along with additional characters that vary by code page. Because all encodings based on ANSI code pages lose data, consider using the encoding instead. UTF-8 is often identical in the U+00 to U+7F range, but can encode characters outside the ASCII range without loss. - -## The Default property on .NET Core - -On .NET Core, the property always returns the . UTF-8 is supported on all the operating systems (Windows, Linux, and macOS) on which .NET Core applications run. - - ]]> - - - - - - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.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 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Text.EncoderFallback - - - Gets or sets the object for the current object. - The encoder fallback object for the current object. - - object represents an error handler that is invoked when a character cannot be converted into an encoded byte sequence. Any one of the following handler types is supported: - -- A best-fit fallback handler, which replaces characters that cannot be encoded with some suitable replacement character. - -- A replacement fallback handler, which replaces characters that cannot be encoded with some arbitrary replacement character. .NET includes one replacement fallback handler, , which by default replaces characters that cannot be encoded with a question mark ("?") character. - -- An exception fallback handler, which throws an exception when characters cannot be encoded. .NET includes one exception fallback handler, , which throws an when characters cannot be decoded. - - ]]> - - The value in a set operation is . - A value cannot be assigned in a set operation because the current object is read-only. - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.String - - - When overridden in a derived class, gets the human-readable description of the current encoding. - The human-readable description of the current . - - property is intended for display. To find a name that can be passed to the method, use the property. - -## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Boolean - - - - - - [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] - [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] - - - - - - The to compare with the current instance. - Determines whether the specified is equal to the current instance. - - if is an instance of and is equal to the current instance; otherwise, . - - are considered equal if they correspond to the same code page and their `EncoderFallback` and `DecoderFallback` objects are equal. In particular, derived code pages all have a code page of 0 and their fallbacks are normally `null` (`Nothing` in Visual Basic .NET). Thus they are all considered equal to one another. One consequence is that when is used to populate a hash table, all derived encodings compare equal and fall into the same hash table slot. - -## Examples - The following example gets two instances of the same encoding (one by codepage and another by name), and checks their equality. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: - - ]]> - - - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The character array containing the characters to encode. - When overridden in a derived class, calculates the number of bytes produced by encoding all the characters in the specified character array. - The number of bytes produced by encoding all the characters in the specified character array. - - to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles string inputs, you should use the string versions of the method. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, you should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - - ]]> - - - is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Int32 - - - - - - The span of characters to encode. - When overridden in a derived class, calculates the number of bytes produced by encoding the characters in the specified character span. - The number of bytes produced by encoding the specified character span. - - to store the resulting bytes, call the method. To calculate the maximum span size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles span of characters inputs, the span version of is recommended. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output span buffer is too small. For continuous encoding of a stream, this method is often the best choice. - - ]]> - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The string containing the set of characters to encode. - When overridden in a derived class, calculates the number of bytes produced by encoding the characters in the specified string. - The number of bytes produced by encoding the specified characters. - - to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles string inputs, the string version of is recommended. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: - - ]]> - - - is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.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 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - [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. - When overridden in a derived class, 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, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some considerations for using these methods: - -- Your app may need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles string inputs, you should use the string version of the method. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - - ]]> - - - is . - - is less than zero. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - 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. - When overridden in a derived class, 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, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles string inputs, the string version of is recommended. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.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 . - - - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - System.Int32 - - - - - - - - The string containing the set of characters to encode. - The index of the first character to encode. - The number of characters to encode. - When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified string. - The number of bytes produced by encoding the string. - - to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles string inputs, the string version of is recommended. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: - - ]]> - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - When overridden in a derived class, encodes a set of characters into a sequence of bytes. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Byte[] - - - - - - The character array containing the characters to encode. - When overridden in a derived class, encodes all the characters in the specified character array into a sequence of bytes. - A byte array containing the results of encoding the specified set of characters. - - or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should call the string version of the method. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - - ]]> - - - is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Byte[] - - - - - - The string containing the characters to encode. - When overridden in a derived class, encodes all the characters in the specified string into a sequence of bytes. - A byte array containing the results of encoding the specified set of characters. - - or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: - - ]]> - - - is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Int32 - - - - - - - The span containing the set of characters to encode. - The byte span to hold the encoded bytes. - When overridden in a derived class, encodes into a span of bytes a set of characters from the specified read-only span. - The number of encoded bytes. - - or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - - ]]> - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Byte[] - - - - - - - - The character array containing the set of characters to encode. - The index of the first character to encode. - The number of characters to encode. - When overridden in a derived class, encodes a set of characters from the specified character array into a sequence of bytes. - A byte array containing the results of encoding the specified set of characters. - - or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.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 . - - - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - System.Byte[] - - - - - - - - The string containing the characters to encode. - The index inside the string to start the encoding from. - The number of characters to encode. - When overridden in a derived class, encodes into an array of bytes the number of characters specified by in the specified string, starting from the specified . - A byte array containing the results of encoding the specified set of characters. - - or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.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 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - [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. - When overridden in a derived class, 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 the parameter. - - requires to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - - ]]> - - - is . - - -or- - - is . - - or is less than zero. - - is less than the resulting number of bytes. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - 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. - When overridden in a derived class, 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, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.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 (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - - - - - The string 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. - When overridden in a derived class, encodes a set of characters from the specified string into the specified byte array. - The actual number of bytes written into . - - to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.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 (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The byte array containing the sequence of bytes to decode. - When overridden in a derived class, calculates the number of characters produced by decoding all the bytes in the specified byte array. - The number of characters produced by decoding the specified sequence of bytes. - - to store the resulting characters, you should use the method. To calculate the maximum array size, you should use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. - -- If your app handles string outputs, you should use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - -## Examples - The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: - - ]]> - - - is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Int32 - - - - - - A read-only byte span to decode. - When overridden in a derived class, calculates the number of characters produced by decoding the provided read-only byte span. - The number of characters produced by decoding the byte span. - - requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - - ]]> - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.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 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - [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. - When overridden in a derived class, 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. - - requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - - ]]> - - - is . - - is less than zero. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - 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. - When overridden in a derived class, 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, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - -## Examples - The following example converts a string from one encoding to another. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: - - The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.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 . - - - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - When overridden in a derived class, decodes a sequence of bytes into a set of characters. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Char[] - - - - - - The byte array containing the sequence of bytes to decode. - When overridden in a derived class, decodes all the bytes in the specified byte array into a set of characters. - A character array containing the results of decoding the specified sequence of bytes. - - gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - -## Examples - The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: - - ]]> - - - is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Int32 - - - - - - - A read-only span containing the sequence of bytes to decode. - The character span receiving the decoded bytes. - When overridden in a derived class, decodes all the bytes in the specified read-only byte span into a character span. - The actual number of characters written at the span indicated by the parameter. - - gets characters from an input byte span. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - - ]]> - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Char[] - - - - - - - - The byte array containing the sequence of bytes to decode. - The index of the first byte to decode. - The number of bytes to decode. - When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a set of characters. - A character array containing the results of decoding the specified sequence of bytes. - - gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - -## Examples - The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.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 . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.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 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - [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. - When overridden in a derived class, 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 the parameter. - - requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. - - > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - -- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - - ]]> - - - 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 - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - 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. - When overridden in a derived class, 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, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - -- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - -## Examples - The following example converts a string from one encoding to another. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: - - The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.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 - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Decoder - - - - When overridden in a derived class, obtains a decoder that converts an encoded sequence of bytes into a sequence of characters. - A that converts an encoded sequence of bytes into a sequence of 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 correctly decodes 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. - - ]]> - - - The default implementation returns a that calls the and methods of the current . You must override this method to return a that maintains its state between calls. - - - - - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoder - - - - When overridden in a derived class, obtains an encoder that converts a sequence of Unicode characters into an encoded sequence of bytes. - A that converts a sequence of Unicode characters into an encoded sequence of bytes. - - method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly encodes character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. 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. - - ]]> - - - The default implementation returns a that calls the and methods of the current . You must override this method to return a that maintains its state between calls. - - - - - - How to use character encoding classes in .NET - - - - - System.Text.Encoding - 4.0.10.0 - - - Returns an encoding for the specified code page. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.Encoding - - - - - - The code page identifier of the preferred encoding. For a list of possible values, see . - - -or- - - 0 (zero), to use the default encoding. - Returns the encoding associated with the specified code page identifier. - The encoding that is associated with the specified code page. - - overload. - - In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. - -You can also supply a value of 0 for the `codepage` argument. Its precise behavior depends on whether any encodings have been made available by registering an object: - -- If one or more encoding providers have been registered, it returns the encoding of the last registered provider that has chosen to return a encoding when the method is passed a `codepage` argument of 0. - -- On .NET Framework, if no encoding provider has been registered, if the is the registered encoding provider, or if no registered encoding provider handles a `codepage` value of 0, it returns the operating system's active code page. To determine the active code page on Windows systems, call the Windows [GetACP](/windows/win32/api/winnls/nf-winnls-getacp) function from .NET Framework on the Windows desktop. - -- On .NET Core, if no encoding provider has been registered or if no registered encoding provider handles a `codepage` value of 0, it returns the . - -> [!NOTE] -> - Some unsupported code pages cause an to be thrown, whereas others cause a . Therefore, your code must catch all exceptions indicated in the Exceptions section. -> - In .NET 5 and later versions, the code page identifier `65000`, which represents UTF-7, is not supported. - -> [!NOTE] -> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For this reason, if the active code page is an ANSI code page, encoding and decoding data using the default code page returned by `Encoding.GetEncoding(0)` is not recommended. For the most consistent results, you should use a Unicode encoding, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. - -## Examples - The following example gets two instances of the same encoding (one by code page and another by name), and checks their equality. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: - - ]]> - - - is less than zero or greater than 65535. - - is not supported by the underlying platform. - - is not supported by the underlying platform. - - - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.Encoding - - - - - - The code page name of the preferred encoding. Any value returned by the property is valid. For a list of possible values, see . - Returns the encoding associated with the specified code page name. - The encoding associated with the specified code page. - - overload. - -In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. - -In .NET 5 and later versions, the code page name `utf-7` is not supported. - -> [!NOTE] -> The ANSI code pages can be different on different computers, or they can be changed for a single computer, leading to data corruption. For the most consistent results, use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. - -## Examples - The following example gets two instances of the same encoding (one by code page and another by name), and checks their equality. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: - - ]]> - - - is not a valid code page name. - - -or- - - The code page indicated by is not supported by the underlying platform. - - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.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 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.Encoding - - - - - - - - The code page identifier of the preferred encoding. For a list of possible values, see . - - -or- - - 0 (zero), to use the default encoding. - An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. - An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. - Returns the encoding associated with the specified code page identifier. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. - The encoding that is associated with the specified code page. - - [!NOTE] -> - Some unsupported code pages cause the exception to be thrown, whereas others cause . Therefore, your code must catch all exceptions indicated in the Exceptions section. -> - In .NET 5 and later versions, the code page identifier `65000`, which represents UTF-7, is not supported. - -In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. - -You can also supply a value of 0 for the `codepage` argument. Its precise behavior depends on whether any encodings have been made available by registering an object: - -- If one or more encoding providers have been registered, it returns the encoding of the last registered provider that has chosen to return a encoding when the method is passed a `codepage` argument of 0. - -- On .NET Framework, if no encoding provider has been registered, if the is the registered encoding provider, or if no registered encoding provider handles a `codepage` value of 0, it returns the active code page. - -- On .NET Core, if no encoding provider has been registered or if no registered encoding provider handles a `codepage` value of 0, it returns the encoding. - -> [!NOTE] -> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For this reason, if the active code page is an ANSI code page, encoding and decoding data using the default code page returned by `Encoding.GetEncoding(0)` is not recommended. For the most consistent results, you should use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - - To get the encoding associated with the active code page, you can either supply a value of 0 for the `codepage` argument or, if your code is running on .NET Framework on the Windows desktop, retrieve the value of the property. To determine the current active code page, call the Windows [GetACP](/windows/win32/api/winnls/nf-winnls-getacp) function from .NET Framework on the Windows desktop. - - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cpp/fallEncRpl.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/sys.txt.fallbackEncRpl/vb/fallEncRpl.vb" id="Snippet1"::: - - ]]> - - - is less than zero or greater than 65535. - - is not supported by the underlying platform. - - is not supported by the underlying platform. - - - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.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 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.Encoding - - - - - - - - The code page name of the preferred encoding. Any value returned by the property is valid. Possible values are listed in the Name column of the table that appears in the class topic. - An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. - An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. - Returns the encoding associated with the specified code page name. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. - The encoding that is associated with the specified code page. - - method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. - -In .NET 5 and later versions, the code page name `utf-7` is not supported. - -> [!NOTE] -> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For the most consistent results, you should use a Unicode encoding, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cpp/fallEncRpl.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/sys.txt.fallbackEncRpl/vb/fallEncRpl.vb" id="Snippet1"::: - - ]]> - - - is not a valid code page name. - - -or- - - The code page indicated by is not supported by the underlying platform. - - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Text.EncodingInfo[] - - - - Returns an array that contains all encodings. - An array that contains all encodings. - - . - -> [!NOTE] -> In .NET 5 and later versions, the list of supported encodings that returns includes any additional encodings made available by any implementations that were registered by calling . -> -> In .NET Framework and .NET Core, the returned list of supported encodings *does not* include these additional encodings. -> -> Therefore, if running on .NET Framework or .NET 5+ with the code pages encoding provider registered via `Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);`, you'll get a result similar to the list in the previous code example. If running on .NET Core versions up to version 3.x, you'll get the basic list. - - On .NET Framework, encodings 50220 and 50222 are both associated with the name "iso-2022-jp", but they are not identical. Encoding 50220 converts half-width Katakana characters to full-width Katakana characters, whereas encoding 50222 uses a shift-in/shift-out sequence to encode half-width Katakana characters. The display name for encoding 50222 is "Japanese (JIS-Allow 1 byte Kana - SO/SI)" to distinguish it from encoding 50220, which has the display name "Japanese (JIS)". - - If you request the encoding name "iso-2022-jp", .NET Framework returns encoding 50220. However, the encoding that is appropriate for your app depends on the preferred treatment of the half-width Katakana characters. - - To get a specific encoding, use the method. - - is sometimes used to present the user with a list of encodings in a File **Save as** dialog box. However, many non-Unicode encodings are either incomplete and translate many characters to "?", or have subtly different behavior on different platforms. Consider using UTF-8 or UTF-16 as the default. - -## Examples - The following example checks the values of the Boolean properties of each encoding. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/CPP/isprops.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetEncodings/isprops.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/VB/isprops.vb" id="Snippet1"::: - - ]]> - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - Returns the hash code for the current instance. - The hash code for the current instance. - To be added. - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The number of characters to encode. - When overridden in a derived class, 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. - - objects that represent the Unicode characters to encode, because .NET internally uses UTF-16 to represent Unicode characters. Consequently, most Unicode characters can be represented by one object, but a Unicode character represented by a surrogate pair, for example, requires two objects. - - To calculate the exact array size required by to store the resulting bytes, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values, particularly in cases where the worst case for the encoding involves switching modes for every character. For example, this can happen for ISO-2022-JP. For more information, see the blog post "[What's with Encoding.GetMaxByteCount() and Encoding.GetMaxCharCount()?](https://blogs.msdn.microsoft.com/shawnste/2005/03/02/whats-with-encoding-getmaxbytecount-and-encoding-getmaxcharcount/). - - In most cases, this method retrieves reasonable values for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case when a more reasonable buffer is too small. You might also want to consider a different approach using or . - - When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. - - Note that considers potential leftover surrogates from a previous decoder operation. Because of the decoder, passing a value of 1 to the method retrieves 2 for a single-byte encoding, such as ASCII. You should use the property if this information is necessary. - -> [!NOTE] -> `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. - -## Examples - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - - ]]> - - - is less than zero. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - All implementations must guarantee that no buffer overflow exceptions occur if buffers are sized according to the results of this method's calculations. - - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The number of bytes to decode. - When overridden in a derived class, 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, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values. - - In most cases, this method retrieves 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 too small. You might also want to consider a different approach using or . - - has no relation to . If you needs a similar function to use with , you should use . - - When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. - - Note that considers the worst case for leftover bytes from a previous encoder operation. For most code pages, passing a value of 0 to this method retrieves values greater than or equal to 1. - -> [!NOTE] -> `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. - -## Examples - The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: - - ]]> - - - is less than zero. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - All implementations must guarantee that no buffer overflow exceptions occur if buffers are sized according to the results of this method's calculations. - - - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Byte[] - - - - When overridden in a derived class, returns a sequence of bytes that specifies the encoding used. - A byte array containing a sequence of bytes that specifies the encoding used. - - -or- - - A byte array of length zero, if a preamble is not required. - - object provides a preamble that is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (in Unicode, code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. - - The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): - -- UTF-8: EF BB BF - -- UTF-16 big endian byte order: FE FF - -- UTF-16 little endian byte order: FF FE - -- UTF-32 big endian byte order: 00 00 FE FF - -- UTF-32 little endian byte order: FF FE 00 00 - - You should use the BOM, because it provides nearly certain identification of an encoding for files that otherwise have lost reference to the object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged, preferably in UTF-8 or UTF-16. - - For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. - - There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. - - For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://home.unicode.org/). - -> [!CAUTION] -> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, you should use a Unicode encoding, that is, , , or , with a preamble. - -## Examples - The following example determines the byte order of the encoding based on the preamble. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetPreamble Example/CPP/preamble.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetPreamble/preamble.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetPreamble Example/VB/preamble.vb" id="Snippet1"::: - - ]]> - - - - - - System.Text.Encoding - 4.0.10.0 - - - When overridden in a derived class, decodes a sequence of bytes into a string. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.String - - - - - - The byte array containing the sequence of bytes to decode. - When overridden in a derived class, decodes all the bytes in the specified byte array into a string. - A string that contains the results of decoding the specified sequence of bytes. - - object returned by the method of a derived class. - - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. - - Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. - -## Examples - The following example reads a UTF-8 encoded string from a binary file represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetString/VB/getstring1.vb" id="Snippet2"::: - - The example uses the following text, which should be saved to a UTF-8 encoded file named Utf8Example.txt. - -```txt - -This is a UTF-8-encoded file that contains primarily Latin text, although it -does list the first twelve letters of the Russian (Cyrillic) alphabet: - -А б в г д е ё ж з и й к - -The goal is to save this file, then open and decode it as a binary stream. - -``` - - ]]> - - The byte array contains invalid Unicode code points. - - is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.String - - - - - - A read-only byte span to decode to a Unicode string. - When overridden in a derived class, decodes all the bytes in the specified byte span into a string. - A string that contains the decoded bytes from the provided read-only span. - - method is designed to optimize performance. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. - - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. - - Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. - - ]]> - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.String - - - - - - - A pointer to a byte array. - The number of bytes to decode. - When overridden in a derived class, decodes a specified number of bytes starting at a specified address into a string. - A string that contains the results of decoding the specified sequence of bytes. - - method is designed to optimize performance when you have a native pointer to a byte array. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. - - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. - - Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. - - ]]> - - - is a null pointer. - - is less than zero. - A fallback occurred (see Character Encoding in .NET) for a complete explanation) - - -and- - - is set to . - - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - 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. - When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a string. - A string that contains the results of decoding the specified sequence of bytes. - - or the provided by the method or the method, respectively, of a derived class. - - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. - -## Examples - The following example reads a UTF-8 encoded string from a binary file that is represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring2.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetString/VB/getstring2.vb" id="Snippet3"::: - - The example uses the following text, which should be saved to a UTF-8 encoded file named Utf8Example.txt. - -```txt - -This is a UTF-8-encoded file that contains primarily Latin text, although it -does list the first twelve letters of the Russian (Cyrillic) alphabet: - -А б в г д е ё ж з и й к - -The goal is to save this file, then open and decode it as a binary stream. - -``` - - ]]> - - The byte array contains invalid Unicode code points. - - 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 . - - - - - - - - - - - - - - Property - - 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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.String - - - When overridden in a derived class, gets a name for the current encoding that can be used with mail agent header tags. - A name for the current to use with mail agent header tags. - - -or- - - An empty string (""), if the current cannot be used. - - method with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding. - - In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. - - Note that returns the name to use to describe an encoding. The property defines a different encoding that might work better for an email application, for example. However, use of the property to define the encoding is not recommended. - -## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - Gets a value indicating whether the current encoding is always normalized. - - - - - - - - - - Method - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Boolean - - - - Gets a value indicating whether the current encoding is always normalized, using the default normalization form. - - if the current is always normalized; otherwise, . The default is . - - , which uses full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. - - ]]> - - - - - - - - - - - - Method - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Boolean - - - - - - One of the values. - When overridden in a derived class, gets a value indicating whether the current encoding is always normalized, using the specified normalization form. - - if the current object is always normalized using the specified value; otherwise, . The default is . - - , which uses full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. - - ]]> - - - - - - - - - - - - Property - - 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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding can be used by browser clients for displaying content. - - if the current can be used by browser clients for displaying content; otherwise, . - - - - - - - - - - - - - - Property - - 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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding can be used by browser clients for saving content. - - if the current can be used by browser clients for saving content; otherwise, . - - - - - - - - - - - - - - Property - - 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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding can be used by mail and news clients for displaying content. - - if the current can be used by mail and news clients for displaying content; otherwise, . - - - - - - - - - - - - - - Property - - 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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding can be used by mail and news clients for saving content. - - if the current can be used by mail and news clients for saving content; otherwise, . - - - - - - - - - - - - - - Property - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding is read-only. - - if the current is read-only; otherwise, . The default is . - To be added. - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.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 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding uses single-byte code points. - - if the current uses single-byte code points; otherwise, . - - , this property retrieves `true`. - -> [!CAUTION] -> You should be careful in what your application does with the value for . An assumption of how an Encoding will proceed may still be wrong. For example, Windows-1252 has a value of `true` for , but Encoding.GetMaxByteCount(1) returns 2. This is because the method considers potential leftover surrogates from a previous decoder operation. - -## Examples - The following example checks the values of the Boolean properties of each encoding. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/CPP/isprops.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetEncodings/isprops.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/VB/isprops.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - Property - - System.Runtime - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - mscorlib - - - netstandard - - - System.Text.Encoding - - - Gets an encoding for the Latin1 character set (ISO-8859-1). - To be added. - To be added. - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [get: System.Runtime.CompilerServices.NullableContext(0)] - [<get: System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.ReadOnlySpan<System.Byte> - - - When overridden in a derived class, returns a span containing the sequence of bytes that specifies the encoding used. - A byte span containing a sequence of bytes that specifies the encoding used, or a span of length zero, if a preamble is not required. - - object provides a preamble that is an sequence of bytes that can be prefixed to the bytes resulting from the encoding process. If the preamble contains a byte order mark (in Unicode, code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. - - The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): - -- UTF-8: EF BB BF - -- UTF-16 big endian byte order: FE FF - -- UTF-16 little endian byte order: FF FE - -- UTF-32 big endian byte order: 00 00 FE FF - -- UTF-32 little endian byte order: FF FE 00 00 - - You should use the BOM, because it provides nearly certain identification of an encoding for files that otherwise have lost reference to the object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged, preferably in UTF-8 or UTF-16. - - For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. - - There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. Despite the few disadvantages, however, the use of a BOM is highly recommended. - - For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://home.unicode.org/). - -> [!CAUTION] -> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, you should use a Unicode encoding, that is, , , or , with a preamble. - - ]]> - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - - System.Void - - - - - - A subclass of that provides access to additional character encodings. - Registers an encoding provider. - - method allows you to register a class derived from that makes character encodings available on a platform that does not otherwise support them. Once the encoding provider is registered, the encodings that it supports can be retrieved by calling any overload. If there are multiple encoding providers, the method attempts to retrieve a specified encoding from each provider starting with the one most recently registered. - -Registering an encoding provider by using the method also modifies the behavior of the [Encoding.GetEncoding(Int32)]() and [EncodingProvider.GetEncoding(Int32, EncoderFallback, DecoderFallback)](xref:System.Text.Encoding.GetEncoding(System.Int32,System.Text.EncoderFallback,System.Text.DecoderFallback)) methods when passed an argument of `0`: - -- If the registered provider is the , the method returns the encoding that matches the system active code page when running on the Windows operating system. - -- A custom encoding provider can choose which encoding to return when either of these method overloads is passed an argument of `0`. The provider can also choose to not return an encoding by having the method return `null`. - -Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, , that makes the encodings available that are present in the full .NET Framework but are not available in the Universal Windows Platform. By default, the Universal Windows Platform only supports the Unicode encodings, ASCII, and code page 28591. - - If the same encoding provider is used in multiple calls to the method, only the first method call registers the provider. Subsequent calls are ignored. - - If the method is called to register multiple providers that handle the same encoding, the last registered provider is the used for all encoding and decoding operations. Any previously registered providers are ignored. - - ]]> - - - is . - - - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Text.Encoding - - - mscorlib - - - netstandard - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Boolean - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Text.Encoding - - - mscorlib - - - netstandard - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Boolean - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Property - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.Encoding - - - Gets an encoding for the UTF-16 format using the little endian byte order. - An encoding for the UTF-16 format using the little endian byte order. - - object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a little endian object whose fallback is either an or a , as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Unicode/unicode1.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.unicode/vb/unicode1.vb" id="Snippet2"::: - -## Examples - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - - ]]> - - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.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 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - Gets an encoding for the UTF-32 format using the little endian byte order. - An encoding object for the UTF-32 format using the little endian byte order. - - object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with the Unicode REPLACEMENT CHARACTER (U+FFFE). Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF32/encoding.utf32.1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf32/vb/encoding.utf32.1.vb" id="Snippet1"::: - - For a discussion of little endian byte order, see . - - For information about the encodings supported by .NET and a discussion of which Unicode encoding to use, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - -## Examples - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - - ]]> - - - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.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}")>] - - - - System.Text.Encoding - - - Gets an encoding for the UTF-7 format. - An encoding for the UTF-7 format. - - - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.Encoding - - - Gets an encoding for the UTF-8 format. - An encoding for the UTF-8 format. - - object that encodes Unicode (UTF-16-encoded) characters into a sequence of one to four bytes per character, and that decodes a UTF-8-encoded byte array to Unicode (UTF-16-encoded) characters. For information about the character encodings supported by .NET and a discussion of which Unicode encoding to use, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - - The object that is returned by this property might not have the appropriate behavior for your app. - -- It returns a object that provides a Unicode byte order mark (BOM). To instantiate a UTF8 encoding that doesn't provide a BOM, call any overload of the constructor. - -- It returns a object that uses replacement fallback to replace each string that it can't encode and each byte that it can't decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF8/encoding.utf8.1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf8/vb/encoding.utf8.1.vb" id="Snippet1"::: - -## Examples - The following example defines an array that consists of the following characters: - -- LATIN SMALL LETTER Z (U+007A) - -- LATIN SMALL LETTER A (U+0061) - -- COMBINING BREVE (U+0306) - -- LATIN SMALL LETTER AE WITH ACUTE (U+01FD) - -- GREEK SMALL LETTER BETA (U+03B2) - -- A surrogate pair (U+D800 U+DD54) that forms GREEK ACROPHONIC ATTIC ONE THOUSAND STATERS (U+10154). - - It displays the UTF-16 code units of each character and determines the number of bytes required by a UTF-8 encoder to encode the character array. It then encodes the characters and displays the resulting UTF-8-encoded bytes. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF8/example1.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf8/vb/example1.vb" id="Snippet2"::: - - ]]> - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.0.0 - 4.0.10.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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - [get: System.Security.SecuritySafeCritical] - [<get: System.Security.SecuritySafeCritical>] - - - - System.String - - - When overridden in a derived class, gets the name registered with the Internet Assigned Numbers Authority (IANA) for the current encoding. - The IANA name for the current . - - property is the same as the property. - - Note that returns an IANA-registered name for the encoding. When its value is the name of a standard, the implementation of the encoding might not conform in full to that standard. The property defines a different encoding that might work better for email headers. However, most apps should use instead. - - For more information on the IANA, go to [www.iana.org](https://www.iana.org/). - - The is the same as the returned by . Some of the web names are duplicates; see the remarks for for more information. - -## Examples - The following example includes the in an HTML header. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.WebName/CPP/webname.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/WebName/webname.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.WebName/VB/webname.vb" id="Snippet1"::: - - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - - - - - Property - - 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.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Int32 - - - When overridden in a derived class, gets the Windows operating system code page that most closely corresponds to the current encoding. - The Windows operating system code page that most closely corresponds to the current . - - instead of to identify the code page. - -## Examples - The following example determines the Windows code page that most closely corresponds to each encoding. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.CodePage/CPP/codepage.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/WindowsCodePage/codepage.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.CodePage/VB/codepage.vb" id="Snippet1"::: - - ]]> - - - - - - - + + + + + + + + + + + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + + + + + + + + + + + + System.Object + + + + System.ICloneable + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Serializable] + [<System.Serializable>] + + + [System.Runtime.InteropServices.ComVisible(true)] + [<System.Runtime.InteropServices.ComVisible(true)>] + + + + Represents a character encoding. + + , see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). + +Note that is intended to operate on Unicode characters instead of arbitrary binary data, such as byte arrays. If you must encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + +.NET provides the following implementations of the class to support current Unicode encodings and other encodings: + +- encodes Unicode characters as single 7-bit ASCII characters. This encoding only supports character values between U+0000 and U+007F. Code page 20127. Also available through the property. + +- encodes Unicode characters using the UTF-7 encoding. This encoding supports all Unicode character values. Code page 65000. Also available through the property. + +- encodes Unicode characters using the UTF-8 encoding. This encoding supports all Unicode character values. Code page 65001. Also available through the property. + +- encodes Unicode characters using the UTF-16 encoding. Both little endian and big endian byte orders are supported. Also available through the property and the property. + +- encodes Unicode characters using the UTF-32 encoding. Both little endian (code page 12000) and big endian (code page 12001) byte orders are supported. Also available through the property. + +The class is primarily intended to convert between different encodings and Unicode. Often one of the derived Unicode classes is the correct choice for your app. + +Use the method to obtain other encodings, and call the method to get a list of all encodings. + +### List of encodings + +The following table lists the encodings supported by .NET. It lists each encoding's code page number and the values of the encoding's and properties. A check mark in the **.NET Framework support**, **.NET Core support**, or **.NET 5 and later support** column indicates that the code page is natively supported by that .NET implementation, regardless of the underlying platform. For .NET Framework, the availability of other encodings listed in the table depends on the operating system. For .NET Core and .NET 5 and later versions, other encodings are available by using the class or by deriving from the class. + +> [!NOTE] +> Code pages whose property corresponds to an international standard do not necessarily comply in full with that standard. + +|Code page|Name|Display name|.NET Framework support| .NET Core support | .NET 5 and later support | +|---------|----|------------|----------------------|-------------------|----------------------------| +|37|IBM037|IBM EBCDIC (US-Canada)|||| +|437|IBM437|OEM United States|||| +|500|IBM500|IBM EBCDIC (International)|||| +|708|ASMO-708|Arabic (ASMO 708)|||| +|720|DOS-720|Arabic (DOS)|||| +|737|ibm737|Greek (DOS)|||| +|775|ibm775|Baltic (DOS)|||| +|850|ibm850|Western European (DOS)|||| +|852|ibm852|Central European (DOS)|||| +|855|IBM855|OEM Cyrillic|||| +|857|ibm857|Turkish (DOS)|||| +|858|IBM00858|OEM Multilingual Latin I|||| +|860|IBM860|Portuguese (DOS)|||| +|861|ibm861|Icelandic (DOS)|||| +|862|DOS-862|Hebrew (DOS)|||| +|863|IBM863|French Canadian (DOS)|||| +|864|IBM864|Arabic (864)|||| +|865|IBM865|Nordic (DOS)|||| +|866|cp866|Cyrillic (DOS)|||| +|869|ibm869|Greek, Modern (DOS)|||| +|870|IBM870|IBM EBCDIC (Multilingual Latin-2)|||| +|874|windows-874|Thai (Windows)|||| +|875|cp875|IBM EBCDIC (Greek Modern)|||| +|932|shift_jis|Japanese (Shift-JIS)|||| +|936|gb2312|Chinese Simplified (GB2312)|✓||| +|949|ks_c_5601-1987|Korean|||| +|950|big5|Chinese Traditional (Big5)|||| +|1026|IBM1026|IBM EBCDIC (Turkish Latin-5)|||| +|1047|IBM01047|IBM Latin-1|||| +|1140|IBM01140|IBM EBCDIC (US-Canada-Euro)|||| +|1141|IBM01141|IBM EBCDIC (Germany-Euro)|||| +|1142|IBM01142|IBM EBCDIC (Denmark-Norway-Euro)|||| +|1143|IBM01143|IBM EBCDIC (Finland-Sweden-Euro)|||| +|1144|IBM01144|IBM EBCDIC (Italy-Euro)|||| +|1145|IBM01145|IBM EBCDIC (Spain-Euro)|||| +|1146|IBM01146|IBM EBCDIC (UK-Euro)|||| +|1147|IBM01147|IBM EBCDIC (France-Euro)|||| +|1148|IBM01148|IBM EBCDIC (International-Euro)|||| +|1149|IBM01149|IBM EBCDIC (Icelandic-Euro)|||| +|1200|utf-16|Unicode|✓|✓|✓| +|1201|unicodeFFFE|Unicode (Big endian)|✓|✓|✓| +|1250|windows-1250|Central European (Windows)|||| +|1251|windows-1251|Cyrillic (Windows)|||| +|1252|Windows-1252|Western European (Windows)|✓|||| +|1253|windows-1253|Greek (Windows)|||| +|1254|windows-1254|Turkish (Windows)|||| +|1255|windows-1255|Hebrew (Windows)|||| +|1256|windows-1256|Arabic (Windows)|||| +|1257|windows-1257|Baltic (Windows)|||| +|1258|windows-1258|Vietnamese (Windows)|||| +|1361|Johab|Korean (Johab)|||| +|10000|macintosh|Western European (Mac)|||| +|10001|x-mac-japanese|Japanese (Mac)|||| +|10002|x-mac-chinesetrad|Chinese Traditional (Mac)|||| +|10003|x-mac-korean|Korean (Mac)|✓||| +|10004|x-mac-arabic|Arabic (Mac)|||| +|10005|x-mac-hebrew|Hebrew (Mac)|||| +|10006|x-mac-greek|Greek (Mac)|||| +|10007|x-mac-cyrillic|Cyrillic (Mac)|||| +|10008|x-mac-chinesesimp|Chinese Simplified (Mac)|✓||| +|10010|x-mac-romanian|Romanian (Mac)|||| +|10017|x-mac-ukrainian|Ukrainian (Mac)|||| +|10021|x-mac-thai|Thai (Mac)|||| +|10029|x-mac-ce|Central European (Mac)|||| +|10079|x-mac-icelandic|Icelandic (Mac)|||| +|10081|x-mac-turkish|Turkish (Mac)|||| +|10082|x-mac-croatian|Croatian (Mac)|||| +|12000|utf-32|Unicode (UTF-32)|✓|✓|✓| +|12001|utf-32BE|Unicode (UTF-32 Big endian)|✓|✓|✓| +|20000|x-Chinese-CNS|Chinese Traditional (CNS)|||| +|20001|x-cp20001|TCA Taiwan|||| +|20002|x-Chinese-Eten|Chinese Traditional (Eten)|||| +|20003|x-cp20003|IBM5550 Taiwan|||| +|20004|x-cp20004|TeleText Taiwan|||| +|20005|x-cp20005|Wang Taiwan|||| +|20105|x-IA5|Western European (IA5)|||| +|20106|x-IA5-German|German (IA5)|||| +|20107|x-IA5-Swedish|Swedish (IA5)|||| +|20108|x-IA5-Norwegian|Norwegian (IA5)|||| +|20127|us-ascii|US-ASCII|✓|✓|✓| +|20261|x-cp20261|T.61|||| +|20269|x-cp20269|ISO-6937|||| +|20273|IBM273|IBM EBCDIC (Germany)|||| +|20277|IBM277|IBM EBCDIC (Denmark-Norway)|||| +|20278|IBM278|IBM EBCDIC (Finland-Sweden)|||| +|20280|IBM280|IBM EBCDIC (Italy)|||| +|20284|IBM284|IBM EBCDIC (Spain)|||| +|20285|IBM285|IBM EBCDIC (UK)|||| +|20290|IBM290|IBM EBCDIC (Japanese katakana)|||| +|20297|IBM297|IBM EBCDIC (France)|||| +|20420|IBM420|IBM EBCDIC (Arabic)|||| +|20423|IBM423|IBM EBCDIC (Greek)|||| +|20424|IBM424|IBM EBCDIC (Hebrew)|||| +|20833|x-EBCDIC-KoreanExtended|IBM EBCDIC (Korean Extended)|||| +|20838|IBM-Thai|IBM EBCDIC (Thai)|||| +|20866|koi8-r|Cyrillic (KOI8-R)|||| +|20871|IBM871|IBM EBCDIC (Icelandic)|||| +|20880|IBM880|IBM EBCDIC (Cyrillic Russian)|||| +|20905|IBM905|IBM EBCDIC (Turkish)|||| +|20924|IBM00924|IBM Latin-1|||| +|20932|EUC-JP|Japanese (JIS 0208-1990 and 0212-1990)|||| +|20936|x-cp20936|Chinese Simplified (GB2312-80)|✓||| +|20949|x-cp20949|Korean Wansung|✓||| +|21025|cp1025|IBM EBCDIC (Cyrillic Serbian-Bulgarian)|||| +|21866|koi8-u|Cyrillic (KOI8-U)|||| +|28591|iso-8859-1|Western European (ISO)|✓|✓|✓| +|28592|iso-8859-2|Central European (ISO)|||| +|28593|iso-8859-3|Latin 3 (ISO)|||| +|28594|iso-8859-4|Baltic (ISO)|||| +|28595|iso-8859-5|Cyrillic (ISO)|||| +|28596|iso-8859-6|Arabic (ISO)|||| +|28597|iso-8859-7|Greek (ISO)|||| +|28598|iso-8859-8|Hebrew (ISO-Visual)|✓||| +|28599|iso-8859-9|Turkish (ISO)|||| +|28603|iso-8859-13|Estonian (ISO)|||| +|28605|iso-8859-15|Latin 9 (ISO)|||| +|29001|x-Europa|Europa|||| +|38598|iso-8859-8-i|Hebrew (ISO-Logical)|✓||| +|50220|iso-2022-jp|Japanese (JIS)|✓||| +|50221|csISO2022JP|Japanese (JIS-Allow 1 byte Kana)|✓||| +|50222|iso-2022-jp|Japanese (JIS-Allow 1 byte Kana - SO/SI)|✓||| +|50225|iso-2022-kr|Korean (ISO)|✓||| +|50227|x-cp50227|Chinese Simplified (ISO-2022)|✓||| +|51932|euc-jp|Japanese (EUC)|✓||| +|51936|EUC-CN|Chinese Simplified (EUC)|✓||| +|51949|euc-kr|Korean (EUC)|✓||| +|52936|hz-gb-2312|Chinese Simplified (HZ)|✓||| +|54936|GB18030|Chinese Simplified (GB18030)|✓||| +|57002|x-iscii-de|ISCII Devanagari|✓||| +|57003|x-iscii-be|ISCII Bengali|✓||| +|57004|x-iscii-ta|ISCII Tamil|✓||| +|57005|x-iscii-te|ISCII Telugu|✓||| +|57006|x-iscii-as|ISCII Assamese|✓||| +|57007|x-iscii-or|ISCII Oriya|✓||| +|57008|x-iscii-ka|ISCII Kannada|✓||| +|57009|x-iscii-ma|ISCII Malayalam|✓||| +|57010|x-iscii-gu|ISCII Gujarati|✓||| +|57011|x-iscii-pa|ISCII Punjabi|✓||| +|65000|utf-7|Unicode (UTF-7)|✓|✓|| +|65001|utf-8|Unicode (UTF-8)|✓|✓|✓| + + The following example calls the and methods to get the Greek (Windows) code page encoding. It compares the objects returned by the method calls to show that they are equal, and then maps displays the Unicode code point and the corresponding code page value for each character in the Greek alphabet. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/getencoding1.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding/vb/getencoding1.vb" id="Snippet1"::: + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + The UTF-16 and the UTF-32 encoders can use the big endian byte order (most significant byte first) or the little endian byte order (least significant byte first). For example, the Latin Capital Letter A (U+0041) is serialized as follows (in hexadecimal): + +- UTF-16 big endian byte order: 00 41 + +- UTF-16 little endian byte order: 41 00 + +- UTF-32 big endian byte order: 00 00 00 41 + +- UTF-32 little endian byte order: 41 00 00 00 + + It is generally more efficient to store Unicode characters using the native byte order. For example, it is better to use the little endian byte order on little endian platforms, such as Intel computers. + + The method retrieves an array of bytes that includes the byte order mark (BOM). If this byte array is prefixed to an encoded stream, it helps the decoder to identify the encoding format used. + + For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://home.unicode.org/). + + Note that the encoding classes allow errors to: + +- Silently change to a "?" character. + +- Use a "best fit" character. + +- Change to an application-specific behavior through use of the and classes with the U+FFFD Unicode replacement character. + + You should throw an exception on any data stream error. An app either uses a "throwonerror" flag when applicable or uses the and classes. Best fit fallback is often not recommended because it can cause data loss or confusion and is slower than simple character replacements. For ANSI encodings, the best fit behavior is the default. + +## Examples + The following example converts a string from one encoding to another. + +> [!NOTE] +> The `byte[]` array is the only type in this example that contains the encoded data. The .NET `Char` and `String` types are themselves Unicode, so the call decodes the data back to Unicode. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: + + ]]> + + How to use character encoding classes in .NET + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + Initializes a new instance of the class. + + + + + + + + + Constructor + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + Initializes a new instance of the class. + + + + + + + + + + + + + + + Constructor + + System.Text.Encoding + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + + + + The code page identifier of the preferred encoding. + + -or- + + 0, to use the default encoding. + Initializes a new instance of the class that corresponds to the specified code page. + + object that uses best-fit fallback for both encoding and decoding operations. Both the and properties are read-only and cannot be modified. To control the fallback strategy for a class derived from , call the constructor. + + ]]> + + + is less than zero. + + + + + + + + + + + + + Constructor + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + + + + + + The encoding code page identifier. + An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. + An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. + Initializes a new instance of the class that corresponds to the specified code page with the specified encoder and decoder fallback strategies. + + class constructors create read-only encoding objects that don't allow encoder or decoder fallback to be set after the object is created. + + If either `encoderFallback` or `decoderFallback` is null, best-fit fallback is used as the corresponding fallback strategy. + + ]]> + + + is less than zero. + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.Encoding + + + Gets an encoding for the ASCII (7-bit) character set. + An encoding for the ASCII (7-bit) character set. + + object that is returned by this property might not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the method to instantiate an object whose fallback is either an or a , as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/ASCII/encoding.ascii2.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.ascii/vb/encoding.ascii2.vb" id="Snippet1"::: + +## Examples + +The following example demonstrates the effect of the ASCII encoding on characters that are outside the ASCII range. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.ASCII Example/CPP/ascii.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/ASCII/ascii.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.ASCII Example/VB/ascii.vb" id="Snippet1"::: + + ]]> + + + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + Gets an encoding for the UTF-16 format that uses the big endian byte order. + An encoding object for the UTF-16 format that uses the big endian byte order. + + object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a big endian object whose fallback is either an or a , as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/bigendianunicode1.cs" interactive="try-dotnet" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/VB/bigendianunicode1.vb" id="Snippet2"::: + + The returned object has , , and properties, which yield the name "unicodeFFFE". Although the UTF-16 big endian byte order mark is hexadecimal FEFF, the name "unicodeFFFE" was chosen because the byte order mark appears as hexadecimal FFFE on little endian Windows computers. + +## Examples + The following example reads a text file with a UTF-16 encoding using the big endian byte order. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/CPP/bigendianunicode.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/bigendianunicode.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/VB/bigendianunicode.vb" id="Snippet1"::: + + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + + ]]> + + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + 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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.String + + + When overridden in a derived class, gets a name for the current encoding that can be used with mail agent body tags. + A name for the current that can be used with mail agent body tags. + + -or- + + An empty string (""), if the current cannot be used. + + with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding; most other applications that need to describe an encoding should use its . + + In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. + +## Examples + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + + + + + Method + + M:System.ICloneable.Clone + + + System.Text.Encoding + 4.0.10.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 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Object + + + + When overridden in a derived class, creates a shallow copy of the current object. + A copy of the current object. + + object is read-only. Therefore, the properties of the clone can be modified. + + A shallow copy of an object is a copy of the object only. If the object contains references to other objects, the shallow copy does not create copies of the referred objects. It refers to the original objects instead. In contrast, a deep copy of an object creates a copy of the object and a copy of everything directly or indirectly referenced by that object. + + ]]> + + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + When overridden in a derived class, gets the code page identifier of the current . + The code page identifier of the current . + + . It displays but does not compare against it. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: + + ]]> + + + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + Converts a byte array from one encoding to another. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Byte[] + + + + + + + + The encoding format of . + The target encoding format. + The bytes to convert. + Converts an entire byte array from one encoding to another. + An array of type containing the results of converting from to . + + property uses replacement fallback and the Pi character is not part of the ASCII character set, the Pi character is replaced with a question mark, as the output from the example shows. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: + + ]]> + + + is . + + -or- + + is . + + -or- + + is . + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + **srcEncoding.** is set to . + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + **dstEncoding.** is set to . + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Byte[] + + + + + + + + + + The encoding of the source array, . + The encoding of the output array. + The array of bytes to convert. + The index of the first element of to convert. + The number of bytes to convert. + Converts a range of bytes in a byte array from one encoding to another. + An array of type containing the result of converting a range of bytes in from to . + To be added. + + is . + + -or- + + is . + + -or- + + is . + + and do not specify a valid range in the byte array. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + **srcEncoding.** is set to . + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + **dstEncoding.** is set to . + + + + + + + + + Method + + System.Runtime + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + mscorlib + + + netstandard + + + System.IO.Stream + + + + + + + + + The stream to wrap. + The encoding associated with . + The encoding associated with the that's returned by this method. + + if disposing the returned by this method should not dispose . + Creates a that serves to transcode data between an inner and an outer , similar to . + A stream that transcodes the contents of as . + + 's and properties will reflect whether `innerStream` is readable or writable. If `innerStream` is full-duplex, the returned will be as well. However, the returned is not seekable, even if `innerStream`'s property returns `true`. + + ]]> + + + + + + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.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 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Text.DecoderFallback + + + Gets or sets the object for the current object. + The decoder fallback object for the current object. + + object represents an error handler that is invoked when an encoded byte sequence cannot be decoded into a character. Any one of the following handler types is supported: + +- A best-fit fallback handler, which replaces bytes that cannot be decoded with some suitable replacement character. + +- A replacement fallback handler, which replaces bytes that cannot be decoded with some arbitrary replacement character. .NET includes one replacement fallback handler, , which by default replaces bytes that cannot be decoded with a question mark ("?") character. + +- An exception fallback handler, which throws an exception when bytes cannot be decoded. .NET includes one exception fallback handler, , which throws a when bytes cannot be decoded. + + ]]> + + The value in a set operation is . + A value cannot be assigned in a set operation because the current object is read-only. + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + 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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + [get: System.Security.SecuritySafeCritical] + [<get: System.Security.SecuritySafeCritical>] + + + + System.Text.Encoding + + + Gets the default encoding for this .NET implementation. + The default encoding for this .NET implementation. + + [!WARNING] +> Different computers can use different encodings as the default, and the default encoding can change on a single computer. If you use the encoding to encode and decode data streamed between computers or retrieved at different times on the same computer, it may translate that data incorrectly. In addition, the encoding returned by the property uses best-fit fallback to map unsupported characters to characters supported by the code page. For these reasons, using the default encoding is not recommended. To ensure that encoded bytes are decoded properly, you should use a Unicode encoding, such as or . You could also use a higher-level protocol to ensure that the same format is used for encoding and decoding. + +### The Default property in .NET Framework + +In .NET Framework on the Windows desktop, the property always gets the system's active code page and creates a object that corresponds to it. The active code page may be an ANSI code page, which includes the ASCII character set along with additional characters that vary by code page. Because all encodings based on ANSI code pages lose data, consider using the encoding instead. UTF-8 is often identical in the U+00 to U+7F range, but can encode characters outside the ASCII range without loss. + +## The Default property on .NET Core + +On .NET Core, the property always returns the . UTF-8 is supported on all the operating systems (Windows, Linux, and macOS) on which .NET Core applications run. + + ]]> + + + + + + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.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 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Text.EncoderFallback + + + Gets or sets the object for the current object. + The encoder fallback object for the current object. + + object represents an error handler that is invoked when a character cannot be converted into an encoded byte sequence. Any one of the following handler types is supported: + +- A best-fit fallback handler, which replaces characters that cannot be encoded with some suitable replacement character. + +- A replacement fallback handler, which replaces characters that cannot be encoded with some arbitrary replacement character. .NET includes one replacement fallback handler, , which by default replaces characters that cannot be encoded with a question mark ("?") character. + +- An exception fallback handler, which throws an exception when characters cannot be encoded. .NET includes one exception fallback handler, , which throws an when characters cannot be decoded. + + ]]> + + The value in a set operation is . + A value cannot be assigned in a set operation because the current object is read-only. + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.String + + + When overridden in a derived class, gets the human-readable description of the current encoding. + The human-readable description of the current . + + property is intended for display. To find a name that can be passed to the method, use the property. + +## Examples + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Boolean + + + + + + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] + [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] + + + + + + The to compare with the current instance. + Determines whether the specified is equal to the current instance. + + if is an instance of and is equal to the current instance; otherwise, . + + are considered equal if they correspond to the same code page and their `EncoderFallback` and `DecoderFallback` objects are equal. In particular, derived code pages all have a code page of 0 and their fallbacks are normally `null` (`Nothing` in Visual Basic .NET). Thus they are all considered equal to one another. One consequence is that when is used to populate a hash table, all derived encodings compare equal and fall into the same hash table slot. + +## Examples + The following example gets two instances of the same encoding (one by codepage and another by name), and checks their equality. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: + + ]]> + + + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The character array containing the characters to encode. + When overridden in a derived class, calculates the number of bytes produced by encoding all the characters in the specified character array. + The number of bytes produced by encoding all the characters in the specified character array. + + to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles string inputs, you should use the string versions of the method. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, you should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + + ]]> + + + is . + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Int32 + + + + + + The span of characters to encode. + When overridden in a derived class, calculates the number of bytes produced by encoding the characters in the specified character span. + The number of bytes produced by encoding the specified character span. + + to store the resulting bytes, call the method. To calculate the maximum span size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles span of characters inputs, the span version of is recommended. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output span buffer is too small. For continuous encoding of a stream, this method is often the best choice. + + ]]> + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The string containing the set of characters to encode. + When overridden in a derived class, calculates the number of bytes produced by encoding the characters in the specified string. + The number of bytes produced by encoding the specified characters. + + to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles string inputs, the string version of is recommended. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: + + ]]> + + + is . + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.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 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + [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. + When overridden in a derived class, 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, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some considerations for using these methods: + +- Your app may need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles string inputs, you should use the string version of the method. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + + ]]> + + + is . + + is less than zero. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + 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. + When overridden in a derived class, 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, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles string inputs, the string version of is recommended. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.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 . + + + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + System.Int32 + + + + + + + + The string containing the set of characters to encode. + The index of the first character to encode. + The number of characters to encode. + When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified string. + The number of bytes produced by encoding the string. + + to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles string inputs, the string version of is recommended. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: + + ]]> + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + When overridden in a derived class, encodes a set of characters into a sequence of bytes. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Byte[] + + + + + + The character array containing the characters to encode. + When overridden in a derived class, encodes all the characters in the specified character array into a sequence of bytes. + A byte array containing the results of encoding the specified set of characters. + + or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should call the string version of the method. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + + ]]> + + + is . + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Byte[] + + + + + + The string containing the characters to encode. + When overridden in a derived class, encodes all the characters in the specified string into a sequence of bytes. + A byte array containing the results of encoding the specified set of characters. + + or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: + + ]]> + + + is . + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Int32 + + + + + + + The span containing the set of characters to encode. + The byte span to hold the encoded bytes. + When overridden in a derived class, encodes into a span of bytes a set of characters from the specified read-only span. + The number of encoded bytes. + + or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + + ]]> + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Byte[] + + + + + + + + The character array containing the set of characters to encode. + The index of the first character to encode. + The number of characters to encode. + When overridden in a derived class, encodes a set of characters from the specified character array into a sequence of bytes. + A byte array containing the results of encoding the specified set of characters. + + or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.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 . + + + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + System.Byte[] + + + + + + + + The string containing the characters to encode. + The index inside the string to start the encoding from. + The number of characters to encode. + When overridden in a derived class, encodes into an array of bytes the number of characters specified by in the specified string, starting from the specified . + A byte array containing the results of encoding the specified set of characters. + + or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.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 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + [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. + When overridden in a derived class, 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 the parameter. + + requires to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + + ]]> + + + is . + + -or- + + is . + + or is less than zero. + + is less than the resulting number of bytes. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + 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. + When overridden in a derived class, 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, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.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 (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + + + + + The string 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. + When overridden in a derived class, encodes a set of characters from the specified string into the specified byte array. + The actual number of bytes written into . + + to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.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 (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The byte array containing the sequence of bytes to decode. + When overridden in a derived class, calculates the number of characters produced by decoding all the bytes in the specified byte array. + The number of characters produced by decoding the specified sequence of bytes. + + to store the resulting characters, you should use the method. To calculate the maximum array size, you should use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. + +- If your app handles string outputs, you should use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + +## Examples + The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: + + ]]> + + + is . + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Int32 + + + + + + A read-only byte span to decode. + When overridden in a derived class, calculates the number of characters produced by decoding the provided read-only byte span. + The number of characters produced by decoding the byte span. + + requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + + ]]> + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.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 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + [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. + When overridden in a derived class, 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. + + requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + + ]]> + + + is . + + is less than zero. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + 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. + When overridden in a derived class, 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, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + +## Examples + The following example converts a string from one encoding to another. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: + + The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.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 . + + + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + When overridden in a derived class, decodes a sequence of bytes into a set of characters. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Char[] + + + + + + The byte array containing the sequence of bytes to decode. + When overridden in a derived class, decodes all the bytes in the specified byte array into a set of characters. + A character array containing the results of decoding the specified sequence of bytes. + + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + > [!NOTE] + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + +## Examples + The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: + + ]]> + + + is . + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Int32 + + + + + + + A read-only span containing the sequence of bytes to decode. + The character span receiving the decoded bytes. + When overridden in a derived class, decodes all the bytes in the specified read-only byte span into a character span. + The actual number of characters written at the span indicated by the parameter. + + gets characters from an input byte span. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + + ]]> + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Char[] + + + + + + + + The byte array containing the sequence of bytes to decode. + The index of the first byte to decode. + The number of bytes to decode. + When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a set of characters. + A character array containing the results of decoding the specified sequence of bytes. + + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + > [!NOTE] + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + +## Examples + The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.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 . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.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 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + [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. + When overridden in a derived class, 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 the parameter. + + requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. + + > [!NOTE] + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) + +- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + + ]]> + + + 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 + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + 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. + When overridden in a derived class, 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, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + > [!NOTE] + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) + +- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + +## Examples + The following example converts a string from one encoding to another. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: + + The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.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 + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Decoder + + + + When overridden in a derived class, obtains a decoder that converts an encoded sequence of bytes into a sequence of characters. + A that converts an encoded sequence of bytes into a sequence of 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 correctly decodes 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. + + ]]> + + + The default implementation returns a that calls the and methods of the current . You must override this method to return a that maintains its state between calls. + + + + + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoder + + + + When overridden in a derived class, obtains an encoder that converts a sequence of Unicode characters into an encoded sequence of bytes. + A that converts a sequence of Unicode characters into an encoded sequence of bytes. + + method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly encodes character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. 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. + + ]]> + + + The default implementation returns a that calls the and methods of the current . You must override this method to return a that maintains its state between calls. + + + + + + How to use character encoding classes in .NET + + + + + System.Text.Encoding + 4.0.10.0 + + + Returns an encoding for the specified code page. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.Encoding + + + + + + The code page identifier of the preferred encoding. For a list of possible values, see . + + -or- + + 0 (zero), to use the default encoding. + Returns the encoding associated with the specified code page identifier. + The encoding that is associated with the specified code page. + + overload. + + In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. + + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + +You can also supply a value of 0 for the `codepage` argument. Its precise behavior depends on whether any encodings have been made available by registering an object: + +- If one or more encoding providers have been registered, it returns the encoding of the last registered provider that has chosen to return a encoding when the method is passed a `codepage` argument of 0. + +- On .NET Framework, if no encoding provider has been registered, if the is the registered encoding provider, or if no registered encoding provider handles a `codepage` value of 0, it returns the operating system's active code page. To determine the active code page on Windows systems, call the Windows [GetACP](/windows/win32/api/winnls/nf-winnls-getacp) function from .NET Framework on the Windows desktop. + +- On .NET Core, if no encoding provider has been registered or if no registered encoding provider handles a `codepage` value of 0, it returns the . + +> [!NOTE] +> - Some unsupported code pages cause an to be thrown, whereas others cause a . Therefore, your code must catch all exceptions indicated in the Exceptions section. +> - In .NET 5 and later versions, the code page identifier `65000`, which represents UTF-7, is not supported. + +> [!NOTE] +> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For this reason, if the active code page is an ANSI code page, encoding and decoding data using the default code page returned by `Encoding.GetEncoding(0)` is not recommended. For the most consistent results, you should use a Unicode encoding, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. + + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + +## Examples + The following example gets two instances of the same encoding (one by code page and another by name), and checks their equality. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: + + ]]> + + + is less than zero or greater than 65535. + + is not supported by the underlying platform. + + is not supported by the underlying platform. + + + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.Encoding + + + + + + The code page name of the preferred encoding. Any value returned by the property is valid. For a list of possible values, see . + Returns the encoding associated with the specified code page name. + The encoding associated with the specified code page. + + overload. + +In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. + + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + +In .NET 5 and later versions, the code page name `utf-7` is not supported. + +> [!NOTE] +> The ANSI code pages can be different on different computers, or they can be changed for a single computer, leading to data corruption. For the most consistent results, use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. + + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + +## Examples + The following example gets two instances of the same encoding (one by code page and another by name), and checks their equality. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: + + ]]> + + + is not a valid code page name. + + -or- + + The code page indicated by is not supported by the underlying platform. + + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.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 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.Encoding + + + + + + + + The code page identifier of the preferred encoding. For a list of possible values, see . + + -or- + + 0 (zero), to use the default encoding. + An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. + An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. + Returns the encoding associated with the specified code page identifier. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. + The encoding that is associated with the specified code page. + + [!NOTE] +> - Some unsupported code pages cause the exception to be thrown, whereas others cause . Therefore, your code must catch all exceptions indicated in the Exceptions section. +> - In .NET 5 and later versions, the code page identifier `65000`, which represents UTF-7, is not supported. + +In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. + + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + +You can also supply a value of 0 for the `codepage` argument. Its precise behavior depends on whether any encodings have been made available by registering an object: + +- If one or more encoding providers have been registered, it returns the encoding of the last registered provider that has chosen to return a encoding when the method is passed a `codepage` argument of 0. + +- On .NET Framework, if no encoding provider has been registered, if the is the registered encoding provider, or if no registered encoding provider handles a `codepage` value of 0, it returns the active code page. + +- On .NET Core, if no encoding provider has been registered or if no registered encoding provider handles a `codepage` value of 0, it returns the encoding. + +> [!NOTE] +> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For this reason, if the active code page is an ANSI code page, encoding and decoding data using the default code page returned by `Encoding.GetEncoding(0)` is not recommended. For the most consistent results, you should use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. + + To get the encoding associated with the active code page, you can either supply a value of 0 for the `codepage` argument or, if your code is running on .NET Framework on the Windows desktop, retrieve the value of the property. To determine the current active code page, call the Windows [GetACP](/windows/win32/api/winnls/nf-winnls-getacp) function from .NET Framework on the Windows desktop. + + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cpp/fallEncRpl.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/sys.txt.fallbackEncRpl/vb/fallEncRpl.vb" id="Snippet1"::: + + ]]> + + + is less than zero or greater than 65535. + + is not supported by the underlying platform. + + is not supported by the underlying platform. + + + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.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 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.Encoding + + + + + + + + The code page name of the preferred encoding. Any value returned by the property is valid. Possible values are listed in the Name column of the table that appears in the class topic. + An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. + An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. + Returns the encoding associated with the specified code page name. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. + The encoding that is associated with the specified code page. + + method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. + + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + +In .NET 5 and later versions, the code page name `utf-7` is not supported. + +> [!NOTE] +> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For the most consistent results, you should use a Unicode encoding, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. + + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cpp/fallEncRpl.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/sys.txt.fallbackEncRpl/vb/fallEncRpl.vb" id="Snippet1"::: + + ]]> + + + is not a valid code page name. + + -or- + + The code page indicated by is not supported by the underlying platform. + + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Text.EncodingInfo[] + + + + Returns an array that contains all encodings. + An array that contains all encodings. + + . + +> [!NOTE] +> In .NET 5 and later versions, the list of supported encodings that returns includes any additional encodings made available by any implementations that were registered by calling . +> +> In .NET Framework and .NET Core, the returned list of supported encodings *does not* include these additional encodings. +> +> Therefore, if running on .NET Framework or .NET 5+ with the code pages encoding provider registered via `Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);`, you'll get a result similar to the list in the previous code example. If running on .NET Core versions up to version 3.x, you'll get the basic list. + + On .NET Framework, encodings 50220 and 50222 are both associated with the name "iso-2022-jp", but they are not identical. Encoding 50220 converts half-width Katakana characters to full-width Katakana characters, whereas encoding 50222 uses a shift-in/shift-out sequence to encode half-width Katakana characters. The display name for encoding 50222 is "Japanese (JIS-Allow 1 byte Kana - SO/SI)" to distinguish it from encoding 50220, which has the display name "Japanese (JIS)". + + If you request the encoding name "iso-2022-jp", .NET Framework returns encoding 50220. However, the encoding that is appropriate for your app depends on the preferred treatment of the half-width Katakana characters. + + To get a specific encoding, use the method. + + is sometimes used to present the user with a list of encodings in a File **Save as** dialog box. However, many non-Unicode encodings are either incomplete and translate many characters to "?", or have subtly different behavior on different platforms. Consider using UTF-8 or UTF-16 as the default. + +## Examples + The following example checks the values of the Boolean properties of each encoding. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/CPP/isprops.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetEncodings/isprops.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/VB/isprops.vb" id="Snippet1"::: + + ]]> + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + Returns the hash code for the current instance. + The hash code for the current instance. + To be added. + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The number of characters to encode. + When overridden in a derived class, 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. + + objects that represent the Unicode characters to encode, because .NET internally uses UTF-16 to represent Unicode characters. Consequently, most Unicode characters can be represented by one object, but a Unicode character represented by a surrogate pair, for example, requires two objects. + + To calculate the exact array size required by to store the resulting bytes, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values, particularly in cases where the worst case for the encoding involves switching modes for every character. For example, this can happen for ISO-2022-JP. For more information, see the blog post "[What's with Encoding.GetMaxByteCount() and Encoding.GetMaxCharCount()?](https://blogs.msdn.microsoft.com/shawnste/2005/03/02/whats-with-encoding-getmaxbytecount-and-encoding-getmaxcharcount/). + + In most cases, this method retrieves reasonable values for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case when a more reasonable buffer is too small. You might also want to consider a different approach using or . + + When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. + + Note that considers potential leftover surrogates from a previous decoder operation. Because of the decoder, passing a value of 1 to the method retrieves 2 for a single-byte encoding, such as ASCII. You should use the property if this information is necessary. + +> [!NOTE] +> `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. + +## Examples + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + + ]]> + + + is less than zero. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + All implementations must guarantee that no buffer overflow exceptions occur if buffers are sized according to the results of this method's calculations. + + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The number of bytes to decode. + When overridden in a derived class, 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, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values. + + In most cases, this method retrieves 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 too small. You might also want to consider a different approach using or . + + has no relation to . If you needs a similar function to use with , you should use . + + When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. + + Note that considers the worst case for leftover bytes from a previous encoder operation. For most code pages, passing a value of 0 to this method retrieves values greater than or equal to 1. + +> [!NOTE] +> `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. + +## Examples + The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: + + ]]> + + + is less than zero. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + All implementations must guarantee that no buffer overflow exceptions occur if buffers are sized according to the results of this method's calculations. + + + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Byte[] + + + + When overridden in a derived class, returns a sequence of bytes that specifies the encoding used. + A byte array containing a sequence of bytes that specifies the encoding used. + + -or- + + A byte array of length zero, if a preamble is not required. + + object provides a preamble that is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (in Unicode, code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. + + The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): + +- UTF-8: EF BB BF + +- UTF-16 big endian byte order: FE FF + +- UTF-16 little endian byte order: FF FE + +- UTF-32 big endian byte order: 00 00 FE FF + +- UTF-32 little endian byte order: FF FE 00 00 + + You should use the BOM, because it provides nearly certain identification of an encoding for files that otherwise have lost reference to the object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged, preferably in UTF-8 or UTF-16. + + For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. + + There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. + + For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://home.unicode.org/). + +> [!CAUTION] +> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, you should use a Unicode encoding, that is, , , or , with a preamble. + +## Examples + The following example determines the byte order of the encoding based on the preamble. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetPreamble Example/CPP/preamble.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetPreamble/preamble.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetPreamble Example/VB/preamble.vb" id="Snippet1"::: + + ]]> + + + + + + System.Text.Encoding + 4.0.10.0 + + + When overridden in a derived class, decodes a sequence of bytes into a string. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.String + + + + + + The byte array containing the sequence of bytes to decode. + When overridden in a derived class, decodes all the bytes in the specified byte array into a string. + A string that contains the results of decoding the specified sequence of bytes. + + object returned by the method of a derived class. + + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + + Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. + +## Examples + The following example reads a UTF-8 encoded string from a binary file represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring1.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetString/VB/getstring1.vb" id="Snippet2"::: + + The example uses the following text, which should be saved to a UTF-8 encoded file named Utf8Example.txt. + +```txt + +This is a UTF-8-encoded file that contains primarily Latin text, although it +does list the first twelve letters of the Russian (Cyrillic) alphabet: + +А б в г д е ё ж з и й к + +The goal is to save this file, then open and decode it as a binary stream. + +``` + + ]]> + + The byte array contains invalid Unicode code points. + + is . + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.String + + + + + + A read-only byte span to decode to a Unicode string. + When overridden in a derived class, decodes all the bytes in the specified byte span into a string. + A string that contains the decoded bytes from the provided read-only span. + + method is designed to optimize performance. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. + + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + + Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. + + ]]> + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.String + + + + + + + A pointer to a byte array. + The number of bytes to decode. + When overridden in a derived class, decodes a specified number of bytes starting at a specified address into a string. + A string that contains the results of decoding the specified sequence of bytes. + + method is designed to optimize performance when you have a native pointer to a byte array. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. + + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + + Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. + + ]]> + + + is a null pointer. + + is less than zero. + A fallback occurred (see Character Encoding in .NET) for a complete explanation) + + -and- + + is set to . + + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + 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. + When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a string. + A string that contains the results of decoding the specified sequence of bytes. + + or the provided by the method or the method, respectively, of a derived class. + + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + +## Examples + The following example reads a UTF-8 encoded string from a binary file that is represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring2.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetString/VB/getstring2.vb" id="Snippet3"::: + + The example uses the following text, which should be saved to a UTF-8 encoded file named Utf8Example.txt. + +```txt + +This is a UTF-8-encoded file that contains primarily Latin text, although it +does list the first twelve letters of the Russian (Cyrillic) alphabet: + +А б в г д е ё ж з и й к + +The goal is to save this file, then open and decode it as a binary stream. + +``` + + ]]> + + The byte array contains invalid Unicode code points. + + 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 . + + + + + + + + + + + + + + Property + + 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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.String + + + When overridden in a derived class, gets a name for the current encoding that can be used with mail agent header tags. + A name for the current to use with mail agent header tags. + + -or- + + An empty string (""), if the current cannot be used. + + method with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding. + + In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. + + Note that returns the name to use to describe an encoding. The property defines a different encoding that might work better for an email application, for example. However, use of the property to define the encoding is not recommended. + +## Examples + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + Gets a value indicating whether the current encoding is always normalized. + + + + + + + + + + Method + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Boolean + + + + Gets a value indicating whether the current encoding is always normalized, using the default normalization form. + + if the current is always normalized; otherwise, . The default is . + + , which uses full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. + + ]]> + + + + + + + + + + + + Method + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Boolean + + + + + + One of the values. + When overridden in a derived class, gets a value indicating whether the current encoding is always normalized, using the specified normalization form. + + if the current object is always normalized using the specified value; otherwise, . The default is . + + , which uses full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. + + ]]> + + + + + + + + + + + + Property + + 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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding can be used by browser clients for displaying content. + + if the current can be used by browser clients for displaying content; otherwise, . + + + + + + + + + + + + + + Property + + 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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding can be used by browser clients for saving content. + + if the current can be used by browser clients for saving content; otherwise, . + + + + + + + + + + + + + + Property + + 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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding can be used by mail and news clients for displaying content. + + if the current can be used by mail and news clients for displaying content; otherwise, . + + + + + + + + + + + + + + Property + + 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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding can be used by mail and news clients for saving content. + + if the current can be used by mail and news clients for saving content; otherwise, . + + + + + + + + + + + + + + Property + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding is read-only. + + if the current is read-only; otherwise, . The default is . + To be added. + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.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 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding uses single-byte code points. + + if the current uses single-byte code points; otherwise, . + + , this property retrieves `true`. + +> [!CAUTION] +> You should be careful in what your application does with the value for . An assumption of how an Encoding will proceed may still be wrong. For example, Windows-1252 has a value of `true` for , but Encoding.GetMaxByteCount(1) returns 2. This is because the method considers potential leftover surrogates from a previous decoder operation. + +## Examples + The following example checks the values of the Boolean properties of each encoding. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/CPP/isprops.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetEncodings/isprops.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/VB/isprops.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + Property + + System.Runtime + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + mscorlib + + + netstandard + + + System.Text.Encoding + + + Gets an encoding for the Latin1 character set (ISO-8859-1). + To be added. + To be added. + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + [get: System.Runtime.CompilerServices.NullableContext(0)] + [<get: System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.ReadOnlySpan<System.Byte> + + + When overridden in a derived class, returns a span containing the sequence of bytes that specifies the encoding used. + A byte span containing a sequence of bytes that specifies the encoding used, or a span of length zero, if a preamble is not required. + + object provides a preamble that is an sequence of bytes that can be prefixed to the bytes resulting from the encoding process. If the preamble contains a byte order mark (in Unicode, code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. + + The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): + +- UTF-8: EF BB BF + +- UTF-16 big endian byte order: FE FF + +- UTF-16 little endian byte order: FF FE + +- UTF-32 big endian byte order: 00 00 FE FF + +- UTF-32 little endian byte order: FF FE 00 00 + + You should use the BOM, because it provides nearly certain identification of an encoding for files that otherwise have lost reference to the object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged, preferably in UTF-8 or UTF-16. + + For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. + + There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. Despite the few disadvantages, however, the use of a BOM is highly recommended. + + For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://home.unicode.org/). + +> [!CAUTION] +> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, you should use a Unicode encoding, that is, , , or , with a preamble. + + ]]> + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + + System.Void + + + + + + A subclass of that provides access to additional character encodings. + Registers an encoding provider. + + method allows you to register a class derived from that makes character encodings available on a platform that does not otherwise support them. Once the encoding provider is registered, the encodings that it supports can be retrieved by calling any overload. If there are multiple encoding providers, the method attempts to retrieve a specified encoding from each provider starting with the one most recently registered. + +Registering an encoding provider by using the method also modifies the behavior of the [Encoding.GetEncoding(Int32)]() and [EncodingProvider.GetEncoding(Int32, EncoderFallback, DecoderFallback)](xref:System.Text.Encoding.GetEncoding(System.Int32,System.Text.EncoderFallback,System.Text.DecoderFallback)) methods when passed an argument of `0`: + +- If the registered provider is the , the method returns the encoding that matches the system active code page when running on the Windows operating system. + +- A custom encoding provider can choose which encoding to return when either of these method overloads is passed an argument of `0`. The provider can also choose to not return an encoding by having the method return `null`. + +Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, , that makes the encodings available that are present in the full .NET Framework but are not available in the Universal Windows Platform. By default, the Universal Windows Platform only supports the Unicode encodings, ASCII, and code page 28591. + + If the same encoding provider is used in multiple calls to the method, only the first method call registers the provider. Subsequent calls are ignored. + + If the method is called to register multiple providers that handle the same encoding, the last registered provider is the used for all encoding and decoding operations. Any previously registered providers are ignored. + + ]]> + + + is . + + + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Text.Encoding + + + mscorlib + + + netstandard + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Boolean + + + + + + + + The span containing the set of characters to encode. + The byte span to hold the encoded bytes. + Upon successful completion of the operation, the number of bytes encoded into . + Encodes into a span of bytes a set of characters from the specified read-only span if the destination is large enough. + + if all of the characters were encoded into the destination; if the destination was too small to contain all the encoded bytes. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Text.Encoding + + + mscorlib + + + netstandard + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Boolean + + + + + + + + A read-only span containing the sequence of bytes to decode. + The character span receiving the decoded bytes. + Upon successful completion of the operation, the number of chars decoded into . + Decodes into a span of chars a set of bytes from the specified read-only span if the destination is large enough. + + if all of the characters were decoded into the destination; if the destination was too small to contain all the decoded chars. + To be added. + + + + + + + + + + Property + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.Encoding + + + Gets an encoding for the UTF-16 format using the little endian byte order. + An encoding for the UTF-16 format using the little endian byte order. + + object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a little endian object whose fallback is either an or a , as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Unicode/unicode1.cs" interactive="try-dotnet" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.unicode/vb/unicode1.vb" id="Snippet2"::: + +## Examples + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + + ]]> + + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.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 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + Gets an encoding for the UTF-32 format using the little endian byte order. + An encoding object for the UTF-32 format using the little endian byte order. + + object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with the Unicode REPLACEMENT CHARACTER (U+FFFE). Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF32/encoding.utf32.1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf32/vb/encoding.utf32.1.vb" id="Snippet1"::: + + For a discussion of little endian byte order, see . + + For information about the encodings supported by .NET and a discussion of which Unicode encoding to use, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). + +## Examples + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + + ]]> + + + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.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}")>] + + + + System.Text.Encoding + + + Gets an encoding for the UTF-7 format. + An encoding for the UTF-7 format. + + + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.Encoding + + + Gets an encoding for the UTF-8 format. + An encoding for the UTF-8 format. + + object that encodes Unicode (UTF-16-encoded) characters into a sequence of one to four bytes per character, and that decodes a UTF-8-encoded byte array to Unicode (UTF-16-encoded) characters. For information about the character encodings supported by .NET and a discussion of which Unicode encoding to use, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). + + The object that is returned by this property might not have the appropriate behavior for your app. + +- It returns a object that provides a Unicode byte order mark (BOM). To instantiate a UTF8 encoding that doesn't provide a BOM, call any overload of the constructor. + +- It returns a object that uses replacement fallback to replace each string that it can't encode and each byte that it can't decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF8/encoding.utf8.1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf8/vb/encoding.utf8.1.vb" id="Snippet1"::: + +## Examples + The following example defines an array that consists of the following characters: + +- LATIN SMALL LETTER Z (U+007A) + +- LATIN SMALL LETTER A (U+0061) + +- COMBINING BREVE (U+0306) + +- LATIN SMALL LETTER AE WITH ACUTE (U+01FD) + +- GREEK SMALL LETTER BETA (U+03B2) + +- A surrogate pair (U+D800 U+DD54) that forms GREEK ACROPHONIC ATTIC ONE THOUSAND STATERS (U+10154). + + It displays the UTF-16 code units of each character and determines the number of bytes required by a UTF-8 encoder to encode the character array. It then encodes the characters and displays the resulting UTF-8-encoded bytes. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF8/example1.cs" interactive="try-dotnet" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf8/vb/example1.vb" id="Snippet2"::: + + ]]> + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.0.0 + 4.0.10.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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + [get: System.Security.SecuritySafeCritical] + [<get: System.Security.SecuritySafeCritical>] + + + + System.String + + + When overridden in a derived class, gets the name registered with the Internet Assigned Numbers Authority (IANA) for the current encoding. + The IANA name for the current . + + property is the same as the property. + + Note that returns an IANA-registered name for the encoding. When its value is the name of a standard, the implementation of the encoding might not conform in full to that standard. The property defines a different encoding that might work better for email headers. However, most apps should use instead. + + For more information on the IANA, go to [www.iana.org](https://www.iana.org/). + + The is the same as the returned by . Some of the web names are duplicates; see the remarks for for more information. + +## Examples + The following example includes the in an HTML header. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.WebName/CPP/webname.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/WebName/webname.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.WebName/VB/webname.vb" id="Snippet1"::: + + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + + + + + Property + + 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.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Int32 + + + When overridden in a derived class, gets the Windows operating system code page that most closely corresponds to the current encoding. + The Windows operating system code page that most closely corresponds to the current . + + instead of to identify the code page. + +## Examples + The following example determines the Windows code page that most closely corresponds to each encoding. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.CodePage/CPP/codepage.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/WindowsCodePage/codepage.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.CodePage/VB/codepage.vb" id="Snippet1"::: + + ]]> + + + + + + + diff --git a/xml/System.Text/Rune.xml b/xml/System.Text/Rune.xml index a5724c69ceb..6f616329a2b 100644 --- a/xml/System.Text/Rune.xml +++ b/xml/System.Text/Rune.xml @@ -1,2536 +1,2537 @@ - - - - - - - - - - - - - - - - - - - - - - - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.ValueType - - - - System.IComparable - - - System.IComparable<System.Text.Rune> - - - System.IEquatable<System.Text.Rune> - - - System.IFormattable - - - System.ISpanFormattable - - - System.IUtf8SpanFormattable - - - - - [System.Runtime.CompilerServices.IsReadOnly] - [<System.Runtime.CompilerServices.IsReadOnly>] - - - - Represents a Unicode scalar value ([ U+0000..U+D7FF ], inclusive; or [ U+E000..U+10FFFF ], inclusive). - - instance represents a Unicode scalar value, which means any code point excluding the surrogate range (U+D800..U+DFFF). The type's constructors and conversion operators validate the input, so consumers can call the APIs assuming that the underlying instance is well formed. - -If you aren't familiar with the terms Unicode scalar value, code point, surrogate range, and well-formed, see [Introduction to character encoding in .NET](/dotnet/standard/base-types/character-encoding-introduction). - -The following sections explain: - -* [When to use the Rune type](#when-to-use-the-rune-type) -* [When not to use the Rune type](#when-not-to-use-rune) -* [How to instantiate a Rune](#how-to-instantiate-a-rune) -* [How to query properties of a Rune instance](#query-properties-of-a-rune) -* [Convert a `Rune` to UTF-8 or UTF-16](#convert-a-rune-to-utf-8-or-utf-16) -* [Rune in .NET vs. other languages](#rune-in-net-vs-other-languages) - -### When to use the Rune type - -Consider using the `Rune` type if your code: - -* Calls APIs that require Unicode scalar values -* Explicitly handles surrogate pairs - -#### APIs that require Unicode scalar values - -If your code iterates through the `char` instances in a `string` or a `ReadOnlySpan`, some of the `char` methods won't work correctly on `char` instances that are in the surrogate range. For example, the following APIs require a scalar value `char` to work correctly: - -* -* -* -* -* -* -* -* -* -* - -The following example shows code that won't work correctly if any of the `char` instances are surrogate code points: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInString.cs" id="SnippetBadExample"::: -:::code language="fsharp" source="~/snippets/fsharp/System.Text/Rune/Overview/CountLettersInString.fs" id="SnippetBadExample"::: - -Here's equivalent code that works with a `ReadOnlySpan`: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInSpan.cs" id="SnippetBadExample"::: - -The preceding code works correctly with some languages such as English: - -```csharp -CountLettersInString("Hello") -// Returns 5 -``` - -But it won't work correctly for languages outside the Basic Multilingual Plane, such as Osage: - -```csharp -CountLettersInString("𐓏𐓘𐓻𐓘𐓻𐓟 𐒻𐓟") -// Returns 0 -``` - -The reason this method returns incorrect results for Osage text is that the `char` instances for Osage letters are surrogate code points. No single surrogate code point has enough information to determine if it's a letter. - -If you change this code to use `Rune` instead of `char`, the method works correctly with code points outside the Basic Multilingual Plane: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInString.cs" id="SnippetGoodExample"::: -:::code language="fsharp" source="~/snippets/fsharp/System.Text/Rune/Overview/CountLettersInString.fs" id="SnippetGoodExample"::: - -Here's equivalent code that works with a `ReadOnlySpan`: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInSpan.cs" id="SnippetGoodExample"::: - -The preceding code counts Osage letters correctly: - -```csharp -CountLettersInString("𐓏𐓘𐓻𐓘𐓻𐓟 𐒻𐓟") -// Returns 8 -``` - -#### Code that explicitly handles surrogate pairs - -Consider using the `Rune` type if your code calls APIs that explicitly operate on surrogate code points, such as the following methods: - -* -* -* -* -* -* - -For example, the following method has special logic to deal with surrogate `char` pairs: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/WorkWithSurrogates.cs" id="SnippetUseChar"::: - -Such code is simpler if it uses `Rune`, as in the following example: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/WorkWithSurrogates.cs" id="SnippetUseRune"::: - -### When not to use `Rune` - -You don't need to use the `Rune` type if your code: - -* Looks for exact `char` matches -* Splits a string on a known char value - -Using the `Rune` type may return incorrect results if your code: - -* Counts the number of display characters in a `string` - -#### Look for exact `char` matches - -The following code iterates through a `string` looking for specific characters, returning the index of the first match. There's no need to change this code to use `Rune`, as the code is looking for characters that are represented by a single `char`. - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/FindFirstLetter.cs" id="SnippetExample"::: - -#### Split a string on a known `char` - -It's common to call `string.Split` and use delimiters such as `' '` (space) or `','` (comma), as in the following example: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/SplitStringOnChar.cs" id="SnippetExample"::: - -There is no need to use `Rune` here, because the code is looking for characters that are represented by a single `char`. - -#### Count the number of display characters in a `string` - -The number of `Rune` instances in a string might not match the number of user-perceivable characters shown when displaying the string. - -Since `Rune` instances represent Unicode scalar values, components that follow the [Unicode text segmentation guidelines](https://www.unicode.org/reports/tr29/) can use `Rune` as a building block for counting display characters. - -The type can be used to count display characters, but it doesn't count correctly in all scenarios for .NET implementations other than .NET 5+. - -For more information, see [Grapheme clusters](/dotnet/standard/base-types/character-encoding-introduction#grapheme-clusters). - -### How to instantiate a `Rune` - -There are several ways to get a `Rune` instance. You can use a constructor to create a `Rune` directly from: - -* A code point. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetCodePoint"::: - -* A single `char`. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetChar"::: - -* A surrogate `char` pair. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetSurrogate"::: - -All of the constructors throw an `ArgumentException` if the input doesn't represent a valid Unicode scalar value. - -There are methods available for callers who don't want exceptions to be thrown on failure. - -`Rune` instances can also be read from existing input sequences. For instance, given a `ReadOnlySpan` that represents UTF-16 data, the method returns the first `Rune` instance at the beginning of the input span. The method operates similarly, accepting a `ReadOnlySpan` parameter that represents UTF-8 data. There are equivalent methods to read from the end of the span instead of the beginning of the span. - -### Query properties of a `Rune` - -To get the integer code point value of a `Rune` instance, use the property. - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetValue"::: - -Many of the static APIs available on the `char` type are also available on the `Rune` type. For instance, and are equivalents to and methods. The `Rune` methods correctly handle surrogate pairs. - -The following example code takes a `ReadOnlySpan` as input and trims from both the start and the end of the span every `Rune` that isn't a letter or a digit. - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/TrimNonLettersAndNonDigits.cs" id="SnippetExample"::: - -There are some API differences between `char` and `Rune`. For example: - -* There is no `Rune` equivalent to , since `Rune` instances by definition can never be surrogate code points. -* The doesn't always return the same result as . It does return the same value as . For more information, see the **Remarks** on . - -### Convert a `Rune` to UTF-8 or UTF-16 - -Since a `Rune` is a Unicode scalar value, it can be converted to UTF-8, UTF-16, or UTF-32 encoding. The `Rune` type has built-in support for conversion to UTF-8 and UTF-16. - -The converts a `Rune` instance to `char` instances. To query the number of `char` instances that would result from converting a `Rune` instance to UTF-16, use the property. Similar methods exist for UTF-8 conversion. - -The following example converts a `Rune` instance to a `char` array. The code assumes you have a `Rune` instance in the `rune` variable: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/EncodeRune.cs" id="SnippetUtf16CharArray"::: - -Since a `string` is a sequence of UTF-16 chars, the following example also converts a `Rune` instance to UTF-16: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/EncodeRune.cs" id="SnippetUtf16String"::: - -The following example converts a `Rune` instance to a `UTF-8` byte array: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/EncodeRune.cs" id="SnippetUtf8ByteArray"::: - -The and methods return the actual number of elements written. They throw an exception if the destination buffer is too short to contain the result. There are non-throwing and methods as well for callers who want to avoid exceptions. - -### Rune in .NET vs. other languages - -The term "rune" is not defined in the Unicode Standard. The term dates back to [the creation of UTF-8](https://www.cl.cam.ac.uk/~mgk25/ucs/utf-8-history.txt). Rob Pike and Ken Thompson were looking for a term to describe what would eventually become known as a code point. [They settled on the term "rune"](https://twitter.com/rob_pike/status/732353233474064384), and Rob Pike's later influence over the Go programming language helped popularize the term. - -However, the .NET `Rune` type is not the equivalent of the Go `rune` type. In Go, the `rune` type is an [alias for `int32`](https://blog.golang.org/strings). A Go rune is intended to represent a Unicode code point, but it can be any 32-bit value, including surrogate code points and values that are not legal Unicode code points. - -For similar types in other programming languages, see [Rust's primitive `char` type](https://doc.rust-lang.org/std/primitive.char.html) or [Swift's `Unicode.Scalar` type](https://developer.apple.com/documentation/swift/unicode/scalar), both of which represent Unicode scalar values. They provide functionality similar to .NET's `Rune` type, and they disallow instantiation of values that are not legal Unicode scalar values. - - ]]> - - - - - - - - - - - Constructor - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - A UTF-16 code unit. - Creates a from the provided UTF-16 code unit. - To be added. - - represents a UTF-16 surrogate code point (U+D800..U+DFFF, inclusive). - - - - - - - - - - Constructor - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - A Unicode scalar value. - Creates a from the specified 32-bit integer that represents a Unicode scalar value. - To be added. - - does not represent a Unicode scalar value. - - - - - - - - - - Constructor - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - - - - A Unicode scalar value. - Creates a from the specified 32-bit unsigned integer that represents a Unicode scalar value. - To be added. - - does not represent a Unicode scalar value. - - - - - - - - - - Constructor - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - - The high surrogate of the surrogate pair. - The low surrogate of the surrogate pair. - Creates a from the provided UTF-16 surrogate pair. - To be added. - - does not represent a UTF-16 high surrogate code point. - --or- - - does not represent a UTF-16 low surrogate code point. - - - - - - - - - - Method - - M:System.IComparable`1.CompareTo(`0) - - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The instance to compare with the current instance. - Compares the current instance to the specified instance. - A signed integer indicating the position of this instance in the sort order in relation to :
- Less than zero: This instance precedes . -
- Zero: The instance has the same position in the sort order as . -
- Greater than zero: This instance follows . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - A read-only UTF-16 character span. - When this method returns, the decoded rune. - When this method returns, the number of characters read to create the rune. - Decodes the at the beginning of the provided UTF-16 source buffer. - - if the source buffer begins with a valid UTF-16 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . - - if the source buffer is empty or contains only a standalone UTF-16 high surrogate character. then contains , and contains the length of the input buffer. - - if the source buffer begins with an ill-formed UTF-16 encoded scalar value. then contains , and contains the number of values used to encode the ill-formed sequence. - . - - if the data was not successfully decoded. This pattern provides convenient automatic U+FFFD substitution of invalid sequences while iterating through the loop. - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - A read-only UTF-8 encoded byte span. - When this method returns, the decoded rune. - When this method returns, the number of bytes read to create the rune. - Decodes the at the beginning of the provided UTF-8 source buffer. - - if the source buffer begins with a valid UTF-8 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . - - if the source buffer is empty or contains only a standalone UTF-8 high surrogate character. then contains , and contains the length of the input buffer. - - if the source buffer begins with an ill-formed UTF-8 encoded scalar value. then contains , and contains the number of values used in the input buffer to encode the ill-formed sequence. - . - - if the data could not be successfully decoded. This pattern provides convenient automatic U+FFFD substitution of invalid sequences while iterating through the loop. - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - A read-only UTF-16 encoded character span. - When this method returns, the decoded rune. - When this method returns, the number of bytes read to create the rune. - Decodes the at the end of the provided UTF-16 source buffer. - - if the source buffer begins with a valid UTF-16 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . - - if the source buffer is empty or contains only a standalone UTF-16 high surrogate character. then contains , and contains the length of the input buffer. - - if the source buffer begins with an ill-formed UTF-16 encoded scalar value. then contains , and contains the number of values used to encode the ill-formed sequence. - . - - , except it allows the caller to loop backward instead of forward. The typical calling convention is that on each iteration of the loop, the caller should slice off the final `charsConsumed` elements of the `source` buffer. - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - A read-only UTF-8 encoded byte span. - When this method returns, the decoded rune. - When this method returns, the number of bytes read to create the rune. - Decodes the at the end of the provided UTF-8 source buffer. - - if the source buffer ends with a valid UTF-8 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . - - if the source buffer is empty or contains only a standalone UTF-8 high surrogate character. then contains , and contains the length of the input buffer. - - if the source buffer ends with an ill-formed UTF-8 encoded scalar value. then contains , and contains the number of values used in the input buffer to encode the ill-formed sequence. - - - , except it allows the caller to loop backward instead of forward. The typical calling convention is that on each iteration of the loop, the caller should slice off the final `bytesConsumed` elements of the `source` buffer. - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The buffer to which to write this value as UTF-16. - Encodes this to a UTF-16 destination buffer. - The number of values written to . - To be added. - - is not large enough to hold the output. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The buffer to which to write this value as UTF-8. - Encodes this to a UTF-8 destination buffer. - The number of values written to . - To be added. - - is not large enough to hold the output. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Boolean - - - - - - [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] - [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] - - - - - - The object to compare with the current instance. - Returns a value that indicates whether the current instance and a specified object are equal. - - if is of type and is equal to the current instance; otherwise, . - To be added. - - - - - - - - - - Method - - M:System.IEquatable`1.Equals(`0) - - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The object to compare with the current instance. - Returns a value that indicates whether the current instance and a specified rune are equal. - - if the current instance and are equal; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - Returns the hash code for this instance. - The hash code for this instance. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Double - - - - - - The rune for which to get the numeric value. - Gets the numeric value associated with the specified rune. - The numeric value associated with , or -1 if doesn't represent a numeric character. - - . Refer to that documentation for more information. - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Text.Rune - - - - - - - The string from which to create the rune. - The starting position in at which to create the rune. - Gets the that begins at a specified position in a string. - The rune obtained from at the specified . - - - - - is . - - does not reference the start of a valid scalar value in . - - is outside the range of . - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Globalization.UnicodeCategory - - - - - - The rune for which to get the Unicode category. - Gets the Unicode category associated with the specified rune. - The Unicode category associated with . - - . Refer to that documentation for more information. - - ]]> - - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - Gets a value that indicates whether the scalar value associated with this is within the ASCII encoding range. - - if the scalar value associated is within the ASCII encoding range ([ U+0000..U+007F ]) and therefore representable by a single UTF-8 code unit; otherwise, . - To be added. - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - Gets a value that indicates whether the scalar value associated with this is within the BMP encoding range. - - if the scalar value associated is within the BMP encoding range ([ U+0000..U+FFFF ]) and therefore representable by a single UTF-16 code unit; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a control character. - - if is a control character; otherwise, . - - and comparing the result against . - -Per [Unicode stability policies](https://www.unicode.org/policies/stability_policy.html), the set of control characters is permanently fixed to be the union of `[ U+0000..U+001F ]` and `[ U+007F..U+009F ]`. - -For more information, see . - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a decimal digit. - - if is a decimal digit; otherwise, . - - and comparing the result against . - -For more information, see . - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a letter. - - if is a letter; otherwise, . - - and comparing the result against any of the values , , , , and . - -For more information, see . - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a letter or a decimal digit. - - if is a letter or a decimal digit; otherwise, . - - and comparing the result against any of the values , , , , , and . - -For more information, see . - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a lowercase letter. - - if is a lowercase letter; otherwise, . - - -and comparing the result against . - -For more information, see . - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a number. - - if is a number; otherwise, . - - and comparing the result against any of the values , , and . - -For more information, see . - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a punctuation mark. - - if is a punctuation mark; otherwise, . - - and comparing the result against any of the values , , , , , , and . - -For more information, see . - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a separator character. - - if is a separator character; otherwise, . - - and comparing the result against any of the values , , and . - -For more information, see . - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a symbol character. - - if is a symbol character; otherwise, . - - and comparing the result against any of the values , , , and . - -For more information, see . - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as an uppercase letter. - - if is an uppercase letter; otherwise,. - - and comparing the result against . - -For more information, see . - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The Unicode scalar value. - Returns a value that indicates whether a 32-bit signed integer represents a valid Unicode scalar value; that is, it is in the range [ U+0000..U+D7FF ], inclusive; or [ U+E000..U+10FFFF ], inclusive. - - if is a valid Unicode scalar value; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Boolean - - - - - - The Unicode scalar value. - Returns a value that indicates whether a 32-bit unsigned integer represents a valid Unicode scalar value; that is, it is in the range [ U+0000..U+D7FF ], inclusive, or [ U+E000..U+10FFFF ], inclusive. - - if is a valid Unicode scalar value; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a white space character. - - if is a white space character; otherwise, . - - and comparing the result against any of the values , , and . However, there are some s in the category which are also classified as white space characters, and this method accounts for those values. - -For more information, see . - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - The second value to compare. - Returns a value that indicates whether two instances are equal. - - if and are equal; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Rune - - - - - - The 16-bit Unicode character to convert. - Defines an explicit conversion of a 16-bit Unicode character to a . - - as a 32-bit Unicode character. - To be added. - - is a Unicode scalar that represents a surrogate code point. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Rune - - - - - - The 32-bit signed integer to convert. - Defines an explicit conversion of a 32-bit signed integer to a . - - as a 32-bit Unicode character. - To be added. - - is an invalid Unicode scalar. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.Rune - - - - - - The 32-bit signed integer to convert. - Defines an explicit conversion of a 32-bit unsigned integer to a . - - as a 32-bit Unicode character. - To be added. - - is an invalid Unicode scalar. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - The second value to compare. - Returns a value indicating whether a specified is greater than another specified . - - if is greater than ; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - The second value to compare. - Returns a value indicating whether a specified is greater than or equal to another specified . - - if is greater than or equal to ; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - The second value to compare. - Returns a value that indicates whether two instances have different values. - - if and are not equal; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - the second value to compare. - Returns a value indicating whether a specified is less than another specified . - - if is less than ; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - The second value to compare. - Returns a value indicating whether a specified is less than or equal to another specified . - - if is less than or equal to ; otherwise, . - To be added. - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - Gets the Unicode plane (0 to 16, inclusive) that contains this scalar. - The Unicode plane (0 to 16, inclusive) that contains this scalar. - To be added. - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Rune - - - Gets a instance that represents the Unicode replacement character U+FFFD. - A instance that represents the Unicode replacement character U+FFFD. - To be added. - - - - - - - - - - Method - - M:System.IComparable.CompareTo(System.Object) - - - System.Runtime - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The object to compare with the current instance. - Compares the current instance to the specified object. - A signed integer indicating the position of this instance in the sort order in relation to :
- Less than zero: This instance precedes . -
- Zero: The instance has the same position in the sort order as . -
- Greater than zero: This instance follows . - - instance is cast to an interface. - - ]]> - - - - - - - - - - - - Method - - M:System.IFormattable.ToString(System.String,System.IFormatProvider) - - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.String - - - - - - - The format to use. - -or- - ( in Visual Basic) to use the default format defined for the type of the implementation. - The provider to use to format the value. - -or- - ( in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system. - Formats the value of the current instance using the specified format. - The value of the current instance in the specified format. - To be added. - - - - - - - - - - Method - - M:System.ISpanFormattable.TryFormat(System.Span{System.Char},System.Int32@,System.ReadOnlySpan{System.Char},System.IFormatProvider) - - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - - - When this method returns, contains this instance's value formatted as a span of characters. - When this method returns, contains the number of characters that were written in . - A span containing the characters that represent a standard or custom format string that defines the acceptable format for . - An optional object that supplies culture-specific formatting information for . - Tries to format the value of the current instance into the provided span of characters. - - if the formatting was successful; otherwise, . - To be added. - - - - - - - - - - Method - - M:System.IUtf8SpanFormattable.TryFormat(System.Span{System.Byte},System.Int32@,System.ReadOnlySpan{System.Char},System.IFormatProvider) - - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Text.Rune - - - - - - - The 32-bit Unicode character to convert. - An object that supplies culture-specific casing rules. - Returns a copy of the specified converted to lowercase, using the casing rules of the specified culture. - The lowercase equivalent of . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Rune - - - - - - The 32-bit Unicode character to convert. - Returns a copy of the specified converted to lowercase using the casing rules of the invariant culture. - The lowercase equivalent of . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.String - - - - Returns the string representation of this instance. - The string representation of this rune. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Text.Rune - - - - - - - The 32-bit Unicode character to convert. - An object that supplies culture-specific casing rules. - Returns a copy of the specified converted to uppercase, using the casing rules of the specified culture. - The uppercase equivalent of . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Rune - - - - - - The 32-bit Unicode character to convert. - Returns a copy of the specified converted to uppercase using the casing rules of the invariant culture. - The uppercase equivalent of . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The character from which to create the rune. - When this method returns, the rune that corresponds to . - Attempts to create a from a specified character and returns a value that indicates whether the operation succeeded. - - if the method succeeded; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The Unicode scalar value. - When this method returns, the rune that corresponds to . - Attempts to create a from a specified signed integer that represents a Unicode scalar value. - - if the method succeeded; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Boolean - - - - - - - The Unicode scalar value. - When this method returns, the rune that corresponds to . - Attempts to create a from the specified 32-bit unsigned integer that represents a Unicode scalar value. - - if the method succeeded; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - - The high surrogate of the surrogate pair. - The low surrogate of the surrogate pair. - The rune that corresponds to the specified surrogate pair. - Attempts to create a from the specified UTF-16 surrogate pair and returns a value that indicates whether the operation was successful. - - if the operation succeeded; if the input values don't represent a well-formed UTF-16 surrogate pair. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The buffer to which to write this value as UTF-16 encoded value. - The number of values written to , or 0 if the destination buffer is not large enough to contain the output. - Encodes this to a UTF-16 encoded destination buffer. - - if the value was written to the buffer; otherwise, . - - property can be queried ahead of time to determine the required size of the `destination` buffer. - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The buffer to which to write the UTF-8 encoded value. - The number of values written to , or 0 if the destination buffer is not large enough to contain the output. - Encodes this to a UTF-8 encoded destination buffer. - - if the value was written to the buffer; otherwise, . - - property can be queried ahead of time to determine the required size of the `destination` buffer. - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Boolean - - - - - - - - The string from which to extract the rune. - The zero-based index from which to extract the rune. - When this method returns, the decoded rune. - Attempts to get the that begins at a specified position in a string, and return a value that indicates whether the operation succeeded. - - if a scalar value was successfully extracted from the specified index; if a value could not be extracted because of invalid data. - - - - - is . - - is out of the range of . - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - Gets the length in code units () of the UTF-16 sequence required to represent this scalar value. - The length in code units () of the UTF-16 sequence required to represent this scalar value. - - - - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - Gets the length in code units of the UTF-8 sequence required to represent this scalar value. - The length in code units of the UTF-8 sequence required to represent this scalar value. - - - - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - Gets the Unicode scalar value as an integer. - The Unicode scalar value as an integer. - To be added. - - - - + + + + + + + + + + + + + + + + + + + + + + + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.ValueType + + + + System.IComparable + + + System.IComparable<System.Text.Rune> + + + System.IEquatable<System.Text.Rune> + + + System.IFormattable + + + System.ISpanFormattable + + + System.IUtf8SpanFormattable + + + + + [System.Runtime.CompilerServices.IsReadOnly] + [<System.Runtime.CompilerServices.IsReadOnly>] + + + + Represents a Unicode scalar value ([ U+0000..U+D7FF ], inclusive; or [ U+E000..U+10FFFF ], inclusive). + + instance represents a Unicode scalar value, which means any code point excluding the surrogate range (U+D800..U+DFFF). The type's constructors and conversion operators validate the input, so consumers can call the APIs assuming that the underlying instance is well formed. + +If you aren't familiar with the terms Unicode scalar value, code point, surrogate range, and well-formed, see [Introduction to character encoding in .NET](/dotnet/standard/base-types/character-encoding-introduction). + +The following sections explain: + +* [When to use the Rune type](#when-to-use-the-rune-type) +* [When not to use the Rune type](#when-not-to-use-rune) +* [How to instantiate a Rune](#how-to-instantiate-a-rune) +* [How to query properties of a Rune instance](#query-properties-of-a-rune) +* [Convert a `Rune` to UTF-8 or UTF-16](#convert-a-rune-to-utf-8-or-utf-16) +* [Rune in .NET vs. other languages](#rune-in-net-vs-other-languages) + +### When to use the Rune type + +Consider using the `Rune` type if your code: + +* Calls APIs that require Unicode scalar values +* Explicitly handles surrogate pairs + +#### APIs that require Unicode scalar values + +If your code iterates through the `char` instances in a `string` or a `ReadOnlySpan`, some of the `char` methods won't work correctly on `char` instances that are in the surrogate range. For example, the following APIs require a scalar value `char` to work correctly: + +* +* +* +* +* +* +* +* +* +* + +The following example shows code that won't work correctly if any of the `char` instances are surrogate code points: + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInString.cs" id="SnippetBadExample"::: +:::code language="fsharp" source="~/snippets/fsharp/System.Text/Rune/Overview/CountLettersInString.fs" id="SnippetBadExample"::: + +Here's equivalent code that works with a `ReadOnlySpan`: + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInSpan.cs" id="SnippetBadExample"::: + +The preceding code works correctly with some languages such as English: + +```csharp +CountLettersInString("Hello") +// Returns 5 +``` + +But it won't work correctly for languages outside the Basic Multilingual Plane, such as Osage: + +```csharp +CountLettersInString("𐓏𐓘𐓻𐓘𐓻𐓟 𐒻𐓟") +// Returns 0 +``` + +The reason this method returns incorrect results for Osage text is that the `char` instances for Osage letters are surrogate code points. No single surrogate code point has enough information to determine if it's a letter. + +If you change this code to use `Rune` instead of `char`, the method works correctly with code points outside the Basic Multilingual Plane: + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInString.cs" id="SnippetGoodExample"::: +:::code language="fsharp" source="~/snippets/fsharp/System.Text/Rune/Overview/CountLettersInString.fs" id="SnippetGoodExample"::: + +Here's equivalent code that works with a `ReadOnlySpan`: + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInSpan.cs" id="SnippetGoodExample"::: + +The preceding code counts Osage letters correctly: + +```csharp +CountLettersInString("𐓏𐓘𐓻𐓘𐓻𐓟 𐒻𐓟") +// Returns 8 +``` + +#### Code that explicitly handles surrogate pairs + +Consider using the `Rune` type if your code calls APIs that explicitly operate on surrogate code points, such as the following methods: + +* +* +* +* +* +* + +For example, the following method has special logic to deal with surrogate `char` pairs: + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/WorkWithSurrogates.cs" id="SnippetUseChar"::: + +Such code is simpler if it uses `Rune`, as in the following example: + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/WorkWithSurrogates.cs" id="SnippetUseRune"::: + +### When not to use `Rune` + +You don't need to use the `Rune` type if your code: + +* Looks for exact `char` matches +* Splits a string on a known char value + +Using the `Rune` type may return incorrect results if your code: + +* Counts the number of display characters in a `string` + +#### Look for exact `char` matches + +The following code iterates through a `string` looking for specific characters, returning the index of the first match. There's no need to change this code to use `Rune`, as the code is looking for characters that are represented by a single `char`. + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/FindFirstLetter.cs" id="SnippetExample"::: + +#### Split a string on a known `char` + +It's common to call `string.Split` and use delimiters such as `' '` (space) or `','` (comma), as in the following example: + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/SplitStringOnChar.cs" id="SnippetExample"::: + +There is no need to use `Rune` here, because the code is looking for characters that are represented by a single `char`. + +#### Count the number of display characters in a `string` + +The number of `Rune` instances in a string might not match the number of user-perceivable characters shown when displaying the string. + +Since `Rune` instances represent Unicode scalar values, components that follow the [Unicode text segmentation guidelines](https://www.unicode.org/reports/tr29/) can use `Rune` as a building block for counting display characters. + +The type can be used to count display characters, but it doesn't count correctly in all scenarios for .NET implementations other than .NET 5+. + +For more information, see [Grapheme clusters](/dotnet/standard/base-types/character-encoding-introduction#grapheme-clusters). + +### How to instantiate a `Rune` + +There are several ways to get a `Rune` instance. You can use a constructor to create a `Rune` directly from: + +* A code point. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetCodePoint"::: + +* A single `char`. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetChar"::: + +* A surrogate `char` pair. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetSurrogate"::: + +All of the constructors throw an `ArgumentException` if the input doesn't represent a valid Unicode scalar value. + +There are methods available for callers who don't want exceptions to be thrown on failure. + +`Rune` instances can also be read from existing input sequences. For instance, given a `ReadOnlySpan` that represents UTF-16 data, the method returns the first `Rune` instance at the beginning of the input span. The method operates similarly, accepting a `ReadOnlySpan` parameter that represents UTF-8 data. There are equivalent methods to read from the end of the span instead of the beginning of the span. + +### Query properties of a `Rune` + +To get the integer code point value of a `Rune` instance, use the property. + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetValue"::: + +Many of the static APIs available on the `char` type are also available on the `Rune` type. For instance, and are equivalents to and methods. The `Rune` methods correctly handle surrogate pairs. + +The following example code takes a `ReadOnlySpan` as input and trims from both the start and the end of the span every `Rune` that isn't a letter or a digit. + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/TrimNonLettersAndNonDigits.cs" id="SnippetExample"::: + +There are some API differences between `char` and `Rune`. For example: + +* There is no `Rune` equivalent to , since `Rune` instances by definition can never be surrogate code points. +* The doesn't always return the same result as . It does return the same value as . For more information, see the **Remarks** on . + +### Convert a `Rune` to UTF-8 or UTF-16 + +Since a `Rune` is a Unicode scalar value, it can be converted to UTF-8, UTF-16, or UTF-32 encoding. The `Rune` type has built-in support for conversion to UTF-8 and UTF-16. + +The converts a `Rune` instance to `char` instances. To query the number of `char` instances that would result from converting a `Rune` instance to UTF-16, use the property. Similar methods exist for UTF-8 conversion. + +The following example converts a `Rune` instance to a `char` array. The code assumes you have a `Rune` instance in the `rune` variable: + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/EncodeRune.cs" id="SnippetUtf16CharArray"::: + +Since a `string` is a sequence of UTF-16 chars, the following example also converts a `Rune` instance to UTF-16: + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/EncodeRune.cs" id="SnippetUtf16String"::: + +The following example converts a `Rune` instance to a `UTF-8` byte array: + +:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/EncodeRune.cs" id="SnippetUtf8ByteArray"::: + +The and methods return the actual number of elements written. They throw an exception if the destination buffer is too short to contain the result. There are non-throwing and methods as well for callers who want to avoid exceptions. + +### Rune in .NET vs. other languages + +The term "rune" is not defined in the Unicode Standard. The term dates back to [the creation of UTF-8](https://www.cl.cam.ac.uk/~mgk25/ucs/utf-8-history.txt). Rob Pike and Ken Thompson were looking for a term to describe what would eventually become known as a code point. [They settled on the term "rune"](https://twitter.com/rob_pike/status/732353233474064384), and Rob Pike's later influence over the Go programming language helped popularize the term. + +However, the .NET `Rune` type is not the equivalent of the Go `rune` type. In Go, the `rune` type is an [alias for `int32`](https://blog.golang.org/strings). A Go rune is intended to represent a Unicode code point, but it can be any 32-bit value, including surrogate code points and values that are not legal Unicode code points. + +For similar types in other programming languages, see [Rust's primitive `char` type](https://doc.rust-lang.org/std/primitive.char.html) or [Swift's `Unicode.Scalar` type](https://developer.apple.com/documentation/swift/unicode/scalar), both of which represent Unicode scalar values. They provide functionality similar to .NET's `Rune` type, and they disallow instantiation of values that are not legal Unicode scalar values. + + ]]> + + + + + + + + + + + Constructor + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + A UTF-16 code unit. + Creates a from the provided UTF-16 code unit. + To be added. + + represents a UTF-16 surrogate code point (U+D800..U+DFFF, inclusive). + + + + + + + + + + Constructor + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + A Unicode scalar value. + Creates a from the specified 32-bit integer that represents a Unicode scalar value. + To be added. + + does not represent a Unicode scalar value. + + + + + + + + + + Constructor + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + + + + A Unicode scalar value. + Creates a from the specified 32-bit unsigned integer that represents a Unicode scalar value. + To be added. + + does not represent a Unicode scalar value. + + + + + + + + + + Constructor + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + + The high surrogate of the surrogate pair. + The low surrogate of the surrogate pair. + Creates a from the provided UTF-16 surrogate pair. + To be added. + + does not represent a UTF-16 high surrogate code point. + +-or- + + does not represent a UTF-16 low surrogate code point. + + + + + + + + + + Method + + M:System.IComparable`1.CompareTo(`0) + + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The instance to compare with the current instance. + Compares the current instance to the specified instance. + A signed integer indicating the position of this instance in the sort order in relation to :
- Less than zero: This instance precedes . +
- Zero: The instance has the same position in the sort order as . +
- Greater than zero: This instance follows . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + A read-only UTF-16 character span. + When this method returns, the decoded rune. + When this method returns, the number of characters read to create the rune. + Decodes the at the beginning of the provided UTF-16 source buffer. + + if the source buffer begins with a valid UTF-16 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . + + if the source buffer is empty or contains only a standalone UTF-16 high surrogate character. then contains , and contains the length of the input buffer. + + if the source buffer begins with an ill-formed UTF-16 encoded scalar value. then contains , and contains the number of values used to encode the ill-formed sequence. + . + + if the data was not successfully decoded. This pattern provides convenient automatic U+FFFD substitution of invalid sequences while iterating through the loop. + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + A read-only UTF-8 encoded byte span. + When this method returns, the decoded rune. + When this method returns, the number of bytes read to create the rune. + Decodes the at the beginning of the provided UTF-8 source buffer. + + if the source buffer begins with a valid UTF-8 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . + + if the source buffer is empty or contains only a standalone UTF-8 high surrogate character. then contains , and contains the length of the input buffer. + + if the source buffer begins with an ill-formed UTF-8 encoded scalar value. then contains , and contains the number of values used in the input buffer to encode the ill-formed sequence. + . + + if the data could not be successfully decoded. This pattern provides convenient automatic U+FFFD substitution of invalid sequences while iterating through the loop. + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + A read-only UTF-16 encoded character span. + When this method returns, the decoded rune. + When this method returns, the number of bytes read to create the rune. + Decodes the at the end of the provided UTF-16 source buffer. + + if the source buffer begins with a valid UTF-16 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . + + if the source buffer is empty or contains only a standalone UTF-16 high surrogate character. then contains , and contains the length of the input buffer. + + if the source buffer begins with an ill-formed UTF-16 encoded scalar value. then contains , and contains the number of values used to encode the ill-formed sequence. + . + + , except it allows the caller to loop backward instead of forward. The typical calling convention is that on each iteration of the loop, the caller should slice off the final `charsConsumed` elements of the `source` buffer. + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + A read-only UTF-8 encoded byte span. + When this method returns, the decoded rune. + When this method returns, the number of bytes read to create the rune. + Decodes the at the end of the provided UTF-8 source buffer. + + if the source buffer ends with a valid UTF-8 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . + + if the source buffer is empty or contains only a standalone UTF-8 high surrogate character. then contains , and contains the length of the input buffer. + + if the source buffer ends with an ill-formed UTF-8 encoded scalar value. then contains , and contains the number of values used in the input buffer to encode the ill-formed sequence. + + + , except it allows the caller to loop backward instead of forward. The typical calling convention is that on each iteration of the loop, the caller should slice off the final `bytesConsumed` elements of the `source` buffer. + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The buffer to which to write this value as UTF-16. + Encodes this to a UTF-16 destination buffer. + The number of values written to . + To be added. + + is not large enough to hold the output. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The buffer to which to write this value as UTF-8. + Encodes this to a UTF-8 destination buffer. + The number of values written to . + To be added. + + is not large enough to hold the output. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Boolean + + + + + + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] + [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] + + + + + + The object to compare with the current instance. + Returns a value that indicates whether the current instance and a specified object are equal. + + if is of type and is equal to the current instance; otherwise, . + To be added. + + + + + + + + + + Method + + M:System.IEquatable`1.Equals(`0) + + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The object to compare with the current instance. + Returns a value that indicates whether the current instance and a specified rune are equal. + + if the current instance and are equal; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + Returns the hash code for this instance. + The hash code for this instance. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Double + + + + + + The rune for which to get the numeric value. + Gets the numeric value associated with the specified rune. + The numeric value associated with , or -1 if doesn't represent a numeric character. + + . Refer to that documentation for more information. + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Text.Rune + + + + + + + The string from which to create the rune. + The starting position in at which to create the rune. + Gets the that begins at a specified position in a string. + The rune obtained from at the specified . + + + + + is . + + does not reference the start of a valid scalar value in . + + is outside the range of . + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Globalization.UnicodeCategory + + + + + + The rune for which to get the Unicode category. + Gets the Unicode category associated with the specified rune. + The Unicode category associated with . + + . Refer to that documentation for more information. + + ]]> + + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + Gets a value that indicates whether the scalar value associated with this is within the ASCII encoding range. + + if the scalar value associated is within the ASCII encoding range ([ U+0000..U+007F ]) and therefore representable by a single UTF-8 code unit; otherwise, . + To be added. + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + Gets a value that indicates whether the scalar value associated with this is within the BMP encoding range. + + if the scalar value associated is within the BMP encoding range ([ U+0000..U+FFFF ]) and therefore representable by a single UTF-16 code unit; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a control character. + + if is a control character; otherwise, . + + and comparing the result against . + +Per [Unicode stability policies](https://www.unicode.org/policies/stability_policy.html), the set of control characters is permanently fixed to be the union of `[ U+0000..U+001F ]` and `[ U+007F..U+009F ]`. + +For more information, see . + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a decimal digit. + + if is a decimal digit; otherwise, . + + and comparing the result against . + +For more information, see . + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a letter. + + if is a letter; otherwise, . + + and comparing the result against any of the values , , , , and . + +For more information, see . + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a letter or a decimal digit. + + if is a letter or a decimal digit; otherwise, . + + and comparing the result against any of the values , , , , , and . + +For more information, see . + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a lowercase letter. + + if is a lowercase letter; otherwise, . + + +and comparing the result against . + +For more information, see . + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a number. + + if is a number; otherwise, . + + and comparing the result against any of the values , , and . + +For more information, see . + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a punctuation mark. + + if is a punctuation mark; otherwise, . + + and comparing the result against any of the values , , , , , , and . + +For more information, see . + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a separator character. + + if is a separator character; otherwise, . + + and comparing the result against any of the values , , and . + +For more information, see . + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a symbol character. + + if is a symbol character; otherwise, . + + and comparing the result against any of the values , , , and . + +For more information, see . + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as an uppercase letter. + + if is an uppercase letter; otherwise,. + + and comparing the result against . + +For more information, see . + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The Unicode scalar value. + Returns a value that indicates whether a 32-bit signed integer represents a valid Unicode scalar value; that is, it is in the range [ U+0000..U+D7FF ], inclusive; or [ U+E000..U+10FFFF ], inclusive. + + if is a valid Unicode scalar value; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Boolean + + + + + + The Unicode scalar value. + Returns a value that indicates whether a 32-bit unsigned integer represents a valid Unicode scalar value; that is, it is in the range [ U+0000..U+D7FF ], inclusive, or [ U+E000..U+10FFFF ], inclusive. + + if is a valid Unicode scalar value; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a white space character. + + if is a white space character; otherwise, . + + and comparing the result against any of the values , , and . However, there are some s in the category which are also classified as white space characters, and this method accounts for those values. + +For more information, see . + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + The second value to compare. + Returns a value that indicates whether two instances are equal. + + if and are equal; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Rune + + + + + + The 16-bit Unicode character to convert. + Defines an explicit conversion of a 16-bit Unicode character to a . + + as a 32-bit Unicode character. + To be added. + + is a Unicode scalar that represents a surrogate code point. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Rune + + + + + + The 32-bit signed integer to convert. + Defines an explicit conversion of a 32-bit signed integer to a . + + as a 32-bit Unicode character. + To be added. + + is an invalid Unicode scalar. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.Rune + + + + + + The 32-bit signed integer to convert. + Defines an explicit conversion of a 32-bit unsigned integer to a . + + as a 32-bit Unicode character. + To be added. + + is an invalid Unicode scalar. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + The second value to compare. + Returns a value indicating whether a specified is greater than another specified . + + if is greater than ; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + The second value to compare. + Returns a value indicating whether a specified is greater than or equal to another specified . + + if is greater than or equal to ; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + The second value to compare. + Returns a value that indicates whether two instances have different values. + + if and are not equal; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + the second value to compare. + Returns a value indicating whether a specified is less than another specified . + + if is less than ; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + The second value to compare. + Returns a value indicating whether a specified is less than or equal to another specified . + + if is less than or equal to ; otherwise, . + To be added. + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + Gets the Unicode plane (0 to 16, inclusive) that contains this scalar. + The Unicode plane (0 to 16, inclusive) that contains this scalar. + To be added. + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Rune + + + Gets a instance that represents the Unicode replacement character U+FFFD. + A instance that represents the Unicode replacement character U+FFFD. + To be added. + + + + + + + + + + Method + + M:System.IComparable.CompareTo(System.Object) + + + System.Runtime + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The object to compare with the current instance. + Compares the current instance to the specified object. + A signed integer indicating the position of this instance in the sort order in relation to :
- Less than zero: This instance precedes . +
- Zero: The instance has the same position in the sort order as . +
- Greater than zero: This instance follows . + + instance is cast to an interface. + + ]]> + + + + + + + + + + + + Method + + M:System.IFormattable.ToString(System.String,System.IFormatProvider) + + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.String + + + + + + + The format to use. + -or- + ( in Visual Basic) to use the default format defined for the type of the implementation. + The provider to use to format the value. + -or- + ( in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system. + Formats the value of the current instance using the specified format. + The value of the current instance in the specified format. + To be added. + + + + + + + + + + Method + + M:System.ISpanFormattable.TryFormat(System.Span{System.Char},System.Int32@,System.ReadOnlySpan{System.Char},System.IFormatProvider) + + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + + + When this method returns, contains this instance's value formatted as a span of characters. + When this method returns, contains the number of characters that were written in . + A span containing the characters that represent a standard or custom format string that defines the acceptable format for . + An optional object that supplies culture-specific formatting information for . + Tries to format the value of the current instance into the provided span of characters. + + if the formatting was successful; otherwise, . + To be added. + + + + + + + + + + Method + + M:System.IUtf8SpanFormattable.TryFormat(System.Span{System.Byte},System.Int32@,System.ReadOnlySpan{System.Char},System.IFormatProvider) + + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + + + + The span in which to write this instance's value formatted as a span of bytes. + When this method returns, contains the number of bytes that were written in . + A span containing the characters that represent a standard or custom format string that defines the acceptable format for . + An optional object that supplies culture-specific formatting information for . + Tries to format the value of the current instance as UTF-8 into the provided span of bytes. + + if the formatting was successful; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Text.Rune + + + + + + + The 32-bit Unicode character to convert. + An object that supplies culture-specific casing rules. + Returns a copy of the specified converted to lowercase, using the casing rules of the specified culture. + The lowercase equivalent of . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Rune + + + + + + The 32-bit Unicode character to convert. + Returns a copy of the specified converted to lowercase using the casing rules of the invariant culture. + The lowercase equivalent of . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.String + + + + Returns the string representation of this instance. + The string representation of this rune. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Text.Rune + + + + + + + The 32-bit Unicode character to convert. + An object that supplies culture-specific casing rules. + Returns a copy of the specified converted to uppercase, using the casing rules of the specified culture. + The uppercase equivalent of . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Rune + + + + + + The 32-bit Unicode character to convert. + Returns a copy of the specified converted to uppercase using the casing rules of the invariant culture. + The uppercase equivalent of . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The character from which to create the rune. + When this method returns, the rune that corresponds to . + Attempts to create a from a specified character and returns a value that indicates whether the operation succeeded. + + if the method succeeded; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The Unicode scalar value. + When this method returns, the rune that corresponds to . + Attempts to create a from a specified signed integer that represents a Unicode scalar value. + + if the method succeeded; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Boolean + + + + + + + The Unicode scalar value. + When this method returns, the rune that corresponds to . + Attempts to create a from the specified 32-bit unsigned integer that represents a Unicode scalar value. + + if the method succeeded; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + + The high surrogate of the surrogate pair. + The low surrogate of the surrogate pair. + The rune that corresponds to the specified surrogate pair. + Attempts to create a from the specified UTF-16 surrogate pair and returns a value that indicates whether the operation was successful. + + if the operation succeeded; if the input values don't represent a well-formed UTF-16 surrogate pair. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The buffer to which to write this value as UTF-16 encoded value. + The number of values written to , or 0 if the destination buffer is not large enough to contain the output. + Encodes this to a UTF-16 encoded destination buffer. + + if the value was written to the buffer; otherwise, . + + property can be queried ahead of time to determine the required size of the `destination` buffer. + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The buffer to which to write the UTF-8 encoded value. + The number of values written to , or 0 if the destination buffer is not large enough to contain the output. + Encodes this to a UTF-8 encoded destination buffer. + + if the value was written to the buffer; otherwise, . + + property can be queried ahead of time to determine the required size of the `destination` buffer. + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Boolean + + + + + + + + The string from which to extract the rune. + The zero-based index from which to extract the rune. + When this method returns, the decoded rune. + Attempts to get the that begins at a specified position in a string, and return a value that indicates whether the operation succeeded. + + if a scalar value was successfully extracted from the specified index; if a value could not be extracted because of invalid data. + + + + + is . + + is out of the range of . + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + Gets the length in code units () of the UTF-16 sequence required to represent this scalar value. + The length in code units () of the UTF-16 sequence required to represent this scalar value. + + + + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + Gets the length in code units of the UTF-8 sequence required to represent this scalar value. + The length in code units of the UTF-8 sequence required to represent this scalar value. + + + + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + Gets the Unicode scalar value as an integer. + The Unicode scalar value as an integer. + To be added. + + + + diff --git a/xml/System.Text/StringBuilder.xml b/xml/System.Text/StringBuilder.xml index 9f53c6ca62f..cae1a4cd317 100644 --- a/xml/System.Text/StringBuilder.xml +++ b/xml/System.Text/StringBuilder.xml @@ -1,7218 +1,7240 @@ - - - - - - - - - - - - - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Object - - - - System.Runtime.Serialization.ISerializable - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Serializable] - [<System.Serializable>] - - - [System.Runtime.InteropServices.ComVisible(true)] - [<System.Runtime.InteropServices.ComVisible(true)>] - - - - Represents a mutable string of characters. This class cannot be inherited. - - -## The String and StringBuilder types - Although and both represent sequences of characters, they are implemented differently. is an immutable type. That is, each operation that appears to modify a object actually creates a new string. - - For example, the call to the method in the following C# example appears to change the value of a string variable named `value`. In fact, the method returns a `value` object that has a different value and address from the `value` object that was passed to the method. Note that the example must be compiled using the `/unsafe` compiler option. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/immutability2.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/immutability2.fs" id="Snippet1"::: - - For routines that perform extensive string manipulation (such as apps that modify a string numerous times in a loop), modifying a string repeatedly can exact a significant performance penalty. The alternative is to use , which is a mutable string class. Mutability means that once an instance of the class has been created, it can be modified by appending, removing, replacing, or inserting characters. A object maintains a buffer to accommodate expansions to the string. New data is appended to the buffer if room is available; otherwise, a new, larger buffer is allocated, data from the original buffer is copied to the new buffer, and the new data is then appended to the new buffer. - -> [!IMPORTANT] -> Although the class generally offers better performance than the class, you should not automatically replace with whenever you want to manipulate strings. Performance depends on the size of the string, the amount of memory to be allocated for the new string, the system on which your code is executing, and the type of operation. You should be prepared to test your code to determine whether actually offers a significant performance improvement. - - Consider using the class under these conditions: - -- When the number of changes that your code will make to a string is small. In these cases, might offer negligible or no performance improvement over . - -- When you are performing a fixed number of concatenation operations, particularly with string literals. In this case, the compiler might combine the concatenation operations into a single operation. - -- When you have to perform extensive search operations while you are building your string. The class lacks search methods such as `IndexOf` or `StartsWith`. You'll have to convert the object to a for these operations, and this can negate the performance benefit from using . For more information, see the [Searching the text in a StringBuilder object](#Searching) section. - - Consider using the class under these conditions: - -- When you expect your code to make an unknown number of changes to a string at design time (for example, when you are using a loop to concatenate a random number of strings that contain user input). - -- When you expect your code to make a significant number of changes to a string. - - -## How StringBuilder works - The property indicates the number of characters the object currently contains. If you add characters to the object, its length increases until it equals the size of the property, which defines the number of characters that the object can contain. If the number of added characters causes the length of the object to exceed its current capacity, new memory is allocated, the value of the property is doubled, new characters are added to the object, and its property is adjusted. Additional memory for the object is allocated dynamically until it reaches the value defined by the property. When the maximum capacity is reached, no further memory can be allocated for the object, and trying to add characters or expand it beyond its maximum capacity throws either an or an exception. - - The following example illustrates how a object allocates new memory and increases its capacity dynamically as the string assigned to the object expands. The code creates a object by calling its default (parameterless) constructor. The default capacity of this object is 16 characters, and its maximum capacity is more than 2 billion characters. Appending the string "This is a sentence." results in a new memory allocation because the string length (19 characters) exceeds the default capacity of the object. The capacity of the object doubles to 32 characters, the new string is added, and the length of the object now equals 19 characters. The code then appends the string "This is an additional sentence." to the value of the object 11 times. Whenever the append operation causes the length of the object to exceed its capacity, its existing capacity is doubled and the operation succeeds. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/default1.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/default1.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/default1.vb" id="Snippet3"::: - - -## Memory allocation - The default capacity of a object is 16 characters, and its default maximum capacity is . These default values are used if you call the and constructors. - - You can explicitly define the initial capacity of a object in the following ways: - -- By calling any of the constructors that includes a `capacity` parameter when you create the object. - -- By explicitly assigning a new value to the property to expand an existing object. Note that the property throws an exception if the new capacity is less than the existing capacity or greater than the object's maximum capacity. - -- By calling the method with the new capacity. The new capacity must not be greater than the object's maximum capacity. However, unlike an assignment to the property, does not throw an exception if the desired new capacity is less than the existing capacity; in this case, the method call has no effect. - - If the length of the string assigned to the object in the constructor call exceeds either the default capacity or the specified capacity, the property is set to the length of the string specified with the `value` parameter. - - You can explicitly define the maximum capacity of a object by calling the constructor. You can't change the maximum capacity by assigning a new value to the property, because it is read-only. - - As the previous section shows, whenever the existing capacity is inadequate, additional memory is allocated and the capacity of a object doubles up to the value defined by the property. - - In general, the default capacity and maximum capacity are adequate for most apps. You might consider setting these values under the following conditions: - -- If the eventual size of the object is likely to grow exceedingly large, typically in excess of several megabytes. In this case, there may be some performance benefit from setting the initial property to a significantly high value to eliminate the need for too many memory reallocations. - -- If your code is running on a system with limited memory. In this case, you may want to consider setting the property to less than if your code is handling large strings that may cause it to execute in a memory-constrained environment. - - -## Instantiating a StringBuilder object - You instantiate a object by calling one of its six overloaded class constructors, which are listed in the following table. Three of the constructors instantiate a object whose value is an empty string, but set its and values differently. The remaining three constructors define a object that has a specific string value and capacity. Two of the three constructors use the default maximum capacity of , whereas the third allows you to set the maximum capacity. - -|Constructor|String value|Capacity|Maximum capacity| -|-----------------|------------------|--------------|----------------------| -|||16|| -|||Defined by the `capacity` parameter|| -|||Defined by the `capacity` parameter|Defined by the `maxCapacity` parameter| -||Defined by the `value` parameter|16 or `value`. , whichever is greater|| -||Defined by the `value` parameter|Defined by the `capacity` parameter or `value`. , whichever is greater.|| -||Defined by `value`. (`startIndex`, `length`)|Defined by the `capacity` parameter or `value`. , whichever is greater.|| - - The following example uses three of these constructor overloads to instantiate objects. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/instantiate1.cs" interactive="try-dotnet" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/instantiate1.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/instantiate1.vb" id="Snippet6"::: - - -## Calling StringBuilder methods - Most of the methods that modify the string in a instance return a reference to that same instance. This enables you to call methods in two ways: - -- You can make individual method calls and ignore the return value, as the following example does. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/call1.cs" interactive="try-dotnet" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/call1.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/call1.vb" id="Snippet4"::: - -- You can make a series of method calls in a single statement. This can be convenient if you want to write a single statement that chains successive operations. The following example consolidates three method calls from the previous example into a single line of code. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/call2.cs" interactive="try-dotnet" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/call2.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/call2.vb" id="Snippet5"::: - - -## Performing StringBuilder operations - You can use the methods of the class to iterate, add, delete, or modify characters in a object. - - -### Iterating StringBuilder characters - You can access the characters in a object by using the property. In C#, is an indexer; in Visual Basic, it is the default property of the class. This enables you to set or retrieve individual characters by using their index only, without explicitly referencing the property. Characters in a object begin at index 0 (zero) and continue to index - 1. - - The following example illustrates the property. It appends ten random numbers to a object, and then iterates each character. If the character's Unicode category is , it decreases the number by 1 (or changes the number to 9 if its value is 0). The example displays the contents of the object both before and after the values of individual characters were changed. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/chars1.cs" interactive="try-dotnet" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/chars1.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/chars1.vb" id="Snippet7"::: - -[!INCLUDE[stringbuilder-performance-note](~/includes/stringbuilder-perf-note.md)] - - -### Adding text to a StringBuilder object - The class includes the following methods for expanding the contents of a object: - -- The method appends a string, a substring, a character array, a portion of a character array, a single character repeated multiple times, or the string representation of a primitive data type to a object. - -- The method appends a line terminator or a string along with a line terminator to a object. - -- The method appends a [composite format string](/dotnet/standard/base-types/composite-formatting) to a object. The string representations of objects included in the result string can reflect the formatting conventions of the current system culture or a specified culture. - -- The method inserts a string, a substring, multiple repetitions of a string, a character array, a portion of a character array, or the string representation of a primitive data type at a specified position in the object. The position is defined by a zero-based index. - - The following example uses the , , , and methods to expand the text of a object. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/expand1.cs" interactive="try-dotnet" id="Snippet9"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/expand1.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/expand1.vb" id="Snippet9"::: - - -### Deleting text from a StringBuilder object - The class includes methods that can reduce the size of the current instance. The method removes all characters and sets the property to zero. The method deletes a specified number of characters starting at a particular index position. In addition, you can remove characters from the end of a object by setting its property to a value that is less than the length of the current instance. - - The following example removes some of the text from a object, displays its resulting capacity, maximum capacity, and length property values, and then calls the method to remove all the characters from the object. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/delete1.cs" interactive="try-dotnet" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/delete1.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/delete1.vb" id="Snippet10"::: - - -### Modifying the text in a StringBuilder object - The method replaces all occurrences of a character or a string in the entire object or in a particular character range. The following example uses the method to replace all exclamation points (!) with question marks (?) in the object. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/replace1.cs" interactive="try-dotnet" id="Snippet11"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/replace1.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/replace1.vb" id="Snippet11"::: - - -## Searching the text in a StringBuilder object - The class does not include methods similar to the , , and methods provided by the class, which allow you to search the object for a particular character or a substring. Determining the presence or starting character position of a substring requires that you search a value by using either a string search method or a regular expression method. There are four ways to implement such searches, as the following table shows. - -|Technique|Pros|Cons| -|---------------|----------|----------| -|Search string values before adding them to the object.|Useful for determining whether a substring exists.|Cannot be used when the index position of a substring is important.| -|Call and search the returned object.|Easy to use if you assign all the text to a object, and then begin to modify it.|Cumbersome to repeatedly call if you must make modifications before all text is added to the object.

You must remember to work from the end of the object's text if you're making changes.| -|Use the property to sequentially search a range of characters.|Useful if you're concerned with individual characters or a small substring.|Cumbersome if the number of characters to search is large or if the search logic is complex.

Results in very poor performance for objects that have grown very large through repeated method calls. | -|Convert the object to a object, and perform modifications on the object.|Useful if the number of modifications is small.|Negates the performance benefit of the class if the number of modifications is large.| - - Let's examine these techniques in greater detail. - -- If the goal of the search is to determine whether a particular substring exists (that is, if you aren't interested in the position of the substring), you can search strings before storing them in the object. The following example provides one possible implementation. It defines a `StringBuilderFinder` class whose constructor is passed a reference to a object and the substring to find in the string. In this case, the example tries to determine whether recorded temperatures are in Fahrenheit or Celsius, and adds the appropriate introductory text to the beginning of the object. A random number generator is used to select an array that contains data in either degrees Celsius or degrees Fahrenheit. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern1.cs" interactive="try-dotnet" id="Snippet12"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern1.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern1.vb" id="Snippet12"::: - -- Call the method to convert the object to a object. You can search the string by using methods such as or , or you can use regular expressions and the class to search for patterns. Because both and objects use UTF-16 encoding to store characters, the index positions of characters, substrings, and regular expression matches are the same in both objects. This enables you to use methods to make changes at the same position at which that text is found in the object. - - > [!NOTE] - > If you adopt this approach, you should work from the end of the object to its beginning so that you don't have to repeatedly convert the object to a string. - - The following example illustrates this approach. It stores four occurrences of each letter of the English alphabet in a object. It then converts the text to a object and uses a regular expression to identify the starting position of each four-character sequence. Finally, it adds an underscore before each four-character sequence except for the first sequence, and converts the first character of the sequence to uppercase. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern2.cs" interactive="try-dotnet" id="Snippet13"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern2.fs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern2.vb" id="Snippet13"::: - -- Use the property to sequentially search a range of characters in a object. This approach may not be practical if the number of characters to be searched is large or the search logic is particularly complex. For the performance implications of character-by-character index-based access for very large, chunked objects, see the documentation for the property. - - The following example is identical in functionality to the previous example but differs in implementation. It uses the property to detect when a character value has changed, inserts an underscore at that position, and converts the first character in the new sequence to uppercase. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern3.cs" interactive="try-dotnet" id="Snippet14"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern3.fs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern3.vb" id="Snippet14"::: - -- Store all the unmodified text in the object, call the method to convert the object to a object, and perform the modifications on the object. You can use this approach if you have only a few modifications; otherwise, the cost of working with immutable strings may negate the performance benefits of using a object. - - The following example is identical in functionality to the previous two examples but differs in implementation. It creates a object, converts it to a object, and then uses a regular expression to perform all remaining modifications on the string. The method uses a lambda expression to perform the replacement on each match. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern4.cs" interactive="try-dotnet" id="Snippet15"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern4.fs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern4.vb" id="Snippet15"::: - - -## Converting the StringBuilder object to a string - You must convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. You perform this conversion by calling the method. For an illustration, see the previous example, which calls the method to convert a object to a string so that it can be passed to a regular expression method. - - - -## Examples - The following example shows how to call many of the methods defined by the class. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringBuilder/cpp/StringBuilder.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/StringBuilder.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/StringBuilder.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringBuilder/VB/StringBuilder.vb" id="Snippet1"::: - - ]]> - - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Initializes a new instance of the class. - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - - Initializes a new instance of the class. - - , and the capacity is set to the implementation-specific default capacity. - - - -## Examples - The following example demonstrates how to call the constructor with no parameters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - - - - The suggested starting size of this instance. - Initializes a new instance of the class using the specified capacity. - - property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. - - The string value of this instance is set to . If `capacity` is zero, the implementation-specific default capacity is used. - - - -## Examples - The following example demonstrates how to call the constructor with a specified capacity. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet3"::: - - ]]> - - - is less than zero. - - - - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - - - - The string used to initialize the value of the instance. If is , the new will contain the empty string (that is, it contains ). - Initializes a new instance of the class using the specified string. - - will contain the empty string (that is, it contains ). - - - -## Examples - The following example demonstrates how to call the constructor with the specified string. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet4"::: - - ]]> - - - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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>] - - - - - - - - The suggested starting size of the . - The maximum number of characters the current string can contain. - Initializes a new instance of the class that starts with a specified capacity and can grow to a specified maximum. - - property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. - - If `capacity` is zero, the implementation-specific default capacity is used. - - The `maxCapacity` property defines the maximum number of characters that the current instance can hold. Its value is assigned to the property. If the number of characters to be stored in the current instance exceeds this `maxCapacity` value, the object does not allocate additional memory, but instead throws an exception. - - - -## Examples - The following example demonstrates how to call the constructor with a specified capacity and maximum capacity. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet5"::: - - ]]> - - - is less than one, is less than zero, or is greater than . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - - - - - The string used to initialize the value of the instance. If is , the new will contain the empty string (that is, it contains ). - The suggested starting size of the . - Initializes a new instance of the class using the specified string and capacity. - - property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. - - If `capacity` is zero, the implementation-specific default capacity is used. - - - -## Examples - The following example demonstrates how to call the constructor with an initial string and a specified capacity. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet7"::: - - ]]> - - - is less than zero. - - - - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - - - - - - - The string that contains the substring used to initialize the value of this instance. If is , the new will contain the empty string (that is, it contains ). - The position within where the substring begins. - The number of characters in the substring. - The suggested starting size of the . - Initializes a new instance of the class from the specified substring and capacity. - - property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. - - If `capacity` is zero, the implementation-specific default capacity is used. - - - -## Examples - The following example demonstrates how to call the constructor with the specified string. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet6"::: - - ]]> - - - is less than zero. - - -or- - - plus is not a position within . - - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Appends the string representation of a specified object to this instance. - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - The Boolean value to append. - Appends the string representation of a specified Boolean value to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet2"::: - - The method calls the method to get the string representation of `value`. The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 8-bit unsigned integer to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet3"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - The UTF-16-encoded code unit to append. - Appends the string representation of a specified object to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet4"::: - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The array of characters to append. - Appends the string representation of the Unicode characters in a specified array to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet6"::: - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified decimal number to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet8"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified double-precision floating-point number to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet9"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet9"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 16-bit signed integer to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet10"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 32-bit signed integer to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet11"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet11"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 64-bit signed integer to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet12"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet12"::: - - The method calls the to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The object to append. - Appends the string representation of a specified object to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. It defines a `Dog` class, creates a `Dog` object, and makes three calls to the method to create a string that contains the dog's name and breed. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append4.cs" interactive="try-dotnet" id="Snippet18"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append4.fs" id="Snippet18"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append4.vb" id="Snippet18"::: - - The method calls the method to get the string representation of `value`. If `value` is `null`, no changes are made to the object. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Text.StringBuilder - - - - - - The read-only character memory region to append. - Appends the string representation of a specified read-only character memory region to this instance. - A reference to this instance after the append operation is completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Text.StringBuilder - - - - - - The read-only character span to append. - Appends the string representation of a specified read-only character span to this instance. - A reference to this instance after the append operation is completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 8-bit signed integer to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet13"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet13"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified single-precision floating-point number to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" id="Snippet14"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet14"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The string to append. - Appends a copy of the specified string to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet2"::: - - If `value` is `null`, no changes are made. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The string builder to append. - Appends the string representation of a specified string builder to this instance. - A reference to this instance after the append operation is completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")] - [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")>] - - - - - - The interpolated string to append. - Appends the specified interpolated string to this instance. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 16-bit unsigned integer to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet15"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet15"::: - - The method calls the method to get the string representation of `value`. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 32-bit unsigned integer to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet16"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet16"::: - - The calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 64-bit unsigned integer to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet17"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet17"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet17"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - - The character to append. - The number of times to append . - Appends a specified number of copies of the string representation of a Unicode character to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet5"::: - - The capacity of this instance is adjusted as needed. - - ]]> - - - is less than zero. - - -or- - - Enlarging the value of this instance would exceed . - Out of memory. - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 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.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Text.StringBuilder - - - - - - - A pointer to an array of characters. - The number of characters in the array. - Appends an array of Unicode characters starting at a specified address to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object. - - The capacity of this instance is adjusted as needed. - - ]]> - - - - is less than zero. - - -or- - - Enlarging the value of this instance would exceed . - - is a null pointer. - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - Method - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })] - [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })>] - - - - - - An object that supplies culture-specific formatting information. - The interpolated string to append. - Appends the specified interpolated string to this instance using the specified format. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - A character array. - The starting position in . - The number of characters to append. - Appends the string representation of a specified subarray of Unicode characters to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet7"::: - - The capacity of this instance is adjusted as needed. - - ]]> - - - is , and and are not zero. - - is less than zero. - - -or- - - is less than zero. - - -or- - - + is greater than the length of . - - -or- - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - The string that contains the substring to append. - The starting position of the substring within . - The number of characters in to append. - Appends a copy of a specified substring to this instance. - A reference to this instance after the append operation has completed. - - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet19"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet19"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet19"::: - - The capacity of this instance is adjusted as needed. - - ]]> - - - is , and and are not zero. - - less than zero. - - -or- - - less than zero. - - -or- - - + is greater than the length of . - - -or- - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - The string builder that contains the substring to append. - The starting position of the substring within . - The number of characters in to append. - Appends a copy of a substring within a specified string builder to this instance. - A reference to this instance after the append operation has completed. - To be added. - - - - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding object argument. - Composite Formatting - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.StringBuilder - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - A composite format string. - An object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a single argument. - A reference to this instance with appended. Each format item in is replaced by the string representation of . - - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items. The index of the format items must be 0, to correspond to `arg0`, the single object in the parameter list of this method. The formatting process replaces each format item with the string representation of `arg0`. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - `arg0` represents the object to be formatted. Each format item in `format` is replaced with the string representation of `arg0`. If the format item includes `formatString` and `arg0` implements the interface, then `arg0.ToString(formatString, null)` defines the formatting. Otherwise, `arg0.ToString()` defines the formatting. - - If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: - - ]]> - - - is . - - is invalid. - - -or- - - The index of a format item is less than 0 (zero), or greater than or equal to 1. - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - A composite format string. - An array of objects to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array. - A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. - - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - `args` represents the objects to be formatted. Each format item in `format` is replaced with the string representation of the corresponding object in `args`. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `args[index].ToString(formatString, provider)` defines the formatting. Otherwise, `args[index].ToString()` defines the formatting. - - If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: - - ]]> - - - or is . - - is invalid. - - -or- - - The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - An object that supplies culture-specific formatting information. - A composite format string. - The object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a single argument using a specified format provider. - A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of in which any format specification is replaced by the string representation of . - - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items. The index of each format item must be zero (0) since this method includes an argument list with a single argument. The formatting process replaces each format item with the string representation of `arg0`. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . In this case, since the method has a single argument in the argument list, the value of *index* must always be 0. If it is not, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - The `provider` parameter specifies an implementation that can provide formatting information for the objects in `args`. `provider` can be any of the following: - -- A object that provides culture-specific formatting information. - -- A object that provides culture-specific formatting information for `arg0` if it is a numeric value. - -- A object that provides culture-specific formatting information for `arg0` if it is a date and time value. - -- A custom implementation that provides formatting information for `arg0`. Typically, such an implementation also implements the interface. - - If the `provider` parameter is `null`, formatting information is obtained from the current culture. - - `arg0` represents the object to be formatted. Each format item in `format` is replaced with the string representation of `arg0`. If the format item includes `formatString` and `arg0` implements the interface, then `arg0.ToString(formatString, provider)` defines the formatting. Otherwise, `arg0.ToString()` defines the formatting. - -## Examples - The following includes two calls to the method. Both use the formatting conventions of the English-United Kingdom (en-GB) culture. The first inserts the string representation of a value currency in a result string. The second inserts a value in two places in a result string, the first including only the short date string and the second the short time string. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat1.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat1.vb" id="Snippet2"::: - - ]]> - - - is . - - is invalid. - - -or- - - The index of a format item is less than 0 (zero), or greater than or equal to one (1). - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - How to: Define and Use Custom Numeric Format Providers - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - An object that supplies culture-specific formatting information. - A composite format string. - An array of objects to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array using a specified format provider. - A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. - - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - The `provider` parameter specifies an implementation that can provide formatting information for the objects in `args`. `provider` can be any of the following: - -- A object that provides culture-specific formatting information. - -- A object that provides culture-specific formatting information for numeric values in `args`. - -- A object that provides culture-specific formatting information for date and time values in `args`. - -- A custom implementation that provides formatting information for one or more of the objects in `args`. Typically, such an implementation also implements the interface. The second example in the next section illustrates an method call with a custom implementation. - - If the `provider` parameter is `null`, format provider information is obtained from the current culture. - - `args` represents the objects to be formatted. Each format item in `format` is replaced with the string representation of the corresponding object in `args`. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `args[index].ToString(formatString, provider)` defines the formatting. Otherwise, `args[index].ToString()` defines the formatting. - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: - - The following example defines a custom implementation named `CustomerFormatter` that formats a 10-digit customer number with hyphens after the fourth and seventh digits. It is passed to the method to create a string that includes the formatted customer number and customer name. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/customernumberformatter1.vb" id="Snippet1"::: - - ]]> - - - is . - - is invalid. - - -or- - - The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - How to: Define and Use Custom Numeric Format Providers - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 2 })>] - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - A composite format string. - The first object to format. - The second object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments. - A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. - - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to `arg0` and `arg1`, the two objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - `arg0` and `arg1` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of either `arg0` or `arg1`. If the format item includes `formatString` and the corresponding object implements the interface, then `arg`*x*`.ToString(formatString, provider)` defines the formatting, where *x* is the index of the argument. Otherwise, `arg`*x*`.ToString()` defines the formatting. - - If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: - - ]]> - - - is . - - is invalid. - - -or- - - The index of a format item is less than 0 (zero), or greater than or equal to 2. - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Text.StringBuilder - - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - An object that supplies culture-specific formatting information. - A composite format string. - The first object to format. - The second object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments using a specified format provider. - A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. - - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - The `provider` parameter specifies an implementation that can provide formatting information for `arg0` and `arg1`. `provider` can be any of the following: - -- A object that provides culture-specific formatting information. - -- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are numeric values. - -- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are date and time values. - -- A custom implementation that provides formatting information for `arg0` and `arg1`. Typically, such an implementation also implements the interface. - - If the `provider` parameter is `null`, format provider information is obtained from the current culture. - - `arg0` and `arg1` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of the object that has the corresponding index. If the format item includes `formatString` and the corresponding argument implements the interface, then the argument's `ToString(formatString, provider)` method defines the formatting. Otherwise, the argument's `ToString()` method defines the formatting. - - - -## Examples - The following example uses the method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only to objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat2.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat2.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat2.vb" id="Snippet3"::: - - ]]> - - - is . - - is invalid. - - -or- - - The index of a format item is less than 0 (zero), or greater than or equal to 2 (two). - The length of the expanded string would exceed . - - IIn .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - How to: Define and Use Custom Numeric Format Providers - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Text.StringBuilder - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - - A composite format string. - The first object to format. - The second object to format. - The third object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of three arguments. - A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. - - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to `arg0` through `arg2`, the objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - `arg0`, `arg1`, and `arg2` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of either `arg0`, `arg1`, or `arg2`, depending on the index of the format item. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `arg`*x*`.ToString(formatString, null)` defines the formatting, where *x* is the index of the argument. Otherwise, `arg`*x*`.ToString()` defines the formatting. - - If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: - - ]]> - - - is . - - is invalid. - - -or- - - The index of a format item is less than 0 (zero), or greater than or equal to 3. - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Text.StringBuilder - - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - - An object that supplies culture-specific formatting information. - A composite format string. - The first object to format. - The second object to format. - The third object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of three arguments using a specified format provider. - A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. - - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - The `provider` parameter specifies an implementation that can provide formatting information for `arg0` and `arg1`. `provider` can be any of the following: - -- A object that provides culture-specific formatting information. - -- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are numeric values. - -- A object that provides culture-specific formatting information for `arg0`, `arg1`, or `arg2` if they are date and time values. - -- A custom implementation that provides formatting information for `arg0`, `arg1`, and `arg2`. Typically, such an implementation also implements the interface. - - If the `provider` parameter is `null`, format provider information is obtained from the current culture. - - `arg0`, `arg1`, and `arg2` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of the object that has the corresponding index. If the format item includes `formatString` and the corresponding argument implements the interface, then the argument's `ToString(formatString, provider)` method defines the formatting. Otherwise, the argument's `ToString()` method defines the formatting. - - - -## Examples - The following example uses the method to illustrate the result of a Boolean `And` operation with integer values. Note that the format string includes six format items, but the method has only three items in its argument list, because each item is formatted in two different ways. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat3.cs" interactive="try-dotnet" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat3.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat3.vb" id="Snippet4"::: - - ]]> - - - is . - - is invalid. - - -or- - - The index of a format item is less than 0 (zero), or greater than or equal to 3 (three). - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - How to: Define and Use Custom Numeric Format Providers - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - The character to use as a separator. is included in the joined strings only if has more than one element. - An array that contains the strings to concatenate and append to the current instance of the string builder. - Concatenates the string representations of the elements in the provided array of objects, using the specified char separator between each member, then appends the result to the current instance of the string builder. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - The character to use as a separator. is included in the joined strings only if has more than one element. - An array that contains the strings to concatenate and append to the current instance of the string builder. - Concatenates the strings of the provided array, using the specified char separator between each string, then appends the result to the current instance of the string builder. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - The string to use as a separator. is included in the joined strings only if has more than one element. - An array that contains the strings to concatenate and append to the current instance of the string builder. - Concatenates the string representations of the elements in the provided array of objects, using the specified separator between each member, then appends the result to the current instance of the string builder. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - The string to use as a separator. is included in the joined strings only if has more than one element. - An array that contains the strings to concatenate and append to the current instance of the string builder. - Concatenates the strings of the provided array, using the specified separator between each string, then appends the result to the current instance of the string builder. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - - The type of the members of . - The character to use as a separator. is included in the concatenated and appended strings only if has more than one element. - A collection that contains the objects to concatenate and append to the current instance of the string builder. - Concatenates and appends the members of a collection, using the specified char separator between each member. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - The type of the members of . - The string to use as a separator. is included in the concatenated and appended strings only if has more than one element. - A collection that contains the objects to concatenate and append to the current instance of the string builder. - Concatenates and appends the members of a collection, using the specified separator between each member. - A reference to this instance after the append operation has completed. - To be added. - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Appends the default line terminator, or a copy of a specified string and the default line terminator, to the end of this instance. - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - Appends the default line terminator to the end of the current object. - A reference to this instance after the append operation has completed. - - property. - - The capacity of this instance is adjusted as needed. - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendline/CPP/al.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendLine/al.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendLine/al.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendline/VB/al.vb" id="Snippet1"::: - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The string to append. - Appends a copy of the specified string followed by the default line terminator to the end of the current object. - A reference to this instance after the append operation has completed. - - property. - - The capacity of this instance is adjusted as needed. - - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")] - [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")>] - - - - - - The interpolated string to append. - Appends the specified interpolated string followed by the default line terminator to the end of the current StringBuilder object. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })] - [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })>] - - - - - - An object that supplies culture-specific formatting information. - The interpolated string to append. - Appends the specified interpolated string using the specified format, followed by the default line terminator, to the end of the current StringBuilder object. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - Property - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Int32 - - - Gets or sets the maximum number of characters that can be contained in the memory allocated by the current instance. - The maximum number of characters that can be contained in the memory allocated by the current instance. Its value can range from to . - - does not affect the string value of the current instance. can be decreased as long as it is not less than . - - The dynamically allocates more space when required and increases accordingly. For performance reasons, a might allocate more memory than needed. The amount of memory allocated is implementation-specific. - - - -## Examples - The following example demonstrates the property. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: - - ]]> - - The value specified for a set operation is less than the current length of this instance. - - -or- - - The value specified for a set operation is greater than the maximum capacity. - - - - - - - - - - Property - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Char - - - - - - The position of the character. - Gets or sets the character at the specified character position in this instance. - The Unicode character at position . - - . The first character in the string is at index 0. The length of a string is the number of characters it contains. The last accessible character of a instance is at index - 1. - - is the default property of the class. In C#, it is an indexer. This means that individual characters can be retrieved from the property as shown in the following example, which counts the number of alphabetic, white-space, and punctuation characters in a string. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Chars/chars1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Chars/chars1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.chars/vb/chars1.vb" id="Snippet1"::: - -### Performance and character-based indexing - -[!INCLUDE[stringbuilder-performance-note](~/includes/stringbuilder-perf-note.md)] - - ]]> - - - is outside the bounds of this instance while setting a character. - - is outside the bounds of this instance while getting a character. - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - Removes all characters from the current instance. - An object whose is 0 (zero). - - is a convenience method that is equivalent to setting the property of the current instance to 0 (zero). - -## Examples - -The following example instantiates a object with a string, calls the method, and then appends a new string. - -:::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Clear/clear1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Clear/clear1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.clear/vb/clear1.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Void - - - - - - - - The starting position in this instance where characters will be copied from. The index is zero-based. - The writable span where characters will be copied. - The number of characters to be copied. - Copies the characters from a specified segment of this instance to a destination span. - - method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an span. - - For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an span where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Void - - - - - - - - - The starting position in this instance where characters will be copied from. The index is zero-based. - The array where characters will be copied. - The starting position in where characters will be copied. The index is zero-based. - The number of characters to be copied. - Copies the characters from a specified segment of this instance to a specified segment of a destination array. - - method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an array. The array should be a fixed size, preallocated, reusable, and possibly globally accessible. - - For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an array where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.copyto2/CPP/ct2.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/CopyTo/ct2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/CopyTo/ct2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.copyto2/VB/ct2.vb" id="Snippet1"::: - - ]]> - - - is . - - , , or , is less than zero. - - -or- - - is greater than the length of this instance. - - + is greater than the length of this instance. - - -or- - - + is greater than the length of . - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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 minimum capacity to ensure. - Ensures that the capacity of this instance of is at least the specified value. - The new capacity of this instance. - - method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: - - ]]> - - - is less than zero. - - -or- - - Enlarging the value of this instance would exceed . - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Boolean - - - - - - The character span to compare with the current instance. - Returns a value indicating whether the characters in this instance are equal to the characters in a specified read-only character span. - - if the characters in this instance and are the same; otherwise, . - - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Boolean - - - - - - [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] - [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] - - - - - - An object to compare with this instance, or . - Returns a value indicating whether this instance is equal to a specified object. - - if this instance and have equal string, , and values; otherwise, . - - , and values. The `Equals` method uses ordinal comparison to determine whether the strings are equal. - -**.NET Core 3.0 and later versions:** The current instance and `sb` are equal if the strings assigned to both objects are the same. To determine equality, the `Equals` method uses ordinal comparison. The and property values are not used in the comparison. - -## Examples - The following code uses the method to check whether two objects are equal. The method is called repeatedly after small changes are made to each object, and the results are displayed to the console. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder+ChunkEnumerator - - - - Returns an object that can be used to iterate through the chunks of characters represented in a created from this instance. - An enumerator for the chunks in the . - - chunk in sb.GetChunks()) - foreach(char ch in chunk.Span) - { /* operations on ch */ } -``` - -The purpose of this method is to efficiently extract the data of a *constant* . If the is modified while the chunk enumeration is incomplete, the result is undefined. is also not thread-safe, so operating on it with concurrent threads is illegal. - -The chunks returned are not guaranteed to remain unchanged if the is modified, so do not cache them for later use. - -Creating a from a (as the method does in the previous example) is expensive, so create a local variable for the span if you need to use it in a nested `for` statement. For example: - -```csharp -foreach (ReadOnlyMemory chunk in sb.GetChunks()) -{ - var span = chunk.Span; - for(int i = 0; i < span.Length; i++) - { - /* operations on span[i] */ - } -} -``` - - ]]> - - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Inserts the string representation of a specified object into this instance at a specified character position. - - method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.insert/CPP/insert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Insert/insert.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Insert/insert.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.insert/VB/insert.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a Boolean value into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a specified 8-bit unsigned integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a specified Unicode character into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - - -or- - - Enlarging the value of this instance would exceed . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The position in this instance where insertion begins. - The character array to insert. - Inserts the string representation of a specified array of Unicode characters into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is not changed. - - ]]> - - - is less than zero or greater than the length of this instance. - - -or- - - Enlarging the value of this instance would exceed . - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a decimal number into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a double-precision floating-point number into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a specified 16-bit signed integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a specified 32-bit signed integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a 64-bit signed integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The position in this instance where insertion begins. - The object to insert, or . - Inserts the string representation of an object into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - If `value` is `null`, the value of this instance is unchanged. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The character span to insert. - Inserts the sequence of characters into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a specified 8-bit signed integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a single-precision floating point number into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The position in this instance where insertion begins. - The string to insert. - Inserts a string into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is not changed if `value` is `null`, or `value` is not `null` but its length is zero. - - ]]> - - - is less than zero or greater than the current length of this instance. - - -or- - - The current length of this object plus the length of exceeds . - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a 16-bit unsigned integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a 32-bit unsigned integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a 64-bit unsigned integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - The position in this instance where insertion begins. - The string to insert. - The number of times to insert . - Inserts one or more copies of a specified string into this instance at the specified character position. - A reference to this instance after insertion has completed. - - object is not changed if `value` is `null`, `value` is not `null` but its length is zero, or `count` is zero. - - ]]> - - - is less than zero or greater than the current length of this instance. - - -or- - - is less than zero. - The current length of this object plus the length of times exceeds . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - The position in this instance where insertion begins. - A character array. - The starting index within . - The number of characters to insert. - Inserts the string representation of a specified subarray of Unicode characters into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - - - - - is , and and are not zero. - - , , or is less than zero. - - -or- - - is greater than the length of this instance. - - -or- - - plus is not a position within . - - -or- - - Enlarging the value of this instance would exceed . - - - - - - - - - - Property - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - [set: System.Security.SecuritySafeCritical] - [<set: System.Security.SecuritySafeCritical>] - - - - System.Int32 - - - Gets or sets the length of the current object. - The length of this instance. - - object is defined by its number of objects. - - Like the property, the property indicates the length of the current string object. Unlike the property, which is read-only, the property allows you to modify the length of the string stored to the object. - - If the specified length is less than the current length, the current object is truncated to the specified length. If the specified length is greater than the current length, the end of the string value of the current object is padded with the Unicode NULL character (U+0000). - - If the specified length is greater than the current capacity, increases so that it is greater than or equal to the specified length. - - - -## Examples - The following example demonstrates the property. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: - - ]]> - - The value specified for a set operation is less than zero or greater than . - - - - - - - - - - Property - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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 - - - Gets the maximum capacity of this instance. - The maximum number of characters this instance can hold. - - . However, this value is implementation-specific and might be different in other or later implementations. You can explicitly set the maximum capacity of a object by calling the constructor. - -In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - - The zero-based position in this instance where removal begins. - The number of characters to remove. - Removes the specified range of characters from this instance. - A reference to this instance after the excise operation has completed. - - [!NOTE] -> The method modifies the value of the current instance and returns that instance. It does not create and return a new object. - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.remove/CPP/remove.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Remove/remove.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Remove/remove.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.remove/VB/remove.vb" id="Snippet1"::: - - ]]> - - If or is less than zero, or + is greater than the length of this instance. - - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Replaces all occurrences of a specified character or string in this instance with another specified character or string. - - method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.replace/CPP/replace.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Replace/replace.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Replace/replace.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.replace/VB/replace.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.StringBuilder - - - - - - - The character to replace. - The character that replaces . - Replaces all occurrences of a specified character in this instance with another specified character. - A reference to this instance with replaced by . - - instance is unchanged after the replacement. - - ]]> - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The string to replace. - The string that replaces , or . - Replaces all occurrences of a specified string in this instance with another specified string. - A reference to this instance with all instances of replaced by . - - , all occurrences of `oldValue` are removed. - - ]]> - - - is . - The length of is zero. - Enlarging the value of this instance would exceed . - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - - - - The character to replace. - The character that replaces . - The position in this instance where the substring begins. - The length of the substring. - Replaces, within a substring of this instance, all occurrences of a specified character with another specified character. - A reference to this instance with replaced by in the range from to + -1. - - object is unchanged after the replacement. - - ]]> - - - + is greater than the length of the value of this instance. - - -or- - - or is less than zero. - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - The string to replace. - The string that replaces , or . - The position in this instance where the substring begins. - The length of the substring. - Replaces, within a substring of this instance, all occurrences of a specified string with another specified string. - A reference to this instance with all instances of replaced by in the range from to + - 1. - - , all occurrences of `oldValue` are removed. - - ]]> - - - is . - The length of is zero. - - or is less than zero. - - -or- - - plus indicates a character position not within this instance. - - -or- - - Enlarging the value of this instance would exceed . - - - - - - - - - - - Method - - M:System.Runtime.Serialization.ISerializable.GetObjectData(System.Runtime.Serialization.SerializationInfo,System.Runtime.Serialization.StreamingContext) - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - - System.Void - - - - - - - The object to populate with serialization information. - The place to store and retrieve serialized data. Reserved for future use. - Populates a object with the data necessary to deserialize the current object. - - method. - - ]]> - - - is . - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Converts the value of a to a . - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.String - - - - Converts the value of this instance to a . - A string whose value is the same as this instance. - - method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. - - - -## Examples - The following example demonstrates calling the method. This example is part of a larger example provided for the class. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringBuilder/cpp/StringBuilder.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/StringBuilder.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/StringBuilder.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringBuilder/VB/StringBuilder.vb" id="Snippet5"::: - - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.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.String - - - - - - - The starting position of the substring in this instance. - The length of the substring. - Converts the value of a substring of this instance to a . - A string whose value is the same as the specified substring of this instance. - - method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. - - ]]> - - - or is less than zero. - - -or- - - The sum of and is greater than the length of the current instance. - - - - + + + + + + + + + + + + + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Object + + + + System.Runtime.Serialization.ISerializable + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Serializable] + [<System.Serializable>] + + + [System.Runtime.InteropServices.ComVisible(true)] + [<System.Runtime.InteropServices.ComVisible(true)>] + + + + Represents a mutable string of characters. This class cannot be inherited. + + +## The String and StringBuilder types + Although and both represent sequences of characters, they are implemented differently. is an immutable type. That is, each operation that appears to modify a object actually creates a new string. + + For example, the call to the method in the following C# example appears to change the value of a string variable named `value`. In fact, the method returns a `value` object that has a different value and address from the `value` object that was passed to the method. Note that the example must be compiled using the `/unsafe` compiler option. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/immutability2.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/immutability2.fs" id="Snippet1"::: + + For routines that perform extensive string manipulation (such as apps that modify a string numerous times in a loop), modifying a string repeatedly can exact a significant performance penalty. The alternative is to use , which is a mutable string class. Mutability means that once an instance of the class has been created, it can be modified by appending, removing, replacing, or inserting characters. A object maintains a buffer to accommodate expansions to the string. New data is appended to the buffer if room is available; otherwise, a new, larger buffer is allocated, data from the original buffer is copied to the new buffer, and the new data is then appended to the new buffer. + +> [!IMPORTANT] +> Although the class generally offers better performance than the class, you should not automatically replace with whenever you want to manipulate strings. Performance depends on the size of the string, the amount of memory to be allocated for the new string, the system on which your code is executing, and the type of operation. You should be prepared to test your code to determine whether actually offers a significant performance improvement. + + Consider using the class under these conditions: + +- When the number of changes that your code will make to a string is small. In these cases, might offer negligible or no performance improvement over . + +- When you are performing a fixed number of concatenation operations, particularly with string literals. In this case, the compiler might combine the concatenation operations into a single operation. + +- When you have to perform extensive search operations while you are building your string. The class lacks search methods such as `IndexOf` or `StartsWith`. You'll have to convert the object to a for these operations, and this can negate the performance benefit from using . For more information, see the [Searching the text in a StringBuilder object](#Searching) section. + + Consider using the class under these conditions: + +- When you expect your code to make an unknown number of changes to a string at design time (for example, when you are using a loop to concatenate a random number of strings that contain user input). + +- When you expect your code to make a significant number of changes to a string. + + +## How StringBuilder works + The property indicates the number of characters the object currently contains. If you add characters to the object, its length increases until it equals the size of the property, which defines the number of characters that the object can contain. If the number of added characters causes the length of the object to exceed its current capacity, new memory is allocated, the value of the property is doubled, new characters are added to the object, and its property is adjusted. Additional memory for the object is allocated dynamically until it reaches the value defined by the property. When the maximum capacity is reached, no further memory can be allocated for the object, and trying to add characters or expand it beyond its maximum capacity throws either an or an exception. + + The following example illustrates how a object allocates new memory and increases its capacity dynamically as the string assigned to the object expands. The code creates a object by calling its default (parameterless) constructor. The default capacity of this object is 16 characters, and its maximum capacity is more than 2 billion characters. Appending the string "This is a sentence." results in a new memory allocation because the string length (19 characters) exceeds the default capacity of the object. The capacity of the object doubles to 32 characters, the new string is added, and the length of the object now equals 19 characters. The code then appends the string "This is an additional sentence." to the value of the object 11 times. Whenever the append operation causes the length of the object to exceed its capacity, its existing capacity is doubled and the operation succeeds. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/default1.cs" interactive="try-dotnet" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/default1.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/default1.vb" id="Snippet3"::: + + +## Memory allocation + The default capacity of a object is 16 characters, and its default maximum capacity is . These default values are used if you call the and constructors. + + You can explicitly define the initial capacity of a object in the following ways: + +- By calling any of the constructors that includes a `capacity` parameter when you create the object. + +- By explicitly assigning a new value to the property to expand an existing object. Note that the property throws an exception if the new capacity is less than the existing capacity or greater than the object's maximum capacity. + +- By calling the method with the new capacity. The new capacity must not be greater than the object's maximum capacity. However, unlike an assignment to the property, does not throw an exception if the desired new capacity is less than the existing capacity; in this case, the method call has no effect. + + If the length of the string assigned to the object in the constructor call exceeds either the default capacity or the specified capacity, the property is set to the length of the string specified with the `value` parameter. + + You can explicitly define the maximum capacity of a object by calling the constructor. You can't change the maximum capacity by assigning a new value to the property, because it is read-only. + + As the previous section shows, whenever the existing capacity is inadequate, additional memory is allocated and the capacity of a object doubles up to the value defined by the property. + + In general, the default capacity and maximum capacity are adequate for most apps. You might consider setting these values under the following conditions: + +- If the eventual size of the object is likely to grow exceedingly large, typically in excess of several megabytes. In this case, there may be some performance benefit from setting the initial property to a significantly high value to eliminate the need for too many memory reallocations. + +- If your code is running on a system with limited memory. In this case, you may want to consider setting the property to less than if your code is handling large strings that may cause it to execute in a memory-constrained environment. + + +## Instantiating a StringBuilder object + You instantiate a object by calling one of its six overloaded class constructors, which are listed in the following table. Three of the constructors instantiate a object whose value is an empty string, but set its and values differently. The remaining three constructors define a object that has a specific string value and capacity. Two of the three constructors use the default maximum capacity of , whereas the third allows you to set the maximum capacity. + +|Constructor|String value|Capacity|Maximum capacity| +|-----------------|------------------|--------------|----------------------| +|||16|| +|||Defined by the `capacity` parameter|| +|||Defined by the `capacity` parameter|Defined by the `maxCapacity` parameter| +||Defined by the `value` parameter|16 or `value`. , whichever is greater|| +||Defined by the `value` parameter|Defined by the `capacity` parameter or `value`. , whichever is greater.|| +||Defined by `value`. (`startIndex`, `length`)|Defined by the `capacity` parameter or `value`. , whichever is greater.|| + + The following example uses three of these constructor overloads to instantiate objects. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/instantiate1.cs" interactive="try-dotnet" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/instantiate1.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/instantiate1.vb" id="Snippet6"::: + + +## Calling StringBuilder methods + Most of the methods that modify the string in a instance return a reference to that same instance. This enables you to call methods in two ways: + +- You can make individual method calls and ignore the return value, as the following example does. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/call1.cs" interactive="try-dotnet" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/call1.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/call1.vb" id="Snippet4"::: + +- You can make a series of method calls in a single statement. This can be convenient if you want to write a single statement that chains successive operations. The following example consolidates three method calls from the previous example into a single line of code. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/call2.cs" interactive="try-dotnet" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/call2.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/call2.vb" id="Snippet5"::: + + +## Performing StringBuilder operations + You can use the methods of the class to iterate, add, delete, or modify characters in a object. + + +### Iterating StringBuilder characters + You can access the characters in a object by using the property. In C#, is an indexer; in Visual Basic, it is the default property of the class. This enables you to set or retrieve individual characters by using their index only, without explicitly referencing the property. Characters in a object begin at index 0 (zero) and continue to index - 1. + + The following example illustrates the property. It appends ten random numbers to a object, and then iterates each character. If the character's Unicode category is , it decreases the number by 1 (or changes the number to 9 if its value is 0). The example displays the contents of the object both before and after the values of individual characters were changed. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/chars1.cs" interactive="try-dotnet" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/chars1.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/chars1.vb" id="Snippet7"::: + +[!INCLUDE[stringbuilder-performance-note](~/includes/stringbuilder-perf-note.md)] + + +### Adding text to a StringBuilder object + The class includes the following methods for expanding the contents of a object: + +- The method appends a string, a substring, a character array, a portion of a character array, a single character repeated multiple times, or the string representation of a primitive data type to a object. + +- The method appends a line terminator or a string along with a line terminator to a object. + +- The method appends a [composite format string](/dotnet/standard/base-types/composite-formatting) to a object. The string representations of objects included in the result string can reflect the formatting conventions of the current system culture or a specified culture. + +- The method inserts a string, a substring, multiple repetitions of a string, a character array, a portion of a character array, or the string representation of a primitive data type at a specified position in the object. The position is defined by a zero-based index. + + The following example uses the , , , and methods to expand the text of a object. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/expand1.cs" interactive="try-dotnet" id="Snippet9"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/expand1.fs" id="Snippet9"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/expand1.vb" id="Snippet9"::: + + +### Deleting text from a StringBuilder object + The class includes methods that can reduce the size of the current instance. The method removes all characters and sets the property to zero. The method deletes a specified number of characters starting at a particular index position. In addition, you can remove characters from the end of a object by setting its property to a value that is less than the length of the current instance. + + The following example removes some of the text from a object, displays its resulting capacity, maximum capacity, and length property values, and then calls the method to remove all the characters from the object. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/delete1.cs" interactive="try-dotnet" id="Snippet10"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/delete1.fs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/delete1.vb" id="Snippet10"::: + + +### Modifying the text in a StringBuilder object + The method replaces all occurrences of a character or a string in the entire object or in a particular character range. The following example uses the method to replace all exclamation points (!) with question marks (?) in the object. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/replace1.cs" interactive="try-dotnet" id="Snippet11"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/replace1.fs" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/replace1.vb" id="Snippet11"::: + + +## Searching the text in a StringBuilder object + The class does not include methods similar to the , , and methods provided by the class, which allow you to search the object for a particular character or a substring. Determining the presence or starting character position of a substring requires that you search a value by using either a string search method or a regular expression method. There are four ways to implement such searches, as the following table shows. + +|Technique|Pros|Cons| +|---------------|----------|----------| +|Search string values before adding them to the object.|Useful for determining whether a substring exists.|Cannot be used when the index position of a substring is important.| +|Call and search the returned object.|Easy to use if you assign all the text to a object, and then begin to modify it.|Cumbersome to repeatedly call if you must make modifications before all text is added to the object.

You must remember to work from the end of the object's text if you're making changes.| +|Use the property to sequentially search a range of characters.|Useful if you're concerned with individual characters or a small substring.|Cumbersome if the number of characters to search is large or if the search logic is complex.

Results in very poor performance for objects that have grown very large through repeated method calls. | +|Convert the object to a object, and perform modifications on the object.|Useful if the number of modifications is small.|Negates the performance benefit of the class if the number of modifications is large.| + + Let's examine these techniques in greater detail. + +- If the goal of the search is to determine whether a particular substring exists (that is, if you aren't interested in the position of the substring), you can search strings before storing them in the object. The following example provides one possible implementation. It defines a `StringBuilderFinder` class whose constructor is passed a reference to a object and the substring to find in the string. In this case, the example tries to determine whether recorded temperatures are in Fahrenheit or Celsius, and adds the appropriate introductory text to the beginning of the object. A random number generator is used to select an array that contains data in either degrees Celsius or degrees Fahrenheit. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern1.cs" interactive="try-dotnet" id="Snippet12"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern1.fs" id="Snippet12"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern1.vb" id="Snippet12"::: + +- Call the method to convert the object to a object. You can search the string by using methods such as or , or you can use regular expressions and the class to search for patterns. Because both and objects use UTF-16 encoding to store characters, the index positions of characters, substrings, and regular expression matches are the same in both objects. This enables you to use methods to make changes at the same position at which that text is found in the object. + + > [!NOTE] + > If you adopt this approach, you should work from the end of the object to its beginning so that you don't have to repeatedly convert the object to a string. + + The following example illustrates this approach. It stores four occurrences of each letter of the English alphabet in a object. It then converts the text to a object and uses a regular expression to identify the starting position of each four-character sequence. Finally, it adds an underscore before each four-character sequence except for the first sequence, and converts the first character of the sequence to uppercase. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern2.cs" interactive="try-dotnet" id="Snippet13"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern2.fs" id="Snippet13"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern2.vb" id="Snippet13"::: + +- Use the property to sequentially search a range of characters in a object. This approach may not be practical if the number of characters to be searched is large or the search logic is particularly complex. For the performance implications of character-by-character index-based access for very large, chunked objects, see the documentation for the property. + + The following example is identical in functionality to the previous example but differs in implementation. It uses the property to detect when a character value has changed, inserts an underscore at that position, and converts the first character in the new sequence to uppercase. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern3.cs" interactive="try-dotnet" id="Snippet14"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern3.fs" id="Snippet14"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern3.vb" id="Snippet14"::: + +- Store all the unmodified text in the object, call the method to convert the object to a object, and perform the modifications on the object. You can use this approach if you have only a few modifications; otherwise, the cost of working with immutable strings may negate the performance benefits of using a object. + + The following example is identical in functionality to the previous two examples but differs in implementation. It creates a object, converts it to a object, and then uses a regular expression to perform all remaining modifications on the string. The method uses a lambda expression to perform the replacement on each match. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern4.cs" interactive="try-dotnet" id="Snippet15"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern4.fs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern4.vb" id="Snippet15"::: + + +## Converting the StringBuilder object to a string + You must convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. You perform this conversion by calling the method. For an illustration, see the previous example, which calls the method to convert a object to a string so that it can be passed to a regular expression method. + + + +## Examples + The following example shows how to call many of the methods defined by the class. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringBuilder/cpp/StringBuilder.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/StringBuilder.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/StringBuilder.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringBuilder/VB/StringBuilder.vb" id="Snippet1"::: + + ]]> + + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Initializes a new instance of the class. + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + + Initializes a new instance of the class. + + , and the capacity is set to the implementation-specific default capacity. + + + +## Examples + The following example demonstrates how to call the constructor with no parameters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + + + + The suggested starting size of this instance. + Initializes a new instance of the class using the specified capacity. + + property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + + The string value of this instance is set to . If `capacity` is zero, the implementation-specific default capacity is used. + + + +## Examples + The following example demonstrates how to call the constructor with a specified capacity. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet3"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet3"::: + + ]]> + + + is less than zero. + + + + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + + + + The string used to initialize the value of the instance. If is , the new will contain the empty string (that is, it contains ). + Initializes a new instance of the class using the specified string. + + will contain the empty string (that is, it contains ). + + + +## Examples + The following example demonstrates how to call the constructor with the specified string. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet4"::: + + ]]> + + + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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>] + + + + + + + + The suggested starting size of the . + The maximum number of characters the current string can contain. + Initializes a new instance of the class that starts with a specified capacity and can grow to a specified maximum. + + property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + + If `capacity` is zero, the implementation-specific default capacity is used. + + The `maxCapacity` property defines the maximum number of characters that the current instance can hold. Its value is assigned to the property. If the number of characters to be stored in the current instance exceeds this `maxCapacity` value, the object does not allocate additional memory, but instead throws an exception. + + + +## Examples + The following example demonstrates how to call the constructor with a specified capacity and maximum capacity. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet5"::: + + ]]> + + + is less than one, is less than zero, or is greater than . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + + + + + The string used to initialize the value of the instance. If is , the new will contain the empty string (that is, it contains ). + The suggested starting size of the . + Initializes a new instance of the class using the specified string and capacity. + + property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + + If `capacity` is zero, the implementation-specific default capacity is used. + + + +## Examples + The following example demonstrates how to call the constructor with an initial string and a specified capacity. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet7"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet7"::: + + ]]> + + + is less than zero. + + + + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + + + + + + + The string that contains the substring used to initialize the value of this instance. If is , the new will contain the empty string (that is, it contains ). + The position within where the substring begins. + The number of characters in the substring. + The suggested starting size of the . + Initializes a new instance of the class from the specified substring and capacity. + + property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + + If `capacity` is zero, the implementation-specific default capacity is used. + + + +## Examples + The following example demonstrates how to call the constructor with the specified string. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet6"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet6"::: + + ]]> + + + is less than zero. + + -or- + + plus is not a position within . + + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Appends the string representation of a specified object to this instance. + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + The Boolean value to append. + Appends the string representation of a specified Boolean value to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet2"::: + + The method calls the method to get the string representation of `value`. The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 8-bit unsigned integer to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet3"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + The UTF-16-encoded code unit to append. + Appends the string representation of a specified object to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet4"::: + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The array of characters to append. + Appends the string representation of the Unicode characters in a specified array to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet6"::: + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified decimal number to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet8"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet8"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified double-precision floating-point number to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet9"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet9"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet9"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 16-bit signed integer to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet10"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet10"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 32-bit signed integer to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet11"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet11"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 64-bit signed integer to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet12"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet12"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet12"::: + + The method calls the to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The object to append. + Appends the string representation of a specified object to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. It defines a `Dog` class, creates a `Dog` object, and makes three calls to the method to create a string that contains the dog's name and breed. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append4.cs" interactive="try-dotnet" id="Snippet18"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append4.fs" id="Snippet18"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append4.vb" id="Snippet18"::: + + The method calls the method to get the string representation of `value`. If `value` is `null`, no changes are made to the object. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Text.StringBuilder + + + + + + The read-only character memory region to append. + Appends the string representation of a specified read-only character memory region to this instance. + A reference to this instance after the append operation is completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Text.StringBuilder + + + + + + The read-only character span to append. + Appends the string representation of a specified read-only character span to this instance. + A reference to this instance after the append operation is completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 8-bit signed integer to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet13"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet13"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet13"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified single-precision floating-point number to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" id="Snippet14"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet14"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet14"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The string to append. + Appends a copy of the specified string to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet2"::: + + If `value` is `null`, no changes are made. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The string builder to append. + Appends the string representation of a specified string builder to this instance. + A reference to this instance after the append operation is completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")] + [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")>] + + + + + + The interpolated string to append. + Appends the specified interpolated string to this instance. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 16-bit unsigned integer to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet15"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet15"::: + + The method calls the method to get the string representation of `value`. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 32-bit unsigned integer to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet16"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet16"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet16"::: + + The calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 64-bit unsigned integer to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet17"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet17"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet17"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + + The character to append. + The number of times to append . + Appends a specified number of copies of the string representation of a Unicode character to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet5"::: + + The capacity of this instance is adjusted as needed. + + ]]> + + + is less than zero. + + -or- + + Enlarging the value of this instance would exceed . + Out of memory. + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 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.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Text.StringBuilder + + + + + + + A pointer to an array of characters. + The number of characters in the array. + Appends an array of Unicode characters starting at a specified address to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object. + + The capacity of this instance is adjusted as needed. + + ]]> + + + + is less than zero. + + -or- + + Enlarging the value of this instance would exceed . + + is a null pointer. + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + Method + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })] + [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })>] + + + + + + An object that supplies culture-specific formatting information. + The interpolated string to append. + Appends the specified interpolated string to this instance using the specified format. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + A character array. + The starting position in . + The number of characters to append. + Appends the string representation of a specified subarray of Unicode characters to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet7"::: + + The capacity of this instance is adjusted as needed. + + ]]> + + + is , and and are not zero. + + is less than zero. + + -or- + + is less than zero. + + -or- + + + is greater than the length of . + + -or- + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + The string that contains the substring to append. + The starting position of the substring within . + The number of characters in to append. + Appends a copy of a specified substring to this instance. + A reference to this instance after the append operation has completed. + + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet19"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet19"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet19"::: + + The capacity of this instance is adjusted as needed. + + ]]> + + + is , and and are not zero. + + less than zero. + + -or- + + less than zero. + + -or- + + + is greater than the length of . + + -or- + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + The string builder that contains the substring to append. + The starting position of the substring within . + The number of characters in to append. + Appends a copy of a substring within a specified string builder to this instance. + A reference to this instance after the append operation has completed. + To be added. + + + + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding object argument. + Composite Formatting + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.StringBuilder + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + A composite format string. + An object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a single argument. + A reference to this instance with appended. Each format item in is replaced by the string representation of . + + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items. The index of the format items must be 0, to correspond to `arg0`, the single object in the parameter list of this method. The formatting process replaces each format item with the string representation of `arg0`. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + `arg0` represents the object to be formatted. Each format item in `format` is replaced with the string representation of `arg0`. If the format item includes `formatString` and `arg0` implements the interface, then `arg0.ToString(formatString, null)` defines the formatting. Otherwise, `arg0.ToString()` defines the formatting. + + If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: + + ]]> + + + is . + + is invalid. + + -or- + + The index of a format item is less than 0 (zero), or greater than or equal to 1. + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + A composite format string. + An array of objects to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array. + A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. + + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + `args` represents the objects to be formatted. Each format item in `format` is replaced with the string representation of the corresponding object in `args`. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `args[index].ToString(formatString, provider)` defines the formatting. Otherwise, `args[index].ToString()` defines the formatting. + + If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: + + ]]> + + + or is . + + is invalid. + + -or- + + The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + An object that supplies culture-specific formatting information. + A composite format string. + The object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a single argument using a specified format provider. + A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of in which any format specification is replaced by the string representation of . + + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items. The index of each format item must be zero (0) since this method includes an argument list with a single argument. The formatting process replaces each format item with the string representation of `arg0`. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . In this case, since the method has a single argument in the argument list, the value of *index* must always be 0. If it is not, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + The `provider` parameter specifies an implementation that can provide formatting information for the objects in `args`. `provider` can be any of the following: + +- A object that provides culture-specific formatting information. + +- A object that provides culture-specific formatting information for `arg0` if it is a numeric value. + +- A object that provides culture-specific formatting information for `arg0` if it is a date and time value. + +- A custom implementation that provides formatting information for `arg0`. Typically, such an implementation also implements the interface. + + If the `provider` parameter is `null`, formatting information is obtained from the current culture. + + `arg0` represents the object to be formatted. Each format item in `format` is replaced with the string representation of `arg0`. If the format item includes `formatString` and `arg0` implements the interface, then `arg0.ToString(formatString, provider)` defines the formatting. Otherwise, `arg0.ToString()` defines the formatting. + +## Examples + The following includes two calls to the method. Both use the formatting conventions of the English-United Kingdom (en-GB) culture. The first inserts the string representation of a value currency in a result string. The second inserts a value in two places in a result string, the first including only the short date string and the second the short time string. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat1.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat1.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat1.vb" id="Snippet2"::: + + ]]> + + + is . + + is invalid. + + -or- + + The index of a format item is less than 0 (zero), or greater than or equal to one (1). + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + How to: Define and Use Custom Numeric Format Providers + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + An object that supplies culture-specific formatting information. + A composite format string. + An array of objects to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array using a specified format provider. + A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. + + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + The `provider` parameter specifies an implementation that can provide formatting information for the objects in `args`. `provider` can be any of the following: + +- A object that provides culture-specific formatting information. + +- A object that provides culture-specific formatting information for numeric values in `args`. + +- A object that provides culture-specific formatting information for date and time values in `args`. + +- A custom implementation that provides formatting information for one or more of the objects in `args`. Typically, such an implementation also implements the interface. The second example in the next section illustrates an method call with a custom implementation. + + If the `provider` parameter is `null`, format provider information is obtained from the current culture. + + `args` represents the objects to be formatted. Each format item in `format` is replaced with the string representation of the corresponding object in `args`. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `args[index].ToString(formatString, provider)` defines the formatting. Otherwise, `args[index].ToString()` defines the formatting. + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: + + The following example defines a custom implementation named `CustomerFormatter` that formats a 10-digit customer number with hyphens after the fourth and seventh digits. It is passed to the method to create a string that includes the formatted customer number and customer name. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/customernumberformatter1.vb" id="Snippet1"::: + + ]]> + + + is . + + is invalid. + + -or- + + The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + How to: Define and Use Custom Numeric Format Providers + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + An object that supplies culture-specific formatting information. + A . + An array of objects to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. + Each format item is replaced by the string representation of any of the arguments using a specified format provider. + A reference to this instance after the append operation has completed. + To be added. + + is . + + is . + The index of a format item is greater than or equal to the number of supplied arguments. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 2 })>] + + + + + + An object that supplies culture-specific formatting information. + A . + A span of objects to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. + Each format item is replaced by the string representation of any of the arguments using a specified format provider. + A reference to this instance after the append operation has completed. + To be added. + + is . + The index of a format item is greater than or equal to the number of supplied arguments. + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + A composite format string. + The first object to format. + The second object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments. + A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. + + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to `arg0` and `arg1`, the two objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + `arg0` and `arg1` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of either `arg0` or `arg1`. If the format item includes `formatString` and the corresponding object implements the interface, then `arg`*x*`.ToString(formatString, provider)` defines the formatting, where *x* is the index of the argument. Otherwise, `arg`*x*`.ToString()` defines the formatting. + + If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: + + ]]> + + + is . + + is invalid. + + -or- + + The index of a format item is less than 0 (zero), or greater than or equal to 2. + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Text.StringBuilder + + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + An object that supplies culture-specific formatting information. + A composite format string. + The first object to format. + The second object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments using a specified format provider. + A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. + + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + The `provider` parameter specifies an implementation that can provide formatting information for `arg0` and `arg1`. `provider` can be any of the following: + +- A object that provides culture-specific formatting information. + +- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are numeric values. + +- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are date and time values. + +- A custom implementation that provides formatting information for `arg0` and `arg1`. Typically, such an implementation also implements the interface. + + If the `provider` parameter is `null`, format provider information is obtained from the current culture. + + `arg0` and `arg1` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of the object that has the corresponding index. If the format item includes `formatString` and the corresponding argument implements the interface, then the argument's `ToString(formatString, provider)` method defines the formatting. Otherwise, the argument's `ToString()` method defines the formatting. + + + +## Examples + The following example uses the method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only to objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat2.cs" interactive="try-dotnet" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat2.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat2.vb" id="Snippet3"::: + + ]]> + + + is . + + is invalid. + + -or- + + The index of a format item is less than 0 (zero), or greater than or equal to 2 (two). + The length of the expanded string would exceed . + + IIn .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + How to: Define and Use Custom Numeric Format Providers + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Text.StringBuilder + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + + A composite format string. + The first object to format. + The second object to format. + The third object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of three arguments. + A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. + + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to `arg0` through `arg2`, the objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + `arg0`, `arg1`, and `arg2` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of either `arg0`, `arg1`, or `arg2`, depending on the index of the format item. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `arg`*x*`.ToString(formatString, null)` defines the formatting, where *x* is the index of the argument. Otherwise, `arg`*x*`.ToString()` defines the formatting. + + If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: + + ]]> + + + is . + + is invalid. + + -or- + + The index of a format item is less than 0 (zero), or greater than or equal to 3. + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Text.StringBuilder + + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + + An object that supplies culture-specific formatting information. + A composite format string. + The first object to format. + The second object to format. + The third object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of three arguments using a specified format provider. + A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. + + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + The `provider` parameter specifies an implementation that can provide formatting information for `arg0` and `arg1`. `provider` can be any of the following: + +- A object that provides culture-specific formatting information. + +- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are numeric values. + +- A object that provides culture-specific formatting information for `arg0`, `arg1`, or `arg2` if they are date and time values. + +- A custom implementation that provides formatting information for `arg0`, `arg1`, and `arg2`. Typically, such an implementation also implements the interface. + + If the `provider` parameter is `null`, format provider information is obtained from the current culture. + + `arg0`, `arg1`, and `arg2` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of the object that has the corresponding index. If the format item includes `formatString` and the corresponding argument implements the interface, then the argument's `ToString(formatString, provider)` method defines the formatting. Otherwise, the argument's `ToString()` method defines the formatting. + + + +## Examples + The following example uses the method to illustrate the result of a Boolean `And` operation with integer values. Note that the format string includes six format items, but the method has only three items in its argument list, because each item is formatted in two different ways. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat3.cs" interactive="try-dotnet" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat3.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat3.vb" id="Snippet4"::: + + ]]> + + + is . + + is invalid. + + -or- + + The index of a format item is less than 0 (zero), or greater than or equal to 3 (three). + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + How to: Define and Use Custom Numeric Format Providers + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + The type of the first object to format. + An object that supplies culture-specific formatting information. + A . + The first object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. + Each format item is replaced by the string representation of any of the arguments using a specified format provider. + A reference to this instance after the append operation has completed. + To be added. + + is . + The index of a format item is greater than or equal to the number of supplied arguments. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + The type of the first object to format. + The type of the second object to format. + An object that supplies culture-specific formatting information. + A . + The first object to format. + The second object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. + Each format item is replaced by the string representation of any of the arguments using a specified format provider. + A reference to this instance after the append operation has completed. + To be added. + + is . + The index of a format item is greater than or equal to the number of supplied arguments. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + + The type of the first object to format. + The type of the second object to format. + The type of the third object to format. + An object that supplies culture-specific formatting information. + A . + The first object to format. + The second object to format. + The third object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. + Each format item is replaced by the string representation of any of the arguments using a specified format provider. + A reference to this instance after the append operation has completed. + To be added. + + is . + The index of a format item is greater than or equal to the number of supplied arguments. + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + The character to use as a separator. is included in the joined strings only if has more than one element. + An array that contains the strings to concatenate and append to the current instance of the string builder. + Concatenates the string representations of the elements in the provided array of objects, using the specified char separator between each member, then appends the result to the current instance of the string builder. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + The character to use as a separator. is included in the joined strings only if has more than one element. + An array that contains the strings to concatenate and append to the current instance of the string builder. + Concatenates the strings of the provided array, using the specified char separator between each string, then appends the result to the current instance of the string builder. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + The string to use as a separator. is included in the joined strings only if has more than one element. + An array that contains the strings to concatenate and append to the current instance of the string builder. + Concatenates the string representations of the elements in the provided array of objects, using the specified separator between each member, then appends the result to the current instance of the string builder. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + The string to use as a separator. is included in the joined strings only if has more than one element. + An array that contains the strings to concatenate and append to the current instance of the string builder. + Concatenates the strings of the provided array, using the specified separator between each string, then appends the result to the current instance of the string builder. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + + The type of the members of . + The character to use as a separator. is included in the concatenated and appended strings only if has more than one element. + A collection that contains the objects to concatenate and append to the current instance of the string builder. + Concatenates and appends the members of a collection, using the specified char separator between each member. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + The type of the members of . + The string to use as a separator. is included in the concatenated and appended strings only if has more than one element. + A collection that contains the objects to concatenate and append to the current instance of the string builder. + Concatenates and appends the members of a collection, using the specified separator between each member. + A reference to this instance after the append operation has completed. + To be added. + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Appends the default line terminator, or a copy of a specified string and the default line terminator, to the end of this instance. + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + Appends the default line terminator to the end of the current object. + A reference to this instance after the append operation has completed. + + property. + + The capacity of this instance is adjusted as needed. + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendline/CPP/al.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendLine/al.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendLine/al.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendline/VB/al.vb" id="Snippet1"::: + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The string to append. + Appends a copy of the specified string followed by the default line terminator to the end of the current object. + A reference to this instance after the append operation has completed. + + property. + + The capacity of this instance is adjusted as needed. + + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")] + [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")>] + + + + + + The interpolated string to append. + Appends the specified interpolated string followed by the default line terminator to the end of the current StringBuilder object. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })] + [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })>] + + + + + + An object that supplies culture-specific formatting information. + The interpolated string to append. + Appends the specified interpolated string using the specified format, followed by the default line terminator, to the end of the current StringBuilder object. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + Property + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Int32 + + + Gets or sets the maximum number of characters that can be contained in the memory allocated by the current instance. + The maximum number of characters that can be contained in the memory allocated by the current instance. Its value can range from to . + + does not affect the string value of the current instance. can be decreased as long as it is not less than . + + The dynamically allocates more space when required and increases accordingly. For performance reasons, a might allocate more memory than needed. The amount of memory allocated is implementation-specific. + + + +## Examples + The following example demonstrates the property. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: + + ]]> + + The value specified for a set operation is less than the current length of this instance. + + -or- + + The value specified for a set operation is greater than the maximum capacity. + + + + + + + + + + Property + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Char + + + + + + The position of the character. + Gets or sets the character at the specified character position in this instance. + The Unicode character at position . + + . The first character in the string is at index 0. The length of a string is the number of characters it contains. The last accessible character of a instance is at index - 1. + + is the default property of the class. In C#, it is an indexer. This means that individual characters can be retrieved from the property as shown in the following example, which counts the number of alphabetic, white-space, and punctuation characters in a string. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Chars/chars1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Chars/chars1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.chars/vb/chars1.vb" id="Snippet1"::: + +### Performance and character-based indexing + +[!INCLUDE[stringbuilder-performance-note](~/includes/stringbuilder-perf-note.md)] + + ]]> + + + is outside the bounds of this instance while setting a character. + + is outside the bounds of this instance while getting a character. + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + Removes all characters from the current instance. + An object whose is 0 (zero). + + is a convenience method that is equivalent to setting the property of the current instance to 0 (zero). + +## Examples + +The following example instantiates a object with a string, calls the method, and then appends a new string. + +:::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Clear/clear1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Clear/clear1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.clear/vb/clear1.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Void + + + + + + + + The starting position in this instance where characters will be copied from. The index is zero-based. + The writable span where characters will be copied. + The number of characters to be copied. + Copies the characters from a specified segment of this instance to a destination span. + + method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an span. + + For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an span where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Void + + + + + + + + + The starting position in this instance where characters will be copied from. The index is zero-based. + The array where characters will be copied. + The starting position in where characters will be copied. The index is zero-based. + The number of characters to be copied. + Copies the characters from a specified segment of this instance to a specified segment of a destination array. + + method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an array. The array should be a fixed size, preallocated, reusable, and possibly globally accessible. + + For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an array where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.copyto2/CPP/ct2.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/CopyTo/ct2.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/CopyTo/ct2.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.copyto2/VB/ct2.vb" id="Snippet1"::: + + ]]> + + + is . + + , , or , is less than zero. + + -or- + + is greater than the length of this instance. + + + is greater than the length of this instance. + + -or- + + + is greater than the length of . + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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 minimum capacity to ensure. + Ensures that the capacity of this instance of is at least the specified value. + The new capacity of this instance. + + method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: + + ]]> + + + is less than zero. + + -or- + + Enlarging the value of this instance would exceed . + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Boolean + + + + + + The character span to compare with the current instance. + Returns a value indicating whether the characters in this instance are equal to the characters in a specified read-only character span. + + if the characters in this instance and are the same; otherwise, . + + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Boolean + + + + + + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] + [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] + + + + + + An object to compare with this instance, or . + Returns a value indicating whether this instance is equal to a specified object. + + if this instance and have equal string, , and values; otherwise, . + + , and values. The `Equals` method uses ordinal comparison to determine whether the strings are equal. + +**.NET Core 3.0 and later versions:** The current instance and `sb` are equal if the strings assigned to both objects are the same. To determine equality, the `Equals` method uses ordinal comparison. The and property values are not used in the comparison. + +## Examples + The following code uses the method to check whether two objects are equal. The method is called repeatedly after small changes are made to each object, and the results are displayed to the console. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder+ChunkEnumerator + + + + Returns an object that can be used to iterate through the chunks of characters represented in a created from this instance. + An enumerator for the chunks in the . + + chunk in sb.GetChunks()) + foreach(char ch in chunk.Span) + { /* operations on ch */ } +``` + +The purpose of this method is to efficiently extract the data of a *constant* . If the is modified while the chunk enumeration is incomplete, the result is undefined. is also not thread-safe, so operating on it with concurrent threads is illegal. + +The chunks returned are not guaranteed to remain unchanged if the is modified, so do not cache them for later use. + +Creating a from a (as the method does in the previous example) is expensive, so create a local variable for the span if you need to use it in a nested `for` statement. For example: + +```csharp +foreach (ReadOnlyMemory chunk in sb.GetChunks()) +{ + var span = chunk.Span; + for(int i = 0; i < span.Length; i++) + { + /* operations on span[i] */ + } +} +``` + + ]]> + + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Inserts the string representation of a specified object into this instance at a specified character position. + + method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.insert/CPP/insert.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Insert/insert.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Insert/insert.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.insert/VB/insert.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a Boolean value into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a specified 8-bit unsigned integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a specified Unicode character into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + + -or- + + Enlarging the value of this instance would exceed . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The position in this instance where insertion begins. + The character array to insert. + Inserts the string representation of a specified array of Unicode characters into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is not changed. + + ]]> + + + is less than zero or greater than the length of this instance. + + -or- + + Enlarging the value of this instance would exceed . + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a decimal number into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a double-precision floating-point number into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a specified 16-bit signed integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a specified 32-bit signed integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a 64-bit signed integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The position in this instance where insertion begins. + The object to insert, or . + Inserts the string representation of an object into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + If `value` is `null`, the value of this instance is unchanged. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The character span to insert. + Inserts the sequence of characters into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a specified 8-bit signed integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a single-precision floating point number into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The position in this instance where insertion begins. + The string to insert. + Inserts a string into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is not changed if `value` is `null`, or `value` is not `null` but its length is zero. + + ]]> + + + is less than zero or greater than the current length of this instance. + + -or- + + The current length of this object plus the length of exceeds . + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a 16-bit unsigned integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a 32-bit unsigned integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a 64-bit unsigned integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + The position in this instance where insertion begins. + The string to insert. + The number of times to insert . + Inserts one or more copies of a specified string into this instance at the specified character position. + A reference to this instance after insertion has completed. + + object is not changed if `value` is `null`, `value` is not `null` but its length is zero, or `count` is zero. + + ]]> + + + is less than zero or greater than the current length of this instance. + + -or- + + is less than zero. + The current length of this object plus the length of times exceeds . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + The position in this instance where insertion begins. + A character array. + The starting index within . + The number of characters to insert. + Inserts the string representation of a specified subarray of Unicode characters into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + + + + + is , and and are not zero. + + , , or is less than zero. + + -or- + + is greater than the length of this instance. + + -or- + + plus is not a position within . + + -or- + + Enlarging the value of this instance would exceed . + + + + + + + + + + Property + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + [set: System.Security.SecuritySafeCritical] + [<set: System.Security.SecuritySafeCritical>] + + + + System.Int32 + + + Gets or sets the length of the current object. + The length of this instance. + + object is defined by its number of objects. + + Like the property, the property indicates the length of the current string object. Unlike the property, which is read-only, the property allows you to modify the length of the string stored to the object. + + If the specified length is less than the current length, the current object is truncated to the specified length. If the specified length is greater than the current length, the end of the string value of the current object is padded with the Unicode NULL character (U+0000). + + If the specified length is greater than the current capacity, increases so that it is greater than or equal to the specified length. + + + +## Examples + The following example demonstrates the property. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: + + ]]> + + The value specified for a set operation is less than zero or greater than . + + + + + + + + + + Property + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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 + + + Gets the maximum capacity of this instance. + The maximum number of characters this instance can hold. + + . However, this value is implementation-specific and might be different in other or later implementations. You can explicitly set the maximum capacity of a object by calling the constructor. + +In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + + The zero-based position in this instance where removal begins. + The number of characters to remove. + Removes the specified range of characters from this instance. + A reference to this instance after the excise operation has completed. + + [!NOTE] +> The method modifies the value of the current instance and returns that instance. It does not create and return a new object. + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.remove/CPP/remove.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Remove/remove.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Remove/remove.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.remove/VB/remove.vb" id="Snippet1"::: + + ]]> + + If or is less than zero, or + is greater than the length of this instance. + + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Replaces all occurrences of a specified character or string in this instance with another specified character or string. + + method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.replace/CPP/replace.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Replace/replace.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Replace/replace.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.replace/VB/replace.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.StringBuilder + + + + + + + The character to replace. + The character that replaces . + Replaces all occurrences of a specified character in this instance with another specified character. + A reference to this instance with replaced by . + + instance is unchanged after the replacement. + + ]]> + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The string to replace. + The string that replaces , or . + Replaces all occurrences of a specified string in this instance with another specified string. + A reference to this instance with all instances of replaced by . + + , all occurrences of `oldValue` are removed. + + ]]> + + + is . + The length of is zero. + Enlarging the value of this instance would exceed . + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + + + + The character to replace. + The character that replaces . + The position in this instance where the substring begins. + The length of the substring. + Replaces, within a substring of this instance, all occurrences of a specified character with another specified character. + A reference to this instance with replaced by in the range from to + -1. + + object is unchanged after the replacement. + + ]]> + + + + is greater than the length of the value of this instance. + + -or- + + or is less than zero. + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + The string to replace. + The string that replaces , or . + The position in this instance where the substring begins. + The length of the substring. + Replaces, within a substring of this instance, all occurrences of a specified string with another specified string. + A reference to this instance with all instances of replaced by in the range from to + - 1. + + , all occurrences of `oldValue` are removed. + + ]]> + + + is . + The length of is zero. + + or is less than zero. + + -or- + + plus indicates a character position not within this instance. + + -or- + + Enlarging the value of this instance would exceed . + + + + + + + + + + + Method + + M:System.Runtime.Serialization.ISerializable.GetObjectData(System.Runtime.Serialization.SerializationInfo,System.Runtime.Serialization.StreamingContext) + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + + System.Void + + + + + + + The object to populate with serialization information. + The place to store and retrieve serialized data. Reserved for future use. + Populates a object with the data necessary to deserialize the current object. + + method. + + ]]> + + + is . + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Converts the value of a to a . + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.String + + + + Converts the value of this instance to a . + A string whose value is the same as this instance. + + method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. + + + +## Examples + The following example demonstrates calling the method. This example is part of a larger example provided for the class. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringBuilder/cpp/StringBuilder.cpp" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/StringBuilder.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/StringBuilder.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringBuilder/VB/StringBuilder.vb" id="Snippet5"::: + + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.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.String + + + + + + + The starting position of the substring in this instance. + The length of the substring. + Converts the value of a substring of this instance to a . + A string whose value is the same as the specified substring of this instance. + + method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. + + ]]> + + + or is less than zero. + + -or- + + The sum of and is greater than the length of the current instance. + + + + diff --git a/xml/System.Text/UTF8Encoding.xml b/xml/System.Text/UTF8Encoding.xml index 9faa2c1fc6b..ea4d56df1c8 100644 --- a/xml/System.Text/UTF8Encoding.xml +++ b/xml/System.Text/UTF8Encoding.xml @@ -1,2338 +1,2340 @@ - - - - - - - - - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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.Serializable] - [<System.Serializable>] - - - [System.Runtime.InteropServices.ComVisible(true)] - [<System.Runtime.InteropServices.ComVisible(true)>] - - - - Represents a UTF-8 encoding of Unicode characters. - - corresponds to the Windows code page 65001. For more information about the UTFs and other encodings supported by , see [Character Encoding in the .NET Framework](/dotnet/standard/base-types/character-encoding). - - You can instantiate a object in a number of ways, depending on whether you want to it to provide a byte order mark (BOM) and whether you want to enable error detection. The following table lists the constructors and the property that return a object. - -|Member|BOM|Error detection| -|------------|---------|---------------------| -||Yes|No (Replacement fallback)| -||No|No (Replacement fallback)| -||Configurable|No (Replacement fallback)| -||Configurable|Configurable| - - 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. - - For an encoder or decoder that is able to save state information when encoding or decoding data that spans multiple blocks (such as string of 1 million characters that is encoded in 100,000-character segments), use the and properties, respectively. - - Optionally, the object provides a byte order mark (BOM), which is an array of bytes that can be prefixed to the beginning of the byte stream that results from the encoding process. If a UTF-8 encoded byte stream is prefaced with a byte order mark (BOM), it helps the decoder determine the byte order and the transformation format or UTF. Note, however, that the Unicode Standard neither requires nor recommends a BOM in UTF-8 encoded streams. For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123). - - If the encoder is configured to provide a BOM, you can retrieve it by calling the method; otherwise, the method returns an empty array. Note that, even if a object is configured for BOM support, you must include the BOM at the beginning of the encoded byte stream as appropriate; the encoding methods of the class do not do this automatically. - -> [!CAUTION] -> To enable error detection and to make the class instance more secure, you should call the constructor and set the `throwOnInvalidBytes` parameter to `true`. With error detection enabled, a method that detects an invalid sequence of characters or bytes throws an exception. Without error detection, no exception is thrown, and the invalid sequence is generally ignored. - -> [!NOTE] -> The state of a UTF-8 encoded object is not preserved if the object is serialized and deserialized using different .NET Framework versions. - - - -## Examples - The following example uses a object to encode a string of Unicode characters and store them in a byte array. The Unicode string includes two characters, Pi (U+03A0) and Sigma (U+03A3), that are outside the ASCII character range. When the encoded byte array is decoded back to a string, the Pi and Sigma characters are still present. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding Example/CPP/snippet.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/Overview/snippet.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding Example/VB/snippet.vb" id="Snippet1"::: - - The following example uses the same string as the previous example, except that it writes the encoded bytes to a file and prefixes the byte stream with a byte order mark (BOM). It then reads the file in two different ways: as a text file by using a object; and as a binary file. As you would expect, neither newly-read string includes the BOM. - - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/Overview/bom1.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding Example/VB/bom1.vb" id="Snippet2"::: - - ]]> - - - - Understanding Encodings - - - - - System.Text.Encoding.Extensions - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - - - Initializes a new instance of the class. - - - - - - - - - Constructor - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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 - - - - Initializes a new instance of the class. - - [!CAUTION] -> For security reasons, we recommend that you enable error detection by calling a constructor with a `throwOnInvalidBytes` parameter and setting its value to `true`. - - - -## Examples - The following example creates a new instance and displays its name. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor1 Example/CPP/ctor.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/.ctor/ctor.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor1 Example/VB/ctor.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - - Constructor - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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 - - - - - - - to specify that the method returns a Unicode byte order mark; otherwise, . - Initializes a new instance of the class. A parameter specifies whether to provide a Unicode byte order mark. - - [!CAUTION] -> For security reasons, you should enable error detection by calling a constructor that includes a `throwOnInvalidBytes` parameter and setting its value to `true`. - - The `encoderShouldEmitUTF8Identifier` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. If `false`, it returns a zero-length byte array. However, setting `encoderShouldEmitUTF8Identifier` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. - - - -## Examples - The following example creates a new instance and specifies that a Unicode byte order mark prefix should be emitted by the method. The method then returns the Unicode byte order mark prefix. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor2 Example/CPP/ctor-boolean.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/.ctor/ctor-boolean.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor2 Example/VB/ctor-boolean.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - - Constructor - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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 - - - - - - - - to specify that the method should return a Unicode byte order mark; otherwise, . - - to throw an exception when an invalid encoding is detected; otherwise, . - Initializes a new instance of the class. Parameters specify whether to provide a Unicode byte order mark and whether to throw an exception when an invalid encoding is detected. - - method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. If `false`, it returns a zero-length byte array. However, setting `encoderShouldEmitUTF8Identifier` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. - - If `throwOnInvalidBytes` is `true`, a method that detects an invalid byte sequence throws an exception. Otherwise, the method does not throw an exception, and the invalid sequence is ignored. - -> [!CAUTION] -> For security reasons, you should enable error detection by calling a constructor that includes a `throwOnInvalidBytes` parameter and setting that parameter to `true`. - - - -## Examples - The following example creates a new instance, specifying that the method should not emit a Unicode byte order mark prefix, and an exception should be thrown when an invalid encoding is detected. The behavior of this constructor is compared to the default constructor, which does not throw an exception when an invalid encoding is detected. The two instances encode a character array that contains two high surrogates (U+D801 and U+D802) in a row, which is an invalid character sequence; a high surrogate should always be followed by a low surrogate. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor3 Example/CPP/ctor-boolean-boolean.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/.ctor/ctor-boolean-boolean.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor3 Example/VB/ctor-boolean-boolean.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Boolean - - - - - - [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] - [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] - - - - - - The object to compare with the current instance. - Determines whether the specified object is equal to the current object. - - if is an instance of and is equal to the current object; otherwise, . - - objects are considered equal if all of the following conditions are true: - -- Both objects provide the byte order mark, or both do not. - -- Both objects use the same encoder fallback. - -- Both objects use the same decoder fallback. - - - -## Examples - The following example uses the method to test whether the current object is equal to a different object. Four objects are created and compared and the results of the comparisons are displayed. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.Equals Example/CPP/equals-object.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/Equals/equals-object.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.Equals Example/VB/equals-object.vb" id="Snippet1"::: - - ]]> - - - - - - - - System.Text.Encoding.Extensions - 4.0.0.0 - 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.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Int32 - - - - - - The span that contains the set of characters to encode. - Calculates the number of bytes produced by encoding the specified character span. - The number of bytes produced by encoding the specified character span. - - to store the resulting bytes, you call the method. To calculate the maximum size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - - 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 the 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, and the number of bytes in the preamble is not reflected in the value returned by the method. - - ]]> - - Error detection is enabled, and contains an invalid sequence of characters. - A fallback occurred (for more information, see Character Encoding in .NET). - - -and- - - is set to . - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Int32 - - - - - - The containing the set of characters to encode. - Calculates the number of bytes produced by encoding the characters in the specified . - The number of bytes produced by encoding the specified characters. - - to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - - 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 the 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, and the number of bytes in the preamble is not reflected in the value returned by the method. - - - -## Examples - The following example calls the and methods to calculate the maximum and actual number of bytes required to encode a string. It also displays the actual number of bytes required to store a byte stream with a byte order mark. - - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetByteCount/getbytecount1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getbytecount/vb/getbytecount1.vb" id="Snippet1"::: - - ]]> - - - is . - The resulting number of bytes is greater than the maximum number that can be returned as an integer. - Error detection is enabled, and contains an invalid sequence 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 - - - 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. - - method to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - - 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 the 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, and the number of bytes in the preamble is not reflected in the value returned by the method. - - ]]> - - - is . - - is less than zero. - - -or- - - The resulting number of bytes is greater than the maximum number that can be returned as an integer. - Error detection is enabled, and contains an invalid sequence of characters. - A fallback occurred (see Character Encoding in .NET for a complete explanation). - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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, you call the uses method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - - 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 the 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, and the number of bytes in the preamble is not reflected in the value returned by the method. - - - -## Examples - The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. - - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetByteCount/getbytecount2.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getbytecount/vb/getbytecount2.vb" id="Snippet2"::: - - ]]> - - - 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 integer. - Error detection is enabled, and contains an invalid sequence of characters. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - The property 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 - - mscorlib - 1.0.5000.0 - - - System.Text.Encoding.Extensions - - - netstandard - - - System.Byte[] - - - - - - The character string to encode. - Encodes the characters in a specified object into a sequence of bytes. - A byte array that contains the encoded characters in the string specified by the s parameter. - To be added. - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Int32 - - - - - - - The character span to encode. - The span to contain the resulting set of bytes. - Encodes the specified character span into the specified byte span. - The actual number of bytes written into . - - to store the resulting bytes, you call the method. To calculate the maximum size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. 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, use the or the returned by the method or the method, respectively. - - 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 the 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 method does not prepend a preamble to the beginning of a sequence of encoded 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 - - - 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, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. 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, use the or the returned by the method or the method, respectively. - - 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 the 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 method does not prepend a preamble to the beginning of a sequence of encoded bytes. - - ]]> - - - is . - - -or- - - is . - - or is less than zero. - Error detection is enabled, and contains an invalid sequence of characters. - - -or- - - is less than the resulting number of bytes. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. 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, use the or the provided by the method or the method, respectively. - - 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 the 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 method does not prepend a preamble to the beginning of a sequence of encoded bytes. - - - -## Examples - The following example uses the method to encode a range of characters from a string and stores the encoded bytes in a range of elements in a byte array. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetBytes3 Example/CPP/getbytes-string-int32-int32-byte[]-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetBytes/getbytes-string-int32-int32-byte[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetBytes3 Example/VB/getbytes-string-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 . - Error detection is enabled, and contains an invalid sequence of characters. - - -or- - - does not have enough capacity from to the end of the array to accommodate the resulting bytes. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. 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, use the or the provided by the method or the method, respectively. - - 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 the 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 method does not prepend a preamble to the beginning of a sequence of encoded bytes. - - - -## Examples - The following example uses 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetBytes1 Example/CPP/getbytes-char[]-int32-int32-byte[]-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetBytes1 Example/VB/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 . - Error detection is enabled, and contains an invalid sequence of characters. - - -or- - - does not have enough capacity from to the end of the array to accommodate the resulting bytes. - 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 - - - Calculates the number of characters produced by decoding a sequence of bytes. - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Int32 - - - - - - The span containing the set of bytes to decode. - Calculates the number of characters produced by decoding the specified byte span. - The number of characters produced by decoding the specified byte span. - - to store the resulting characters, call the method. To calculate the maximum size, call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - - ]]> - - - - - - - - - - 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 - - - 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, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - - ]]> - - - is . - - is less than zero. - - -or- - - The resulting number of bytes is greater than the maximum number that can be returned as an integer. - Error detection is enabled, and contains an invalid sequence of bytes. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - - - -## Examples - The following example uses the method to return the number of characters produced by decoding a range of elements in a byte array. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetCharCount Example/CPP/getcharcount-byte[]-int32-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetCharCount/getcharcount-byte[]-int32-int32.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetCharCount Example/VB/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 bytes is greater than the maximum number that can be returned as an integer. - Error detection is enabled, and contains an invalid sequence of bytes. - 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.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Int32 - - - - - - - The span containing the bytes to decode. - The span to contain the resulting set of characters. - Decodes the specified byte span into the specified character span. - The actual number of characters written into . - - to store the resulting characters, call the method. To calculate the maximum size, call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - - If the set of bytes to be decoded includes the byte order mark (BOM) and the span of bytes was returned by a method of a non-BOM aware type, the character `U+FFFE` is included in the span of characters returned by this method. You can remove it by calling the method. - - 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, use the or the object provided by the method or the method, respectively. - - ]]> - - - - - - - - - - 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 - - - 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, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - - 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, use the or the object provided by the method or the method, respectively. - - ]]> - - - is . - - -or- - - is . - - or is less than zero. - Error detection is enabled, and contains an invalid sequence of bytes. - - -or- - - 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.0.0 - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - - 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, use the or the provided by the method or the method, respectively. - - - -## Examples - The following example uses the method to decode a range of elements in a byte array and store the result in a character array. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetChars Example/CPP/getchars-byte[]-int32-int32-char[]-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetChars Example/VB/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 . - Error detection is enabled, and contains an invalid sequence of bytes. - - -or- - - 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.0.0 - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Text.Decoder - - - - Obtains a decoder that converts a UTF-8 encoded sequence of bytes into a sequence of Unicode characters. - A decoder that converts a UTF-8 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. - - If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the decoder is undefined and processing must stop. - - - -## Examples - The following example uses the method to obtain a UTF-8 decoder. The decoder converts a sequence of bytes into a sequence of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetDecoder Example/CPP/getdecoder-.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetDecoder/getdecoder-.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetDecoder Example/VB/getdecoder-.vb" id="Snippet1"::: - - ]]> - - - - - - - Understanding Encodings - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Text.Encoder - - - - Obtains an encoder that converts a sequence of Unicode characters into a UTF-8 encoded sequence of bytes. - A that converts a sequence of Unicode characters into a UTF-8 encoded sequence of bytes. - - method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method. However, a maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. 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. - - If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the encoder is undefined and processing must stop. - - - -## Examples - The following example uses the method to obtain an encoder to convert a sequence of characters into a UTF-8 encoded sequence of bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetEncoder Example/CPP/getencoder-.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetEncoder/getencoder-.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetEncoder Example/VB/getencoder-.vb" id="Snippet1"::: - - ]]> - - - - - - Understanding Encodings - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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 - - - - Returns the hash code for the current instance. - The hash code for the current instance. - - method to return a hash code for instances. Notice that the hash code returned by this method depends on the constructor used to create the object. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetHashCode Example/CPP/gethashcode-.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetHashCode/gethashcode-.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetHashCode Example/VB/gethashcode-.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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, you call the method. To calculate the maximum array size, you call the method. The method generally allocates 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 . For example, text in English and many other languages often needs only one UTF-8 byte to represent a character, but the number returned by has to allow for the possibility that the string to be converted will consist entirely of characters that each require four bytes. - - 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 example uses the method to return the maximum number of bytes required to encode a specified number of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetMaxByteCount Example/CPP/getmaxbytecount-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetMaxByteCount/getmaxbytecount-int32.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetMaxByteCount Example/VB/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 integer. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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, you call the method. To calculate the maximum array size, you call the method. The method generally allocates 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 example uses the method to return the maximum number of characters produced by decoding a specified number of bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetMaxCharCount Example/CPP/getmaxcharcount-int32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetMaxCharCount/getmaxcharcount-int32.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetMaxCharCount Example/VB/getmaxcharcount-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 integer. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - 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.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Byte[] - - - - Returns a Unicode byte order mark encoded in UTF-8 format, if the encoding object is configured to supply one. - A byte array containing the Unicode byte order mark, if the encoding object is configured to supply one. Otherwise, this method returns a zero-length byte array. - - object can provide a preamble, which is a byte array that can be prefixed to the sequence of bytes that result from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code point U+FEFF) helps the decoder determine the byte order and the transformation format, or UTF. The Unicode byte order mark (BOM) is serialized as 0xEF 0xBB 0xBF. Note that the Unicode Standard neither requires nor recommends the use of a BOM for UTF-8 encoded streams. - - You can instantiate a object whose method returns a valid BOM in the following ways: - -- By retrieving the object returned by the property. - -- By calling a constructor with a `encoderShouldEmitUTF8Identifier` parameter and setting its value set to `true`. - - All other objects are configured to return an empty array rather than a valid BOM. - - The BOM provide nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Often user problems might be avoided if data is consistently and properly tagged. - - For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. - - There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. - - For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123). - -> [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. - -## Examples - The following example uses the method to return the Unicode byte order mark encoded in UTF-8 format. Notice that the parameterless constructor for does not provide a preamble. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetPreamble Example/CPP/getpreamble-.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetPreamble/getpreamble-.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetPreamble Example/VB/getpreamble-.vb" id="Snippet1"::: - - The following example instantiates two objects, the first by calling the parameterless constructor, which does not provide a BOM, and the second by calling the constructor with its `encoderShouldEmitUTF8Identifier` argument set to `true`. It then calls the method to write the BOM to a file before writing a UF8-encoded string. As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first. - - :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetPreamble/getpreamble1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getpreamble/vb/getpreamble1.vb" id="Snippet1"::: - - You can also compare the files by using the `fc` command in a console window, or you can inspect the files in a text editor that includes a Hex View mode. Note that when the file is opened in an editor that supports UTF-8, the BOM is not displayed. - - ]]> - - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 4.0.0.0 - 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 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [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. - - exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - - 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, use the or the provided by the method or the method, respectively. - - - -## Examples - The following example initializes an array by calling the method to determine exactly how many bytes are required for an encoded string and then adding the size of the byte order mark (BOM). The example then calls the method to store the BOM to the array before calling the method to store the encoded bytes to the array. The example then calls the method to decode the string. - - :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetString/getstring1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getstring/vb/getstring1.vb" id="Snippet1"::: - - Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. - - ]]> - - - is . - - or is less than zero. - - -or- - - and do not denote a valid range in . - Error detection is enabled, and contains an invalid sequence of bytes. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - - is set to . - - - - - - - - - - - - - - Property - - System.Text.Encoding.Extensions - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.ReadOnlySpan<System.Byte> - - - Gets a Unicode byte order mark encoded in UTF-8 format, if this object is configured to supply one. - A byte span containing the Unicode byte order mark, if this object is configured to supply one; otherwise, the default span. - - object can provide a preamble, which is a span of bytes that can be prefixed to the sequence of bytes that result from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code point `U+FEFF`) helps the decoder determine the byte order and the transformation format, or UTF. The Unicode byte order mark (BOM) is serialized as 0xEF 0xBB 0xBF. Note that the Unicode Standard neither requires nor recommends the use of a BOM for UTF-8 encoded streams. - - You can instantiate a object whose `Preamble` is a valid BOM in the following ways: - -- By retrieving the object returned by the property. - -- By calling a constructor with an `encoderShouldEmitUTF8Identifier` parameter and setting its value set to `true`. - - All other objects are configured to return a default span rather than a valid BOM. - - The BOM provides nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Often user problems might be avoided if data is consistently and properly tagged. - - For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. - - There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. - - For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123). - -> [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. - - ]]> - - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Boolean - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - - - - - - - Method - - System.Text.Encoding.Extensions - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Boolean - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - - - - + + + + + + + + + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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.Serializable] + [<System.Serializable>] + + + [System.Runtime.InteropServices.ComVisible(true)] + [<System.Runtime.InteropServices.ComVisible(true)>] + + + + Represents a UTF-8 encoding of Unicode characters. + + corresponds to the Windows code page 65001. For more information about the UTFs and other encodings supported by , see [Character Encoding in the .NET Framework](/dotnet/standard/base-types/character-encoding). + + You can instantiate a object in a number of ways, depending on whether you want to it to provide a byte order mark (BOM) and whether you want to enable error detection. The following table lists the constructors and the property that return a object. + +|Member|BOM|Error detection| +|------------|---------|---------------------| +||Yes|No (Replacement fallback)| +||No|No (Replacement fallback)| +||Configurable|No (Replacement fallback)| +||Configurable|Configurable| + + 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. + + For an encoder or decoder that is able to save state information when encoding or decoding data that spans multiple blocks (such as string of 1 million characters that is encoded in 100,000-character segments), use the and properties, respectively. + + Optionally, the object provides a byte order mark (BOM), which is an array of bytes that can be prefixed to the beginning of the byte stream that results from the encoding process. If a UTF-8 encoded byte stream is prefaced with a byte order mark (BOM), it helps the decoder determine the byte order and the transformation format or UTF. Note, however, that the Unicode Standard neither requires nor recommends a BOM in UTF-8 encoded streams. For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123). + + If the encoder is configured to provide a BOM, you can retrieve it by calling the method; otherwise, the method returns an empty array. Note that, even if a object is configured for BOM support, you must include the BOM at the beginning of the encoded byte stream as appropriate; the encoding methods of the class do not do this automatically. + +> [!CAUTION] +> To enable error detection and to make the class instance more secure, you should call the constructor and set the `throwOnInvalidBytes` parameter to `true`. With error detection enabled, a method that detects an invalid sequence of characters or bytes throws an exception. Without error detection, no exception is thrown, and the invalid sequence is generally ignored. + +> [!NOTE] +> The state of a UTF-8 encoded object is not preserved if the object is serialized and deserialized using different .NET Framework versions. + + + +## Examples + The following example uses a object to encode a string of Unicode characters and store them in a byte array. The Unicode string includes two characters, Pi (U+03A0) and Sigma (U+03A3), that are outside the ASCII character range. When the encoded byte array is decoded back to a string, the Pi and Sigma characters are still present. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding Example/CPP/snippet.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/Overview/snippet.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding Example/VB/snippet.vb" id="Snippet1"::: + + The following example uses the same string as the previous example, except that it writes the encoded bytes to a file and prefixes the byte stream with a byte order mark (BOM). It then reads the file in two different ways: as a text file by using a object; and as a binary file. As you would expect, neither newly-read string includes the BOM. + + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/Overview/bom1.cs" interactive="try-dotnet" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding Example/VB/bom1.vb" id="Snippet2"::: + + ]]> + + + + Understanding Encodings + + + + + System.Text.Encoding.Extensions + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + + + Initializes a new instance of the class. + + + + + + + + + Constructor + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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 + + + + Initializes a new instance of the class. + + [!CAUTION] +> For security reasons, we recommend that you enable error detection by calling a constructor with a `throwOnInvalidBytes` parameter and setting its value to `true`. + + + +## Examples + The following example creates a new instance and displays its name. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor1 Example/CPP/ctor.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/.ctor/ctor.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor1 Example/VB/ctor.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + + Constructor + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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 + + + + + + + to specify that the method returns a Unicode byte order mark; otherwise, . + Initializes a new instance of the class. A parameter specifies whether to provide a Unicode byte order mark. + + [!CAUTION] +> For security reasons, you should enable error detection by calling a constructor that includes a `throwOnInvalidBytes` parameter and setting its value to `true`. + + The `encoderShouldEmitUTF8Identifier` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. If `false`, it returns a zero-length byte array. However, setting `encoderShouldEmitUTF8Identifier` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. + + + +## Examples + The following example creates a new instance and specifies that a Unicode byte order mark prefix should be emitted by the method. The method then returns the Unicode byte order mark prefix. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor2 Example/CPP/ctor-boolean.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/.ctor/ctor-boolean.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor2 Example/VB/ctor-boolean.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + + Constructor + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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 + + + + + + + + to specify that the method should return a Unicode byte order mark; otherwise, . + + to throw an exception when an invalid encoding is detected; otherwise, . + Initializes a new instance of the class. Parameters specify whether to provide a Unicode byte order mark and whether to throw an exception when an invalid encoding is detected. + + method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. If `false`, it returns a zero-length byte array. However, setting `encoderShouldEmitUTF8Identifier` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. + + If `throwOnInvalidBytes` is `true`, a method that detects an invalid byte sequence throws an exception. Otherwise, the method does not throw an exception, and the invalid sequence is ignored. + +> [!CAUTION] +> For security reasons, you should enable error detection by calling a constructor that includes a `throwOnInvalidBytes` parameter and setting that parameter to `true`. + + + +## Examples + The following example creates a new instance, specifying that the method should not emit a Unicode byte order mark prefix, and an exception should be thrown when an invalid encoding is detected. The behavior of this constructor is compared to the default constructor, which does not throw an exception when an invalid encoding is detected. The two instances encode a character array that contains two high surrogates (U+D801 and U+D802) in a row, which is an invalid character sequence; a high surrogate should always be followed by a low surrogate. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor3 Example/CPP/ctor-boolean-boolean.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/.ctor/ctor-boolean-boolean.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.ctor3 Example/VB/ctor-boolean-boolean.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Boolean + + + + + + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] + [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] + + + + + + The object to compare with the current instance. + Determines whether the specified object is equal to the current object. + + if is an instance of and is equal to the current object; otherwise, . + + objects are considered equal if all of the following conditions are true: + +- Both objects provide the byte order mark, or both do not. + +- Both objects use the same encoder fallback. + +- Both objects use the same decoder fallback. + + + +## Examples + The following example uses the method to test whether the current object is equal to a different object. Four objects are created and compared and the results of the comparisons are displayed. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.Equals Example/CPP/equals-object.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/Equals/equals-object.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.Equals Example/VB/equals-object.vb" id="Snippet1"::: + + ]]> + + + + + + + + System.Text.Encoding.Extensions + 4.0.0.0 + 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.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Int32 + + + + + + The span that contains the set of characters to encode. + Calculates the number of bytes produced by encoding the specified character span. + The number of bytes produced by encoding the specified character span. + + to store the resulting bytes, you call the method. To calculate the maximum size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. + + 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 the 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, and the number of bytes in the preamble is not reflected in the value returned by the method. + + ]]> + + Error detection is enabled, and contains an invalid sequence of characters. + A fallback occurred (for more information, see Character Encoding in .NET). + + -and- + + is set to . + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Int32 + + + + + + The containing the set of characters to encode. + Calculates the number of bytes produced by encoding the characters in the specified . + The number of bytes produced by encoding the specified characters. + + to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. + + 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 the 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, and the number of bytes in the preamble is not reflected in the value returned by the method. + + + +## Examples + The following example calls the and methods to calculate the maximum and actual number of bytes required to encode a string. It also displays the actual number of bytes required to store a byte stream with a byte order mark. + + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetByteCount/getbytecount1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getbytecount/vb/getbytecount1.vb" id="Snippet1"::: + + ]]> + + + is . + The resulting number of bytes is greater than the maximum number that can be returned as an integer. + Error detection is enabled, and contains an invalid sequence 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 + + + 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. + + method to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. + + 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 the 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, and the number of bytes in the preamble is not reflected in the value returned by the method. + + ]]> + + + is . + + is less than zero. + + -or- + + The resulting number of bytes is greater than the maximum number that can be returned as an integer. + Error detection is enabled, and contains an invalid sequence of characters. + A fallback occurred (see Character Encoding in .NET for a complete explanation). + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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, you call the uses method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. + + 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 the 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, and the number of bytes in the preamble is not reflected in the value returned by the method. + + + +## Examples + The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. + + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetByteCount/getbytecount2.cs" interactive="try-dotnet" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getbytecount/vb/getbytecount2.vb" id="Snippet2"::: + + ]]> + + + 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 integer. + Error detection is enabled, and contains an invalid sequence of characters. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + The property 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 + + mscorlib + 1.0.5000.0 + + + System.Text.Encoding.Extensions + + + netstandard + + + System.Byte[] + + + + + + The character string to encode. + Encodes the characters in a specified object into a sequence of bytes. + A byte array that contains the encoded characters in the string specified by the s parameter. + To be added. + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Int32 + + + + + + + The character span to encode. + The span to contain the resulting set of bytes. + Encodes the specified character span into the specified byte span. + The actual number of bytes written into . + + to store the resulting bytes, you call the method. To calculate the maximum size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. 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, use the or the returned by the method or the method, respectively. + + 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 the 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 method does not prepend a preamble to the beginning of a sequence of encoded 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 + + + 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, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. 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, use the or the returned by the method or the method, respectively. + + 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 the 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 method does not prepend a preamble to the beginning of a sequence of encoded bytes. + + ]]> + + + is . + + -or- + + is . + + or is less than zero. + Error detection is enabled, and contains an invalid sequence of characters. + + -or- + + is less than the resulting number of bytes. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. 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, use the or the provided by the method or the method, respectively. + + 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 the 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 method does not prepend a preamble to the beginning of a sequence of encoded bytes. + + + +## Examples + The following example uses the method to encode a range of characters from a string and stores the encoded bytes in a range of elements in a byte array. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetBytes3 Example/CPP/getbytes-string-int32-int32-byte[]-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetBytes/getbytes-string-int32-int32-byte[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetBytes3 Example/VB/getbytes-string-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 . + Error detection is enabled, and contains an invalid sequence of characters. + + -or- + + does not have enough capacity from to the end of the array to accommodate the resulting bytes. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. 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, use the or the provided by the method or the method, respectively. + + 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 the 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 method does not prepend a preamble to the beginning of a sequence of encoded bytes. + + + +## Examples + The following example uses 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetBytes1 Example/CPP/getbytes-char[]-int32-int32-byte[]-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetBytes1 Example/VB/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 . + Error detection is enabled, and contains an invalid sequence of characters. + + -or- + + does not have enough capacity from to the end of the array to accommodate the resulting bytes. + 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 + + + Calculates the number of characters produced by decoding a sequence of bytes. + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Int32 + + + + + + The span containing the set of bytes to decode. + Calculates the number of characters produced by decoding the specified byte span. + The number of characters produced by decoding the specified byte span. + + to store the resulting characters, call the method. To calculate the maximum size, call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. + + ]]> + + + + + + + + + + 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 + + + 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, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. + + ]]> + + + is . + + is less than zero. + + -or- + + The resulting number of bytes is greater than the maximum number that can be returned as an integer. + Error detection is enabled, and contains an invalid sequence of bytes. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. + + + +## Examples + The following example uses the method to return the number of characters produced by decoding a range of elements in a byte array. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetCharCount Example/CPP/getcharcount-byte[]-int32-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetCharCount/getcharcount-byte[]-int32-int32.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetCharCount Example/VB/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 bytes is greater than the maximum number that can be returned as an integer. + Error detection is enabled, and contains an invalid sequence of bytes. + 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.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Int32 + + + + + + + The span containing the bytes to decode. + The span to contain the resulting set of characters. + Decodes the specified byte span into the specified character span. + The actual number of characters written into . + + to store the resulting characters, call the method. To calculate the maximum size, call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. + + If the set of bytes to be decoded includes the byte order mark (BOM) and the span of bytes was returned by a method of a non-BOM aware type, the character `U+FFFE` is included in the span of characters returned by this method. You can remove it by calling the method. + + 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, use the or the object provided by the method or the method, respectively. + + ]]> + + + + + + + + + + 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 + + + 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, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. + + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + + 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, use the or the object provided by the method or the method, respectively. + + ]]> + + + is . + + -or- + + is . + + or is less than zero. + Error detection is enabled, and contains an invalid sequence of bytes. + + -or- + + 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.0.0 + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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, call the method. To calculate the maximum array size, call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. + + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + + 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, use the or the provided by the method or the method, respectively. + + + +## Examples + The following example uses the method to decode a range of elements in a byte array and store the result in a character array. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetChars Example/CPP/getchars-byte[]-int32-int32-char[]-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetChars Example/VB/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 . + Error detection is enabled, and contains an invalid sequence of bytes. + + -or- + + 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.0.0 + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Text.Decoder + + + + Obtains a decoder that converts a UTF-8 encoded sequence of bytes into a sequence of Unicode characters. + A decoder that converts a UTF-8 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. + + If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the decoder is undefined and processing must stop. + + + +## Examples + The following example uses the method to obtain a UTF-8 decoder. The decoder converts a sequence of bytes into a sequence of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetDecoder Example/CPP/getdecoder-.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetDecoder/getdecoder-.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetDecoder Example/VB/getdecoder-.vb" id="Snippet1"::: + + ]]> + + + + + + + Understanding Encodings + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Text.Encoder + + + + Obtains an encoder that converts a sequence of Unicode characters into a UTF-8 encoded sequence of bytes. + A that converts a sequence of Unicode characters into a UTF-8 encoded sequence of bytes. + + method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method. However, a maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. 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. + + If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the encoder is undefined and processing must stop. + + + +## Examples + The following example uses the method to obtain an encoder to convert a sequence of characters into a UTF-8 encoded sequence of bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetEncoder Example/CPP/getencoder-.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetEncoder/getencoder-.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetEncoder Example/VB/getencoder-.vb" id="Snippet1"::: + + ]]> + + + + + + Understanding Encodings + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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 + + + + Returns the hash code for the current instance. + The hash code for the current instance. + + method to return a hash code for instances. Notice that the hash code returned by this method depends on the constructor used to create the object. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetHashCode Example/CPP/gethashcode-.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetHashCode/gethashcode-.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetHashCode Example/VB/gethashcode-.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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, you call the method. To calculate the maximum array size, you call the method. The method generally allocates 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 . For example, text in English and many other languages often needs only one UTF-8 byte to represent a character, but the number returned by has to allow for the possibility that the string to be converted will consist entirely of characters that each require four bytes. + + 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 example uses the method to return the maximum number of bytes required to encode a specified number of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetMaxByteCount Example/CPP/getmaxbytecount-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetMaxByteCount/getmaxbytecount-int32.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetMaxByteCount Example/VB/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 integer. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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, you call the method. To calculate the maximum array size, you call the method. The method generally allocates 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 example uses the method to return the maximum number of characters produced by decoding a specified number of bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetMaxCharCount Example/CPP/getmaxcharcount-int32.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetMaxCharCount/getmaxcharcount-int32.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetMaxCharCount Example/VB/getmaxcharcount-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 integer. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + 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.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Byte[] + + + + Returns a Unicode byte order mark encoded in UTF-8 format, if the encoding object is configured to supply one. + A byte array containing the Unicode byte order mark, if the encoding object is configured to supply one. Otherwise, this method returns a zero-length byte array. + + object can provide a preamble, which is a byte array that can be prefixed to the sequence of bytes that result from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code point U+FEFF) helps the decoder determine the byte order and the transformation format, or UTF. The Unicode byte order mark (BOM) is serialized as 0xEF 0xBB 0xBF. Note that the Unicode Standard neither requires nor recommends the use of a BOM for UTF-8 encoded streams. + + You can instantiate a object whose method returns a valid BOM in the following ways: + +- By retrieving the object returned by the property. + +- By calling a constructor with a `encoderShouldEmitUTF8Identifier` parameter and setting its value set to `true`. + + All other objects are configured to return an empty array rather than a valid BOM. + + The BOM provide nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Often user problems might be avoided if data is consistently and properly tagged. + + For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. + + There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. + + For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123). + +> [!IMPORTANT] +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. + +## Examples + The following example uses the method to return the Unicode byte order mark encoded in UTF-8 format. Notice that the parameterless constructor for does not provide a preamble. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetPreamble Example/CPP/getpreamble-.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetPreamble/getpreamble-.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetPreamble Example/VB/getpreamble-.vb" id="Snippet1"::: + + The following example instantiates two objects, the first by calling the parameterless constructor, which does not provide a BOM, and the second by calling the constructor with its `encoderShouldEmitUTF8Identifier` argument set to `true`. It then calls the method to write the BOM to a file before writing a UF8-encoded string. As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first. + + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF8Encoding/GetPreamble/getpreamble1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getpreamble/vb/getpreamble1.vb" id="Snippet1"::: + + You can also compare the files by using the `fc` command in a console window, or you can inspect the files in a text editor that includes a Hex View mode. Note that when the file is opened in an editor that supports UTF-8, the BOM is not displayed. + + ]]> + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 4.0.0.0 + 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 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [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. + + exception. Without error detection, invalid sequences are ignored, and no exception is thrown. + + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + + 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, use the or the provided by the method or the method, respectively. + + + +## Examples + The following example initializes an array by calling the method to determine exactly how many bytes are required for an encoded string and then adding the size of the byte order mark (BOM). The example then calls the method to store the BOM to the array before calling the method to store the encoded bytes to the array. The example then calls the method to decode the string. + + :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetString/getstring1.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getstring/vb/getstring1.vb" id="Snippet1"::: + + Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. + + ]]> + + + is . + + or is less than zero. + + -or- + + and do not denote a valid range in . + Error detection is enabled, and contains an invalid sequence of bytes. + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + + is set to . + + + + + + + + + + + + + + Property + + System.Text.Encoding.Extensions + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.ReadOnlySpan<System.Byte> + + + Gets a Unicode byte order mark encoded in UTF-8 format, if this object is configured to supply one. + A byte span containing the Unicode byte order mark, if this object is configured to supply one; otherwise, the default span. + + object can provide a preamble, which is a span of bytes that can be prefixed to the sequence of bytes that result from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code point `U+FEFF`) helps the decoder determine the byte order and the transformation format, or UTF. The Unicode byte order mark (BOM) is serialized as 0xEF 0xBB 0xBF. Note that the Unicode Standard neither requires nor recommends the use of a BOM for UTF-8 encoded streams. + + You can instantiate a object whose `Preamble` is a valid BOM in the following ways: + +- By retrieving the object returned by the property. + +- By calling a constructor with an `encoderShouldEmitUTF8Identifier` parameter and setting its value set to `true`. + + All other objects are configured to return a default span rather than a valid BOM. + + The BOM provides nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Often user problems might be avoided if data is consistently and properly tagged. + + For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. + + There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. + + For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123). + +> [!IMPORTANT] +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. + + ]]> + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Boolean + + + + + + + + To be added. + To be added. + To be added. + To be added. + To be added. + To be added. + + + + + + + + + + + Method + + System.Text.Encoding.Extensions + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Boolean + + + + + + + + To be added. + To be added. + To be added. + To be added. + To be added. + To be added. + + + + + From 1ed7917ab1ba96d3802798941c7685b1a1b85dd3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20S=C3=A1nchez=20L=C3=B3pez?= <1175054+carlossanlop@users.noreply.github.com> Date: Thu, 17 Aug 2023 10:23:55 -0700 Subject: [PATCH 2/5] Range - range --- xml/System.Text/Ascii.xml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/xml/System.Text/Ascii.xml b/xml/System.Text/Ascii.xml index 3b3d848d770..b5105ded996 100644 --- a/xml/System.Text/Ascii.xml +++ b/xml/System.Text/Ascii.xml @@ -765,7 +765,8 @@ The ASCII buffer. Trims all leading and trailing ASCII whitespaces from the buffer. - The Range of the untrimmed data. + The range of the untrimmed data. + To be added. @@ -816,7 +817,8 @@ The ASCII buffer. Trims all trailing ASCII whitespaces from the buffer. - The Range of the untrimmed data. + The range of the untrimmed data. + To be added. @@ -867,7 +869,8 @@ The ASCII buffer. Trims all leading ASCII whitespaces from the buffer. - The Range of the untrimmed data. + The range of the untrimmed data. + To be added. From 5c8061abd388638293d19606cf687e610ac6234e Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 21 Aug 2023 14:07:30 -0700 Subject: [PATCH 3/5] Update StringBuilder.xml --- xml/System.Text/StringBuilder.xml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/xml/System.Text/StringBuilder.xml b/xml/System.Text/StringBuilder.xml index cae1a4cd317..a6393c54a99 100644 --- a/xml/System.Text/StringBuilder.xml +++ b/xml/System.Text/StringBuilder.xml @@ -3186,9 +3186,7 @@ A reference to this instance after the append operation has completed. To be added. - is . - - is . + or is . The index of a format item is greater than or equal to the number of supplied arguments. From fa742e2f7979a9ddfa1634b413b48f0f07887c47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20S=C3=A1nchez=20L=C3=B3pez?= <1175054+carlossanlop@users.noreply.github.com> Date: Tue, 22 Aug 2023 09:29:20 -0700 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- xml/System.Text/Ascii.xml | 48 +++++++++++++++++++---------- xml/System.Text/CompositeFormat.xml | 3 +- 2 files changed, 34 insertions(+), 17 deletions(-) diff --git a/xml/System.Text/Ascii.xml b/xml/System.Text/Ascii.xml index b5105ded996..0ce102c116e 100644 --- a/xml/System.Text/Ascii.xml +++ b/xml/System.Text/Ascii.xml @@ -42,7 +42,8 @@ The buffer to compare with . Determines whether the provided buffers contain equal ASCII characters. - if the corresponding elements in and were equal and ASCII. otherwise. + if the corresponding elements in and are equal and ASCII; otherwise. + If both buffers contain equal, but non-ASCII characters, the method returns . @@ -154,7 +155,8 @@ The buffer to compare with . Determines whether the provided buffers contain equal ASCII characters, ignoring case considerations. - if the corresponding elements in and were equal ignoring case considerations and ASCII. otherwise. + if the corresponding elements in and are equal ignoring case considerations and ASCII; otherwise. + If both buffers contain equal, but non-ASCII characters, the method returns . @@ -265,7 +267,8 @@ The source buffer from which UTF-16 text is read. The destination buffer to which ASCII text is written. - The number of bytes actually written to . It's the same as the number of chars actually read from . + When this method returns, contains the number of bytes actually written to . It's the same as the number of chars actually read from . + Copies text from a source buffer to a destination buffer, converting from UTF-16 to ASCII during the copy. An describing the result of the operation. To be added. @@ -398,7 +401,8 @@ The source buffer from which ASCII text is read. The destination buffer to which lowercase text is written. - The number of bytes actually written to . It's the same as the number of bytes actually read from . + When this method returns, contains the number of bytes actually written to . It's the same as the number of bytes actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to lowercase during the copy. An describing the result of the operation. In-place conversion is prohibited, please use for that. @@ -427,7 +431,8 @@ The source buffer from which ASCII text is read. The destination buffer to which lowercase text is written. - The number of characters actually written to . It's the same as the number of bytes actually read from . + When this method returns, contains the number of characters actually written to . It's the same as the number of bytes actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to lowercase during the copy. An describing the result of the operation. To be added. @@ -456,7 +461,8 @@ The source buffer from which ASCII text is read. The destination buffer to which lowercase text is written. - The number of bytes actually written to . It's the same as the number of characters actually read from . + When this method returns, contains the number of bytes actually written to . It's the same as the number of characters actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to lowercase during the copy. An describing the result of the operation. To be added. @@ -485,7 +491,8 @@ The source buffer from which ASCII text is read. The destination buffer to which lowercase text is written. - The number of characters actually written to . It's the same as the number of characters actually read from . + When this method returns, contains the number of characters actually written to . It's the same as the number of characters actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to lowercase during the copy. An describing the result of the operation. In-place conversion is prohibited, please use for that. @@ -512,7 +519,8 @@ The ASCII text buffer. - The number of processed bytes. + When this method returns, contains the number of processed bytes. + Performs in-place uppercase conversion. An describing the result of the operation. To be added. @@ -539,7 +547,8 @@ The ASCII text buffer. - The number of processed characters. + When this method returns, contains the number of processed characters. + Performs in-place uppercase conversion. An describing the result of the operation. To be added. @@ -568,7 +577,8 @@ The source buffer from which ASCII text is read. The destination buffer to which uppercase text is written. - The number of bytes actually written to . It's the same as the number of bytes actually read from . + When this method returns, contains the number of bytes actually written to . It's the same as the number of bytes actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to uppercase during the copy. An describing the result of the operation. In-place conversion is prohibited, please use for that. @@ -597,7 +607,8 @@ The source buffer from which ASCII text is read. The destination buffer to which uppercase text is written. - The number of characters actually written to . It's the same as the number of bytes actually read from . + When this method returns, contains the number of characters actually written to . It's the same as the number of bytes actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to uppercase during the copy. An describing the result of the operation. To be added. @@ -626,7 +637,8 @@ The source buffer from which ASCII text is read. The destination buffer to which uppercase text is written. - The number of bytes actually written to . It's the same as the number of characters actually read from . + When this method returns, contains the number of bytes actually written to . It's the same as the number of characters actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to uppercase during the copy. An describing the result of the operation. To be added. @@ -655,7 +667,8 @@ The source buffer from which ASCII text is read. The destination buffer to which uppercase text is written. - The number of characters actually written to . It's the same as the number of characters actually read from . + When this method returns, contains the number of characters actually written to . It's the same as the number of characters actually read from . + Copies text from a source buffer to a destination buffer, converting ASCII letters to uppercase during the copy. An describing the result of the operation. In-place conversion is prohibited, please use for that. @@ -682,7 +695,8 @@ The ASCII text buffer. - The number of processed bytes. + When this method returns, contains the number of processed bytes. + Performs in-place lowercase conversion. An describing the result of the operation. To be added. @@ -709,7 +723,8 @@ The ASCII text buffer. - The number of processed characters. + When this method returns, contains the number of processed characters. + Performs in-place lowercase conversion. An describing the result of the operation. To be added. @@ -738,7 +753,8 @@ The source buffer from which ASCII text is read. The destination buffer to which UTF-16 text is written. - The number of chars actually written to . It's the same as the number of bytes actually read from + When this method returns, contains the number of chars actually written to . It's the same as the number of bytes actually read from + Copies text from a source buffer to a destination buffer, converting from ASCII to UTF-16 during the copy. An describing the result of the operation. To be added. diff --git a/xml/System.Text/CompositeFormat.xml b/xml/System.Text/CompositeFormat.xml index 669fcd6ee9d..4f6f31c2d99 100644 --- a/xml/System.Text/CompositeFormat.xml +++ b/xml/System.Text/CompositeFormat.xml @@ -97,7 +97,8 @@ The string to parse. - Parse the composite format string . + Parses the specified composite format string. + The parsed . To be added. From 4f0abda65a9e83bc9cc9ca32aaf6be70006a61f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20S=C3=A1nchez=20L=C3=B3pez?= <1175054+carlossanlop@users.noreply.github.com> Date: Tue, 22 Aug 2023 12:04:41 -0600 Subject: [PATCH 5/5] Update xml/System.Text/Ascii.xml --- xml/System.Text/Ascii.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/xml/System.Text/Ascii.xml b/xml/System.Text/Ascii.xml index 0ce102c116e..3784e02d4fe 100644 --- a/xml/System.Text/Ascii.xml +++ b/xml/System.Text/Ascii.xml @@ -405,7 +405,8 @@ Copies text from a source buffer to a destination buffer, converting ASCII letters to lowercase during the copy. An describing the result of the operation. - In-place conversion is prohibited, please use for that. + The source and destination spans must not overlap. If they do, an will be thrown. If you want to mutate the span in-place, use the method instead. +