diff --git a/xml/System.Text.RegularExpressions/GroupCollection.xml b/xml/System.Text.RegularExpressions/GroupCollection.xml index 1c3f3813433..01226c15790 100644 --- a/xml/System.Text.RegularExpressions/GroupCollection.xml +++ b/xml/System.Text.RegularExpressions/GroupCollection.xml @@ -1614,7 +1614,7 @@ This member is an explicit interface member implementation. It can be used only The group to locate in the group collection. Determines the index of a specific group in the group collection. - The index of the if found; otherwise, -1. + The index of the if found; otherwise, -1. 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. - + 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. +> 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"::: @@ -128,27 +128,27 @@ 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. - +> 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. - +> 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"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.ASCIIEncoding.ctor Example/VB/ctor.vb" id="Snippet1"::: + ]]> @@ -199,11 +199,11 @@ 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. - + 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. + ]]> @@ -258,29 +258,29 @@ 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 . - + 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"::: - + :::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- - + + -and- + is set to . @@ -346,26 +346,26 @@ 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. - + 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- - + 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- - + + -and- + is set to . @@ -426,38 +426,38 @@ 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 . - + 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"::: - + :::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- - + 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- - + + -and- + is set to . @@ -512,17 +512,17 @@ 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 ("?"). - + 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. +> For security reasons, you should use , , or and enable error detection. ]]> @@ -590,35 +590,35 @@ 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 ("?"). - + 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. - +> For security reasons, your application is recommended to use , , or and enable error detection. + ]]> - is . - - -or- - + 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- - + + -and- + is set to . @@ -683,23 +683,23 @@ 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 ("?"). - + 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. - +> 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"::: @@ -707,27 +707,27 @@ ]]> - is . - - -or- - + is . + + -or- + is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + + -and- + is set to . @@ -784,7 +784,7 @@ - The containing the set of characters to encode. + 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. @@ -792,23 +792,21 @@ 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 ("?"). - + 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. - +> For security reasons, it's 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"::: @@ -816,27 +814,23 @@ ]]> - is . - - -or- - - is . + or is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + + -and- + is set to . @@ -889,11 +883,11 @@ 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. - + 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. + ]]> @@ -956,26 +950,26 @@ 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. - + 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- - + 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- - + + -and- + is set to . @@ -1036,38 +1030,38 @@ 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. - + 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"::: - + :::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- - + 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- - + + -and- + is set to . @@ -1122,18 +1116,18 @@ 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 ("?"). - + 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. - +> For security reasons, you should use , , or and enable error detection. + ]]> @@ -1200,35 +1194,35 @@ 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 ("?"). - + 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. - +> For security reasons, your application is recommended to use , , or and enable error detection. + ]]> - is . - - -or- - + 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- - + + -and- + is set to . @@ -1294,51 +1288,51 @@ 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 ("?"). - + 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. - +> 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"::: - + :::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- + is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + + -and- + is set to . @@ -1392,11 +1386,11 @@ 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. - + 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. + ]]> @@ -1453,11 +1447,11 @@ 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. - + 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. + ]]> @@ -1511,36 +1505,36 @@ 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 . - + 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. - +> `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"::: - + :::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- - + is less than zero. + + -or- + The resulting number of bytes is greater than the maximum number that can be returned as an integer. @@ -1591,34 +1585,34 @@ 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 . - + 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. - +> `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"::: - + :::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- - + is less than zero. + + -or- + The resulting number of bytes is greater than the maximum number that can be returned as an integer. @@ -1711,21 +1705,19 @@ 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 ("?"). - + 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 . - +> 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"::: @@ -1735,15 +1727,15 @@ is . - or is less than zero. - - -or- - - and do not denote a valid range in . + 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- - + + -and- + is set to . @@ -1796,11 +1788,11 @@ 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. - + 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. + ]]> diff --git a/xml/System.Text/Decoder.xml b/xml/System.Text/Decoder.xml index d0b6358745a..d869e58dd73 100644 --- a/xml/System.Text/Decoder.xml +++ b/xml/System.Text/Decoder.xml @@ -1178,7 +1178,7 @@ The following example uses the method to c -or- - and do not denote a valid range in . + and do not denote a valid range in . -or- @@ -1276,7 +1276,7 @@ The following example uses the method to c -or- - and do not denote a valid range in . + and do not denote a valid range in . -or- diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index ff4dfa91a42..e8d9d04d1a1 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -2466,7 +2466,7 @@ The returned 's and and do not denote a valid range in . + and do not denote a valid range in . -or- @@ -3339,7 +3339,7 @@ The returned 's and and do not denote a valid range in . + and do not denote a valid range in . -or- diff --git a/xml/System.Text/EncodingProvider.xml b/xml/System.Text/EncodingProvider.xml index 96b6c490722..0a202e72cc3 100644 --- a/xml/System.Text/EncodingProvider.xml +++ b/xml/System.Text/EncodingProvider.xml @@ -406,7 +406,7 @@ This method is called by the [Encoding.GetEncoding(String)](, or the `decoderExceptionFallback` argument is an instance of , the encoding method throws an exception if characters cannot be encoded, and the decoding method throws an exception if a byte sequence cannot be decoded. @@ -416,9 +416,6 @@ This method is called by the [Encoding.GetEncoding(String)]( - - Because calls to this method use your implementation of the method, you do not have to override it. When user code attempts to retrieve an encoding by calling the method, the method passes the identifier to every registered encoding provider until one returns a valid encoding. If none returns a valid encoding, the method attempts to retrieve a cached encoding whose code page identifier is . Because of this, if you do choose to override the method, your override should return if is not the code page identifier of an encoding that you support; it should never throw an exception. - This method is called by the method. You should not call it directly from user code. diff --git a/xml/System.Text/Rune.xml b/xml/System.Text/Rune.xml index 92477925073..8b68f1769e4 100644 --- a/xml/System.Text/Rune.xml +++ b/xml/System.Text/Rune.xml @@ -190,10 +190,10 @@ 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 high surrogate code point. + +-or- + does not represent a UTF-16 low surrogate code point. @@ -228,8 +228,8 @@ 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 . + 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. @@ -267,19 +267,19 @@ 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 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. - + if the data was not successfully decoded. This pattern provides convenient automatic U+FFFD substitution of invalid sequences while iterating through the loop. + ]]> @@ -317,19 +317,19 @@ The general convention is to call this method in a loop, slicing the `source` bu 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 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. - + if the data could not be successfully decoded. This pattern provides convenient automatic U+FFFD substitution of invalid sequences while iterating through the loop. + ]]> @@ -367,19 +367,19 @@ The general convention is to call this method in a loop, slicing the `source` bu 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. + 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. - + , 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. + ]]> @@ -417,19 +417,19 @@ This method is very similar to 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. + 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. - + , 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. + ]]> @@ -637,12 +637,12 @@ This method is very similar to 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. - + . Refer to that documentation for more information. + ]]> @@ -679,12 +679,12 @@ This method has behavior equivalent to Gets the that begins at a specified position in a string. The rune obtained from at the specified . - @@ -725,12 +725,12 @@ Throws an exception if `input` is `null`, `index` is out of range, or `index` do Gets the Unicode category associated with the specified rune. The Unicode category associated with . - . Refer to that documentation for more information. - + . Refer to that documentation for more information. + ]]> @@ -824,16 +824,16 @@ This method has behavior equivalent to 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 . - + 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 . + ]]> @@ -869,14 +869,14 @@ For more information, see if is a decimal digit; otherwise, . - and comparing the result against . - -For more information, see . - + and comparing the result against . + +For more information, see . + ]]> @@ -912,14 +912,14 @@ For more information, see if is a letter; otherwise, . - and comparing the result against any of the values , , , , and . - -For more information, see . - + and comparing the result against any of the values , , , , and . + +For more information, see . + ]]> @@ -955,14 +955,14 @@ For more information, see if is a letter or a decimal digit; otherwise, . - and comparing the result against any of the values , , , , , and . - -For more information, see . - + and comparing the result against any of the values , , , , , and . + +For more information, see . + ]]> @@ -998,15 +998,15 @@ For more information, see if is a lowercase letter; otherwise, . - -and comparing the result against . - -For more information, see . - + +and comparing the result against . + +For more information, see . + ]]> @@ -1042,14 +1042,14 @@ For more information, see if is a number; otherwise, . - and comparing the result against any of the values , , and . - -For more information, see . - + and comparing the result against any of the values , , and . + +For more information, see . + ]]> @@ -1085,14 +1085,14 @@ For more information, see if is a punctuation mark; otherwise, . - and comparing the result against any of the values , , , , , , and . - -For more information, see . - + and comparing the result against any of the values , , , , , , and . + +For more information, see . + ]]> @@ -1128,14 +1128,14 @@ For more information, see if is a separator character; otherwise, . - and comparing the result against any of the values , , and . - -For more information, see . - + and comparing the result against any of the values , , and . + +For more information, see . + ]]> @@ -1171,14 +1171,14 @@ For more information, see if is a symbol character; otherwise, . - and comparing the result against any of the values , , , and . - -For more information, see . - + and comparing the result against any of the values , , , and . + +For more information, see . + ]]> @@ -1214,14 +1214,14 @@ For more information, see if is an uppercase letter; otherwise,. - and comparing the result against . - -For more information, see . - + and comparing the result against . + +For more information, see . + ]]> @@ -1329,14 +1329,14 @@ For more information, see 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 . - + 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 . + ]]> @@ -1747,16 +1747,16 @@ For more information, see 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 . + 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. - + instance is cast to an interface. + ]]> @@ -1789,11 +1789,11 @@ This member is an explicit interface member implementation. It can be used only - The format to use. - -or- + 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- + 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. @@ -2218,12 +2218,12 @@ This member is an explicit interface member implementation. It can be used only 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. - + property can be queried ahead of time to determine the required size of the `destination` buffer. + ]]> @@ -2261,12 +2261,12 @@ The property can be queried ahead of 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. - + property can be queried ahead of time to determine the required size of the `destination` buffer. + ]]> @@ -2306,12 +2306,12 @@ The property can be queried ahead of if a scalar value was successfully extracted from the specified index; if a value could not be extracted because of invalid data. - @@ -2346,12 +2346,12 @@ Throws an exception if `input` is `null` or `index` is out of range. 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. - @@ -2382,12 +2382,12 @@ The return value will be 1 or 2. 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. - diff --git a/xml/System.Text/StringBuilder.xml b/xml/System.Text/StringBuilder.xml index 9518f0f869d..cde9833f26e 100644 --- a/xml/System.Text/StringBuilder.xml +++ b/xml/System.Text/StringBuilder.xml @@ -7067,7 +7067,7 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti The read-only character span to replace. The read-only character span to replace with. Replaces all instances of one read-only character span with another in this builder. - A reference to this instance with replaced by . + A reference to this instance with replaced by . If is empty, instances of are removed from this builder. @@ -7262,7 +7262,7 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti The index to start in this builder. The number of characters to read in this builder. Replaces all instances of one read-only character span with another in part of this builder. - A reference to this instance with replaced by . + A reference to this instance with replaced by . If is empty, instances of are removed from this builder. diff --git a/xml/System.Text/UTF32Encoding.xml b/xml/System.Text/UTF32Encoding.xml index 6062d4bb39e..ac1e306372c 100644 --- a/xml/System.Text/UTF32Encoding.xml +++ b/xml/System.Text/UTF32Encoding.xml @@ -55,70 +55,70 @@ Represents a UTF-32 encoding of Unicode characters. - , see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - - The class represents a UTF-32 encoding. The encoder 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 (code point U+0041) is serialized as follows (in hexadecimal): - -- Big endian byte order: 00 00 00 41 - -- 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. corresponds to the Windows code pages 12000 (little endian byte order) and 12001 (big endian byte order). You can determine the "endianness" of a particular architecture by calling the method. - - Optionally, the object provides a byte order mark (BOM), which 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 (BOM), it helps the decoder determine the byte order and the transformation format or UTF of a byte array. - - If the instance 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 instantiate a object by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. With error detection, 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. - - You can instantiate a object in a number of ways, depending on whether you want to it to provide a byte order mark (BOM), whether you want big-endian or little-endian encoding, and whether you want to enable error detection. The following table lists the constructors and the properties that return a object. - -|Member|Endianness|BOM|Error detection| -|------------|----------------|---------|---------------------| -||Little-endian|Yes|No (Replacement fallback)| -||Little-endian|Yes|No (Replacement fallback)| -||Configurable|Configurable|No (Replacement fallback)| -||Configurable|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. - - - -## Examples - The following example demonstrates the behavior of objects with and without error detection enabled. It creates a byte array whose last four bytes represent an invalid surrogate pair; the high surrogate U+D8FF is followed by an U+01FF, which is outside the range of low surrogates (0xDC00 through 0xDFFF). Without error detection, the UTF32 decoder uses replacement fallback to replace the invalid surrogate pair with REPLACEMENT CHARACTER (U+FFFD). - + + The class represents a UTF-32 encoding. The encoder 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 (code point U+0041) is serialized as follows (in hexadecimal): + +- Big endian byte order: 00 00 00 41 + +- 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. corresponds to the Windows code pages 12000 (little endian byte order) and 12001 (big endian byte order). You can determine the "endianness" of a particular architecture by calling the method. + + Optionally, the object provides a byte order mark (BOM), which 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 (BOM), it helps the decoder determine the byte order and the transformation format or UTF of a byte array. + + If the instance 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 instantiate a object by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. With error detection, 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. + + You can instantiate a object in a number of ways, depending on whether you want to it to provide a byte order mark (BOM), whether you want big-endian or little-endian encoding, and whether you want to enable error detection. The following table lists the constructors and the properties that return a object. + +|Member|Endianness|BOM|Error detection| +|------------|----------------|---------|---------------------| +||Little-endian|Yes|No (Replacement fallback)| +||Little-endian|Yes|No (Replacement fallback)| +||Configurable|Configurable|No (Replacement fallback)| +||Configurable|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. + + + +## Examples + The following example demonstrates the behavior of objects with and without error detection enabled. It creates a byte array whose last four bytes represent an invalid surrogate pair; the high surrogate U+D8FF is followed by an U+01FF, which is outside the range of low surrogates (0xDC00 through 0xDFFF). Without error detection, the UTF32 decoder uses replacement fallback to replace the invalid surrogate pair with REPLACEMENT CHARACTER (U+FFFD). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF32Encoding.ErrorDetection/CPP/errordetection.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/Overview/errordetection.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.ErrorDetection/VB/ErrorDetection.vb" id="Snippet1"::: - - The following example encodes a string of Unicode characters into a byte array by using a object. The byte array is then decoded into a string to demonstrate that there is no loss of data. - + + The following example encodes a string of Unicode characters into a byte array by using a object. The byte array is then decoded into a string to demonstrate that there is no loss of data. + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/Overview/snippet.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf32encoding.class/vb/snippet.vb" id="Snippet1"::: - - The following example uses the same string as the previous one, 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. - + + The following example uses the same string as the previous one, 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/UTF32Encoding/Overview/bom1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf32encoding.class/vb/bom1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf32encoding.class/vb/bom1.vb" id="Snippet2"::: + ]]> @@ -177,23 +177,23 @@ Initializes a new instance of the class. - [!CAUTION] -> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidCharacters` argument to `true`. - - - -## Examples - The following example retrieves and displays the byte order mark for different instances. - +> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidCharacters` argument to `true`. + + + +## Examples + The following example retrieves and displays the byte order mark for different instances. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetPreamble/CPP/getpreamble.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/.ctor/getpreamble.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetPreamble/VB/GetPreamble.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetPreamble/VB/GetPreamble.vb" id="Snippet1"::: + ]]> @@ -241,21 +241,21 @@ to specify that a Unicode byte order mark is provided; otherwise, . Initializes a new instance of the class. Parameters specify whether to use the big endian byte order and whether the method returns a Unicode byte order mark. - [!CAUTION] -> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidCharacters` argument to `true`. - -## Examples - The following example retrieves and displays the byte order mark for different instances. - +> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidCharacters` argument to `true`. + +## Examples + The following example retrieves and displays the byte order mark for different instances. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetPreamble/CPP/getpreamble.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/.ctor/getpreamble.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetPreamble/VB/GetPreamble.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetPreamble/VB/GetPreamble.vb" id="Snippet1"::: + ]]> @@ -307,21 +307,21 @@ to specify that an exception should be thrown when an invalid encoding is detected; otherwise, . Initializes a new instance of the class. Parameters specify whether to use the big endian byte order, whether to provide a Unicode byte order mark, and whether to throw an exception when an invalid encoding is detected. - . Otherwise, the method does not throw an exception, and the invalid sequence is ignored. - + . 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 the constructor and setting its `throwOnInvalidCharacters` argument to `true`. - -## Examples - The following example demonstrates the behavior of , both with error detection enabled and without. - + +## Examples + The following example demonstrates the behavior of , both with error detection enabled and without. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF32Encoding.ErrorDetection/CPP/errordetection.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/Overview/errordetection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.ErrorDetection/VB/ErrorDetection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.ErrorDetection/VB/ErrorDetection.vb" id="Snippet1"::: + ]]> @@ -379,28 +379,28 @@ 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 use the same byte order. - -- 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 creates objects using different parameter values and then checks them for equality. - + objects are considered equal if all of the following conditions are true: + +- Both objects use the same byte order. + +- 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 creates objects using different parameter values and then checks them for equality. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF32Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/Equals/equals.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.Equals/VB/equals.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.Equals/VB/equals.vb" id="Snippet1"::: + ]]> @@ -466,23 +466,23 @@ 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 a . 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. - + 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 a . 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/UTF32Encoding/GetByteCount/getbytecount1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf32encoding.getbytecount/vb/getbytecount1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf32encoding.getbytecount/vb/getbytecount1.vb" id="Snippet1"::: + ]]> @@ -490,9 +490,9 @@ 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- - + + -and- + is set to . @@ -553,30 +553,30 @@ 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, you call the method. To calculate the maximum array size, you call the . The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw an . 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 a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. - + to store the resulting bytes, you call the method. To calculate the maximum array size, you call the . The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw an . 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 a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. + ]]> is . - is less than zero. - - -or- - + 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 (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -636,42 +636,42 @@ 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 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 a . 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 a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, 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. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic 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 Cyrillic 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 a . 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 a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, 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. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic 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 Cyrillic characters. + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetByteCount/getbytecount2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf32encoding.getbytecount/vb/getbytecount2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf32encoding.getbytecount/vb/getbytecount2.vb" id="Snippet2"::: + ]]> is . - or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + + -and- + is set to . @@ -746,37 +746,37 @@ 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. - 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 a . Without error detection, invalid sequences are ignored, and no exception is thrown. - - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. - + 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 a . Without error detection, invalid sequences are ignored, and no exception is thrown. + + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. + > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. - +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. + ]]> - is . - - -or- - + is . + + -or- + is . or is less than zero. - Error detection is enabled, and contains an invalid sequence of characters. - - -or- - + 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- - + + -and- + is set to . @@ -840,52 +840,52 @@ 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 a . Without error detection, invalid sequences are ignored, and no exception is thrown. - - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. - + 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 a . Without error detection, invalid sequences are ignored, and no exception is thrown. + + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. + > [!IMPORTANT] > To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. - -## Examples - The following example determines the number of bytes required to encode three characters from a character array, then encodes the characters and displays the resulting bytes. - + +## Examples + The following example determines the number of bytes required to encode three characters from a character array, then encodes the characters and displays the resulting bytes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetBytes/getbytes_chararr.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetBytes_CharArr/VB/GetBytes_CharArr.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetBytes_CharArr/VB/GetBytes_CharArr.vb" id="Snippet1"::: + ]]> - is . - - -or- - + is . + + -or- + is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + 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- - + + -and- + is set to . @@ -949,52 +949,52 @@ 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 a . Without error detection, invalid sequences are ignored, and no exception is thrown. - - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. - + 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 a . Without error detection, invalid sequences are ignored, and no exception is thrown. + + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. + > [!IMPORTANT] > To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting a preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. - -## Examples - The following example determines the number of bytes required to encode a string, then encodes the string and displays the resulting bytes. - + +## Examples + The following example determines the number of bytes required to encode a string, then encodes the string and displays the resulting bytes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetBytes/getbytes_string.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetBytes_String/VB/GetBytes_String.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetBytes_String/VB/GetBytes_String.vb" id="Snippet1"::: + ]]> - is . - - -or- - + is . + + -or- + is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + 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- - + + -and- + is set to . @@ -1065,28 +1065,28 @@ 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. - calculates the exact array size required by the method to store the resulting characters. 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 a . Without error detection, invalid sequences are ignored, and no exception is thrown. - + calculates the exact array size required by the method to store the resulting characters. 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 a . Without error detection, invalid sequences are ignored, and no exception is thrown. + ]]> is . - is less than zero. - - -or- - + 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- - + + -and- + is set to . @@ -1146,41 +1146,41 @@ 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. - method calculates the exact array size required by the method to store the resulting characters. 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 a . Without error detection, invalid sequences are ignored, and no exception is thrown. - - - -## Examples - The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. - + method calculates the exact array size required by the method to store the resulting characters. 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 a . Without error detection, invalid sequences are ignored, and no exception is thrown. + + + +## 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.UTF32Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetCharCount/getchars.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetChars/VB/GetChars.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetChars/VB/GetChars.vb" id="Snippet1"::: + ]]> is . - or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + + -and- + is set to . @@ -1255,36 +1255,36 @@ 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 a . 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, the application uses the or the provided by the method or the method, respectively. - + 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 a . 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, the application uses the or the provided by the method or the method, respectively. + ]]> - is . - - -or- - + is . + + -or- + is . or is less than zero. - Error detection is enabled, and contains an invalid sequence of bytes. - - -or- - + 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- - + + -and- + is set to . @@ -1349,53 +1349,53 @@ 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 a . 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, the application uses the or the provided by the method or the method, respectively. - - - -## Examples - The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. - + 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 a . 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, the application uses the or the provided by the method or the method, respectively. + + + +## 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.UTF32Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetCharCount/getchars.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetChars/VB/GetChars.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetChars/VB/GetChars.vb" id="Snippet1"::: + ]]> - is . - - -or- - + is . + + -or- + is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + 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- - + + -and- + is set to . @@ -1443,22 +1443,22 @@ Obtains a decoder that converts a UTF-32 encoded sequence of bytes into a sequence of Unicode characters. A that converts a UTF-32 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. 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 was 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 an encoder and a decoder to encode a string into an array of bytes, and then decode the bytes into an array of characters. - + method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + + If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor was 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 an encoder and a decoder to encode a string into an array of bytes, and then decode the bytes into an array of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF32Encoding.EncDec/CPP/encdec.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetDecoder/encdec.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.EncDec/VB/EncDec.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.EncDec/VB/EncDec.vb" id="Snippet1"::: + ]]> @@ -1509,22 +1509,22 @@ Obtains an encoder that converts a sequence of Unicode characters into a UTF-32 encoded sequence of bytes. A that converts a sequence of Unicode characters into a UTF-32 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 was 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 an encoder and a decoder to encode a string into an array of bytes, and then decode the bytes into an array of characters. - + 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 was 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 an encoder and a decoder to encode a string into an array of bytes, and then decode the bytes into an array of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF32Encoding.EncDec/CPP/encdec.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetDecoder/encdec.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.EncDec/VB/EncDec.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.EncDec/VB/EncDec.vb" id="Snippet1"::: + ]]> @@ -1620,39 +1620,39 @@ 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 and use or . - - has no relationship to . If you need a similar function to use with , use . - + 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 and use or . + + has no relationship to . If you need a similar function to use with , use . + > [!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 string, then encodes the string and displays the resulting bytes. - +> `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 string, then encodes the string and displays the resulting bytes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetBytes/getbytes_string.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetBytes_String/VB/GetBytes_String.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetBytes_String/VB/GetBytes_String.vb" id="Snippet1"::: + ]]> - is less than zero. - - -or- - + 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- - + + -and- + is set to . @@ -1702,39 +1702,39 @@ 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 and use or . - - has no relationship to . If you need a similar function to use with , use . - + 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 and use or . + + has no relationship to . If you need a similar function to use with , use . + > [!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. - +> `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.UTF32Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetCharCount/getchars.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetChars/VB/GetChars.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetChars/VB/GetChars.vb" id="Snippet1"::: + ]]> - is less than zero. - - -or- - + 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- - + + -and- + is set to . @@ -1782,48 +1782,48 @@ Returns a Unicode byte order mark encoded in UTF-32 format, if the object is configured to supply one. A byte array containing the Unicode byte order mark, if the object is configured to supply one. Otherwise, this method returns a zero-length byte array. - object can provide a preamble, which is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code points U+0000 U+FEFF) 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): - -- Big endian byte order: 00 00 FE FF - -- Little endian byte order: FF FE 00 00 - - 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 the parameterless constructor to instantiate a object. - -- By supplying `true` as the value of the `byteOrderMark` argument to the and constructors. - - We recommend that you use the BOM, since 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. - - 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). - + object can provide a preamble, which is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code points U+0000 U+FEFF) 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): + +- Big endian byte order: 00 00 FE FF + +- Little endian byte order: FF FE 00 00 + + 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 the parameterless constructor to instantiate a object. + +- By supplying `true` as the value of the `byteOrderMark` argument to the and constructors. + + We recommend that you use the BOM, since 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. + + 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, you should prefix 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 code example retrieves and displays the byte order mark for different instances. - +> To ensure that the encoded bytes are decoded properly, you should prefix 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 code example retrieves and displays the byte order mark for different instances. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetPreamble/CPP/getpreamble.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/.ctor/getpreamble.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetPreamble/VB/GetPreamble.vb" id="Snippet1"::: - - The following example instantiates two objects, the first of which does not provide a BOM and the second of which does. It then calls the method to write the BOM to a file before writing a UTF-32-encoded string. As the output from the example shows, the file that saves the bytes from the second encoder has four more bytes that the first. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetPreamble/VB/GetPreamble.vb" id="Snippet1"::: + + The following example instantiates two objects, the first of which does not provide a BOM and the second of which does. It then calls the method to write the BOM to a file before writing a UTF-32-encoded string. As the output from the example shows, the file that saves the bytes from the second encoder has four more bytes that the first. + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/.ctor/getpreamble1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetPreamble/VB/getpreamble1.vb" id="Snippet2"::: - - 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-32, the BOM is not displayed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF32Encoding.GetPreamble/VB/getpreamble1.vb" id="Snippet2"::: + + 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-32, the BOM is not displayed. + ]]> @@ -1881,45 +1881,45 @@ Decodes a range of bytes from a byte array into a string. A string that contains the results of decoding the specified sequence of bytes. - . 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, the application should use the or the provided by the method or the method, respectively. - - - -## Examples - The following example encodes a string into two arrays of bytes, one in little-endian order and the other in big-endian order. It then decodes the bytes back into a string. - + . 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, the application should use the or the provided by the method or the method, respectively. + + + +## Examples + The following example encodes a string into two arrays of bytes, one in little-endian order and the other in big-endian order. It then decodes the bytes back into a string. + :::code language="csharp" source="~/snippets/csharp/System.Text/UTF32Encoding/GetString/getstring.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf32encoding.getstring/VB/GetString.vb" id="Snippet1"::: - - 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="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf32encoding.getstring/VB/GetString.vb" id="Snippet1"::: + + 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/UTF32Encoding/GetString/GetString1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf32encoding.getstring/VB/GetString1.vb" id="Snippet2"::: - - Note that in this case the decoded string differs from the original string, since it begins with a 32-bit byte order mark U+FFFE U+0000. 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 "?". - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf32encoding.getstring/VB/GetString1.vb" id="Snippet2"::: + + Note that in this case the decoded string differs from the original string, since it begins with a 32-bit byte order mark U+FFFE U+0000. 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 "?". + ]]> is . - or is less than zero. - - -or- - + 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 for a complete explanation). - - -and- - + + -and- + is set to . @@ -1965,34 +1965,34 @@ Gets a Unicode byte order mark encoded in UTF-32 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, a default span. - object can provide a preamble, which is an span of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code points `U+0000` `U+FEFF`) 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): - -- Big endian byte order: `00 00 FE FF` - -- Little endian byte order: `FF FE 00 00` - - You can instantiate a object whose property is a valid BOM in the following ways: - -- By retrieving the object returned by the property. - -- By calling the parameterless constructor to instantiate a object. - -- By supplying `true` as the value of the `byteOrderMark` argument to the and constructors. - - We recommend that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to the object, such as 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. - - 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). - + object can provide a preamble, which is an span of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code points `U+0000` `U+FEFF`) 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): + +- Big endian byte order: `00 00 FE FF` + +- Little endian byte order: `FF FE 00 00` + + You can instantiate a object whose property is a valid BOM in the following ways: + +- By retrieving the object returned by the property. + +- By calling the parameterless constructor to instantiate a object. + +- By supplying `true` as the value of the `byteOrderMark` argument to the and constructors. + + We recommend that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to the object, such as 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. + + 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, you should prefix 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. - +> To ensure that the encoded bytes are decoded properly, you should prefix 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. + ]]> diff --git a/xml/System.Text/UTF7Encoding.xml b/xml/System.Text/UTF7Encoding.xml index 08495f65556..3b3959ee35b 100644 --- a/xml/System.Text/UTF7Encoding.xml +++ b/xml/System.Text/UTF7Encoding.xml @@ -880,7 +880,7 @@ -or- - and do not denote a valid range in . + and do not denote a valid range in . -or- @@ -1277,7 +1277,7 @@ -or- - and do not denote a valid range in . + and do not denote a valid range in . -or- diff --git a/xml/System.Text/UTF8Encoding.xml b/xml/System.Text/UTF8Encoding.xml index 38928f0a782..fa109725ba7 100644 --- a/xml/System.Text/UTF8Encoding.xml +++ b/xml/System.Text/UTF8Encoding.xml @@ -58,49 +58,49 @@ 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. - + 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. - +> 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. - +> 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. - + 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"::: @@ -159,19 +159,19 @@ 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. - +> 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"::: @@ -223,21 +223,21 @@ 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. - +> 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"::: @@ -292,21 +292,21 @@ 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. - + 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. - +> 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"::: @@ -370,22 +370,22 @@ 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. - + 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"::: @@ -443,22 +443,22 @@ 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. - + 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- - + + -and- + is set to . @@ -513,20 +513,20 @@ 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. - + 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"::: @@ -537,9 +537,9 @@ 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- - + + -and- + is set to . @@ -604,30 +604,30 @@ 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. - + 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- - + 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- - + + -and- + is set to . @@ -689,42 +689,42 @@ 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. - + 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"::: + :::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- - + 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- - + + -and- + The property is set to . @@ -810,17 +810,17 @@ 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. - + 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. + ]]> @@ -887,36 +887,36 @@ 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. - + 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 . or is less than zero. - Error detection is enabled, and contains an invalid sequence of characters. - - -or- - + 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- - + + -and- + is set to . @@ -982,53 +982,53 @@ 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. - + 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="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- + is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + 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- - + + -and- + is set to . @@ -1094,22 +1094,22 @@ 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. - + 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"::: @@ -1117,30 +1117,30 @@ ]]> - is . - - -or- - + is . + + -or- + is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + 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- - + + -and- + is set to . @@ -1193,13 +1193,13 @@ 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. - + 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. + ]]> @@ -1262,28 +1262,28 @@ 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. - + 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- - + 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- - + + -and- + is set to . @@ -1345,18 +1345,18 @@ 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. - + 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"::: @@ -1366,20 +1366,20 @@ is . - or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + + -and- + is set to . @@ -1434,17 +1434,17 @@ 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. - + 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. + ]]> @@ -1511,36 +1511,36 @@ 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. - + 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 . or is less than zero. - Error detection is enabled, and contains an invalid sequence of bytes. - - -or- - + 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- - + + -and- + is set to . @@ -1607,22 +1607,22 @@ 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. - + 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"::: @@ -1630,30 +1630,30 @@ ]]> - is . - - -or- - + is . + + -or- + is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + 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- - + 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- - + + -and- + is set to . @@ -1703,18 +1703,18 @@ 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. - + 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"::: @@ -1771,18 +1771,18 @@ 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. - + 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"::: @@ -1838,15 +1838,15 @@ 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. - + 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"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UTF8Encoding.GetHashCode Example/VB/gethashcode-.vb" id="Snippet1"::: + ]]> @@ -1897,25 +1897,25 @@ 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 . - + 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. - +> `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"::: @@ -1923,15 +1923,15 @@ ]]> - is less than zero. - - -or- - + 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- - + + -and- + is set to . @@ -1983,25 +1983,25 @@ 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 . - + 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. - +> `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"::: @@ -2009,15 +2009,15 @@ ]]> - is less than zero. - - -or- - + 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- - + + -and- + is set to . @@ -2067,44 +2067,44 @@ 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). - + 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. - + +## 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="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. - + + 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. + ]]> @@ -2167,40 +2167,40 @@ 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. - + 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. - + 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- - + 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- - + + -and- + is set to . @@ -2240,30 +2240,30 @@ 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). - + 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. - + ]]> diff --git a/xml/System.Text/UnicodeEncoding.xml b/xml/System.Text/UnicodeEncoding.xml index d4375e22dab..29d0f06f82e 100644 --- a/xml/System.Text/UnicodeEncoding.xml +++ b/xml/System.Text/UnicodeEncoding.xml @@ -1082,9 +1082,7 @@ Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. > [!IMPORTANT] -> 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. - - +> 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 demonstrates how 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. @@ -1106,7 +1104,7 @@ -or- - and do not denote a valid range in . + and do not denote a valid range in . -or- @@ -1517,7 +1515,7 @@ -or- - and do not denote a valid range in . + and do not denote a valid range in . -or- diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index bb5b5716c15..025d77e125d 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -4082,7 +4082,7 @@ This method is intended for compiler use rather than use directly in code. ]]> - The parameter was . + The parameter is . The task has been canceled. This exception is stored into the returned task. The associated with was disposed. Exception Handling (Task Parallel Library) diff --git a/xml/System.Threading/LazyThreadSafetyMode.xml b/xml/System.Threading/LazyThreadSafetyMode.xml index 09b68301188..91ce78b8364 100644 --- a/xml/System.Threading/LazyThreadSafetyMode.xml +++ b/xml/System.Threading/LazyThreadSafetyMode.xml @@ -52,23 +52,23 @@ Specifies how a instance synchronizes access among multiple threads. - constructors. The effects of all constructors on thread synchronization can be described in terms of this enumeration, whether or not they have `mode` parameters. - - A instance is initialized either by a user-specified initialization method or by the parameterless constructor for `T`. The initialization method is specified by the `valueFactory` parameter of a constructor. The method returns an instance of `T`, which is the type that is lazily instantiated by the instance of . If a constructor does not have a `valueFactory` parameter, the parameterless constructor for `T` is used to initialize the instance. In either case, initialization occurs the first time you call the property. - - In addition to specifying the thread safety of a instance, this enumeration affects exception caching. When exceptions are cached for a instance, you get only one chance to initialize the instance. If an exception is thrown the first time you call the property, that exception is cached and rethrown on all subsequent calls to the property. The advantage of caching exceptions is that any two threads always get the same result, even when errors occur. - - When you specify the PublicationOnly mode, exceptions are never cached. When you specify None or ExecutionAndPublication, caching depends on whether you specify an initialization method or allow the parameterless constructor for `T` to be used. Specifying an initialization method enables exception caching for these two modes. The initialization method can be very simple. For example, it might call the parameterless constructor for `T`: `new Lazy(() => new Contents(), mode)` in C#, or `New Lazy(Of Contents)(Function() New Contents())` in Visual Basic. If you use a constructor that does not specify an initialization method, exceptions that are thrown by the parameterless constructor for `T` are not cached. The following table summarizes exception caching behavior. - -|Mode|Using initialization method|Using parameterless constructor for `T`| -|----------|---------------------------------|---------------------------------------| -|None|Cached|Not cached| -|PublicationOnly|Not cached|Not cached| -|ExecutionAndPublication|Cached|Not cached| - + constructors. The effects of all constructors on thread synchronization can be described in terms of this enumeration, whether or not they have `mode` parameters. + + A instance is initialized either by a user-specified initialization method or by the parameterless constructor for `T`. The initialization method is specified by the `valueFactory` parameter of a constructor. The method returns an instance of `T`, which is the type that is lazily instantiated by the instance of . If a constructor does not have a `valueFactory` parameter, the parameterless constructor for `T` is used to initialize the instance. In either case, initialization occurs the first time you call the property. + + In addition to specifying the thread safety of a instance, this enumeration affects exception caching. When exceptions are cached for a instance, you get only one chance to initialize the instance. If an exception is thrown the first time you call the property, that exception is cached and rethrown on all subsequent calls to the property. The advantage of caching exceptions is that any two threads always get the same result, even when errors occur. + + When you specify the PublicationOnly mode, exceptions are never cached. When you specify None or ExecutionAndPublication, caching depends on whether you specify an initialization method or allow the parameterless constructor for `T` to be used. Specifying an initialization method enables exception caching for these two modes. The initialization method can be very simple. For example, it might call the parameterless constructor for `T`: `new Lazy(() => new Contents(), mode)` in C#, or `New Lazy(Of Contents)(Function() New Contents())` in Visual Basic. If you use a constructor that does not specify an initialization method, exceptions that are thrown by the parameterless constructor for `T` are not cached. The following table summarizes exception caching behavior. + +|Mode|Using initialization method|Using parameterless constructor for `T`| +|----------|---------------------------------|---------------------------------------| +|None|Cached|Not cached| +|PublicationOnly|Not cached|Not cached| +|ExecutionAndPublication|Cached|Not cached| + ]]> Lazy Initialization @@ -206,7 +206,7 @@ 1 - When multiple threads try to initialize a instance simultaneously, all threads are allowed to run the initialization method (or the parameterless constructor, if there is no initialization method). The first thread to complete initialization sets the value of the instance. This is referred to as `Publication` in the field names. That value is returned to any other threads that were simultaneously running the initialization method, unless the initialization method throws exceptions on those threads. Any instances of that were created by the competing threads are discarded. Effectively, the publication of the initialized value is thread-safe in the sense that only one of the initialized values may be published and used by all threads. If the initialization method throws an exception on any thread, the exception is propagated out of the property on that thread. The exception is not cached. The value of the property remains , and subsequent calls to the property, either by the thread where the exception was thrown or by other threads, cause the initialization method to run again. If the initialization method recursively accesses the property of the instance, no exception is thrown. + When multiple threads try to initialize a instance simultaneously, all threads are allowed to run the initialization method (or the parameterless constructor, if there is no initialization method). The first thread to complete initialization sets the value of the instance. This is referred to as `Publication` in the field names. That value is returned to any other threads that were simultaneously running the initialization method, unless the initialization method throws exceptions on those threads. Any instances of that were created by the competing threads are discarded. Effectively, the publication of the initialized value is thread-safe in the sense that only one of the initialized values can be published and used by all threads. If the initialization method throws an exception on any thread, the exception is propagated out of the property on that thread. The exception is not cached. The value of the property remains , and subsequent calls to the property, either by the thread where the exception was thrown or by other threads, cause the initialization method to run again. If the initialization method recursively accesses the property of the instance, no exception is thrown. diff --git a/xml/System.Threading/ReaderWriterLock.xml b/xml/System.Threading/ReaderWriterLock.xml index 8ddd8655a44..63bda1412e9 100644 --- a/xml/System.Threading/ReaderWriterLock.xml +++ b/xml/System.Threading/ReaderWriterLock.xml @@ -56,51 +56,51 @@ Defines a lock that supports single writers and multiple readers. - [!IMPORTANT] -> The .NET Framework has two reader-writer locks, and . is recommended for all new development. is similar to , but it has simplified rules for recursion and for upgrading and downgrading lock state. avoids many cases of potential deadlock. In addition, the performance of is significantly better than . - - is used to synchronize access to a resource. At any given time, it allows either concurrent read access for multiple threads, or write access for a single thread. In a situation where a resource is changed infrequently, a `ReaderWriterLock` provides better throughput than a simple one-at-a-time lock, such as . - - `ReaderWriterLock` works best where most accesses are reads, while writes are infrequent and of short duration. Multiple readers alternate with single writers, so that neither readers nor writers are blocked for long periods. - +> The .NET Framework has two reader-writer locks, and . is recommended for all new development. is similar to , but it has simplified rules for recursion and for upgrading and downgrading lock state. avoids many cases of potential deadlock. In addition, the performance of is significantly better than . + + is used to synchronize access to a resource. At any given time, it allows either concurrent read access for multiple threads, or write access for a single thread. In a situation where a resource is changed infrequently, a `ReaderWriterLock` provides better throughput than a simple one-at-a-time lock, such as . + + `ReaderWriterLock` works best where most accesses are reads, while writes are infrequent and of short duration. Multiple readers alternate with single writers, so that neither readers nor writers are blocked for long periods. + > [!NOTE] -> Holding reader locks or writer locks for long periods will starve other threads. For best performance, consider restructuring your application to minimize the duration of writes. - - A thread can hold a reader lock or a writer lock, but not both at the same time. Instead of releasing a reader lock in order to acquire the writer lock, you can use and . - - Recursive lock requests increase the lock count on a lock. - - Readers and writers are queued separately. When a thread releases the writer lock, all threads waiting in the reader queue at that instant are granted reader locks; when all of those reader locks have been released, the next thread waiting in the writer queue, if any, is granted the writer lock, and so on. In other words, `ReaderWriterLock` alternates between a collection of readers, and one writer. - - While a thread in the writer queue is waiting for active reader locks to be released, threads requesting new reader locks accumulate in the reader queue. Their requests are not granted, even though they could share concurrent access with existing reader-lock holders; this helps protect writers against indefinite blockage by readers. - - Most methods for acquiring locks on a `ReaderWriterLock` accept time-out values. Use time-outs to avoid deadlocks in your application. For example, a thread might acquire the writer lock on one resource and then request a reader lock on a second resource; in the meantime, another thread might acquire the writer lock on the second resource, and request a reader lock on the first. Unless time-outs are used, the threads deadlock. - - If the time-out interval expires and the lock request has not been granted, the method returns control to the calling thread by throwing an . A thread can catch this exception and determine what action to take next. - - Time-outs are expressed in milliseconds. If you use a to specify the time-out, the value used is the total number of whole milliseconds represented by the . The following table shows the valid time-out values in milliseconds. - -|Value|Description| -|-----------|-----------------| -|-1|The thread waits until the lock is acquired, regardless of how long it takes. For methods that specify integer time-outs, the constant can be used.| -|0|The thread does not wait to acquire the lock. If the lock cannot be acquired immediately, the method returns.| -|>0|The number of milliseconds to wait.| - - With the exception of -1, negative time-out values are not allowed. If you specify a negative integer other than -1, a time-out value of zero is used instead. (That is, the method returns without waiting, if the lock cannot be acquired immediately.) If you specify a that represents a negative number of milliseconds other than -1, is thrown. - - - -## Examples - The following example demonstrates how to use a to protect a shared resource, an integer value named `resource`, that is read concurrently and written exclusively by multiple threads. Note that the is declared at the class level so that it is visible to all threads. - +> Holding reader locks or writer locks for long periods will starve other threads. For best performance, consider restructuring your application to minimize the duration of writes. + + A thread can hold a reader lock or a writer lock, but not both at the same time. Instead of releasing a reader lock in order to acquire the writer lock, you can use and . + + Recursive lock requests increase the lock count on a lock. + + Readers and writers are queued separately. When a thread releases the writer lock, all threads waiting in the reader queue at that instant are granted reader locks; when all of those reader locks have been released, the next thread waiting in the writer queue, if any, is granted the writer lock, and so on. In other words, `ReaderWriterLock` alternates between a collection of readers, and one writer. + + While a thread in the writer queue is waiting for active reader locks to be released, threads requesting new reader locks accumulate in the reader queue. Their requests are not granted, even though they could share concurrent access with existing reader-lock holders; this helps protect writers against indefinite blockage by readers. + + Most methods for acquiring locks on a `ReaderWriterLock` accept time-out values. Use time-outs to avoid deadlocks in your application. For example, a thread might acquire the writer lock on one resource and then request a reader lock on a second resource; in the meantime, another thread might acquire the writer lock on the second resource, and request a reader lock on the first. Unless time-outs are used, the threads deadlock. + + If the time-out interval expires and the lock request has not been granted, the method returns control to the calling thread by throwing an . A thread can catch this exception and determine what action to take next. + + Time-outs are expressed in milliseconds. If you use a to specify the time-out, the value used is the total number of whole milliseconds represented by the . The following table shows the valid time-out values in milliseconds. + +|Value|Description| +|-----------|-----------------| +|-1|The thread waits until the lock is acquired, regardless of how long it takes. For methods that specify integer time-outs, the constant can be used.| +|0|The thread does not wait to acquire the lock. If the lock cannot be acquired immediately, the method returns.| +|>0|The number of milliseconds to wait.| + + With the exception of -1, negative time-out values are not allowed. If you specify a negative integer other than -1, a time-out value of zero is used instead. (That is, the method returns without waiting, if the lock cannot be acquired immediately.) If you specify a that represents a negative number of milliseconds other than -1, is thrown. + + + +## Examples + The following example demonstrates how to use a to protect a shared resource, an integer value named `resource`, that is read concurrently and written exclusively by multiple threads. Note that the is declared at the class level so that it is visible to all threads. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -149,20 +149,20 @@ Initializes a new instance of the class. - class. - - This code is part of a larger example provided for the class. - + class. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: + ]]> Managed Threading @@ -231,37 +231,37 @@ The time-out in milliseconds. Acquires a reader lock, using an value for the time-out. - blocks if a different thread has the writer lock, or if at least one thread is waiting for the writer lock. - + blocks if a different thread has the writer lock, or if at least one thread is waiting for the writer lock. + > [!NOTE] -> If the current thread already has the writer lock, no reader lock is acquired. Instead, the lock count on the writer lock is incremented. This prevents a thread from blocking on its own writer lock. The result is exactly the same as calling , and an additional call to is required when releasing the writer lock. - - `AcquireReaderLock` supports recursive reader-lock requests. That is, a thread can call AcquireReaderLock multiple times, which increments the lock count each time. You must call once for each time you call `AcquireReaderLock`. Alternatively, you can call to reduce the lock count to zero immediately. - - Recursive lock requests are always granted immediately, without placing the requesting thread in the reader queue. Use recursive locks with caution, to avoid blocking writer-lock requests for long periods. - - For valid time-out values, see . - - - -## Examples - The following code example shows how to acquire and release a reader lock, and how to handle the exception thrown when a request times out. - - This code is part of a larger example provided for the class. - +> If the current thread already has the writer lock, no reader lock is acquired. Instead, the lock count on the writer lock is incremented. This prevents a thread from blocking on its own writer lock. The result is exactly the same as calling , and an additional call to is required when releasing the writer lock. + + `AcquireReaderLock` supports recursive reader-lock requests. That is, a thread can call AcquireReaderLock multiple times, which increments the lock count each time. You must call once for each time you call `AcquireReaderLock`. Alternatively, you can call to reduce the lock count to zero immediately. + + Recursive lock requests are always granted immediately, without placing the requesting thread in the reader queue. Use recursive locks with caution, to avoid blocking writer-lock requests for long periods. + + For valid time-out values, see . + + + +## Examples + The following code example shows how to acquire and release a reader lock, and how to handle the exception thrown when a request times out. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet3"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: + ]]> @@ -322,20 +322,20 @@ A specifying the time-out period. Acquires a reader lock, using a value for the time-out. - blocks if a different thread has the writer lock, or if at least one thread is waiting for the writer lock. - + blocks if a different thread has the writer lock, or if at least one thread is waiting for the writer lock. + > [!NOTE] -> If the current thread already has the writer lock, no reader lock is acquired. Instead, the lock count on the writer lock is incremented. This prevents a thread from blocking on its own writer lock. The result is exactly the same as calling , and an additional call to is required when releasing the writer lock. - - `AcquireReaderLock` supports recursive reader-lock requests. That is, a thread can call AcquireReaderLock multiple times, which increments the lock count each time. You must call once for each time you call `AcquireReaderLock`. Alternatively, you can call to reduce the lock count to zero immediately. - - Recursive lock requests are always granted immediately, without placing the requesting thread in the reader queue. Use recursive locks with caution, to avoid blocking writer-lock requests for long periods. - - For valid time-out values, see . - +> If the current thread already has the writer lock, no reader lock is acquired. Instead, the lock count on the writer lock is incremented. This prevents a thread from blocking on its own writer lock. The result is exactly the same as calling , and an additional call to is required when releasing the writer lock. + + `AcquireReaderLock` supports recursive reader-lock requests. That is, a thread can call AcquireReaderLock multiple times, which increments the lock count each time. You must call once for each time you call `AcquireReaderLock`. Alternatively, you can call to reduce the lock count to zero immediately. + + Recursive lock requests are always granted immediately, without placing the requesting thread in the reader queue. Use recursive locks with caution, to avoid blocking writer-lock requests for long periods. + + For valid time-out values, see . + ]]> @@ -404,43 +404,41 @@ The time-out in milliseconds. Acquires the writer lock, using an value for the time-out. - class. - - A thread that already has a reader lock can acquire the writer lock in one of two ways: by releasing the reader lock before calling , or by calling . - + class. + + A thread that already has a reader lock can acquire the writer lock in one of two ways: by releasing the reader lock before calling , or by calling . + > [!CAUTION] -> If a thread calls `AcquireWriterLock` while it still has a reader lock, it will block on its own reader lock; if an infinite time-out is specified, the thread will deadlock. To avoid such deadlocks, use to determine whether the current thread already has a reader lock. - - `AcquireWriterLock` supports recursive writer-lock requests. That is, a thread can call `AcquireWriterLock` multiple times, which increments the lock count each time. You must call once for each time you call `AcquireWriterLock`. Alternatively, you can call to reduce the lock count to zero immediately. - - Recursive lock requests are always granted immediately, without placing the requesting thread in the writer queue. - - For valid time-out values, see . - - - -## Examples - The following code example shows how to acquire and release a writer lock, and how to handle the exception thrown when a request times out. - - This code is part of a larger example provided for the class. - +> If a thread calls `AcquireWriterLock` while it still has a reader lock, it will block on its own reader lock; if an infinite time-out is specified, the thread will deadlock. To avoid such deadlocks, use to determine whether the current thread already has a reader lock. + + `AcquireWriterLock` supports recursive writer-lock requests. That is, a thread can call `AcquireWriterLock` multiple times, which increments the lock count each time. You must call once for each time you call `AcquireWriterLock`. Alternatively, you can call to reduce the lock count to zero immediately. + + Recursive lock requests are always granted immediately, without placing the requesting thread in the writer queue. + + For valid time-out values, see . + +## Examples + The following code example shows how to acquire and release a writer lock, and how to handle the exception thrown when a request times out. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet4"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: + ]]> - expires before the lock request is granted. + expires before the lock request is granted. Managed Threading ReaderWriterLock @@ -493,22 +491,22 @@ The specifying the time-out period. Acquires the writer lock, using a value for the time-out. - class. - - A thread that already has a reader lock can acquire the writer lock in one of two ways: by releasing the reader lock before calling , or by calling . - + class. + + A thread that already has a reader lock can acquire the writer lock in one of two ways: by releasing the reader lock before calling , or by calling . + > [!CAUTION] -> If a thread calls `AcquireWriterLock` while it still has a reader lock, it will block on its own reader lock; if an infinite time-out is specified, the thread will deadlock. To avoid such deadlocks, use to determine whether the current thread already has a reader lock. - - `AcquireWriterLock` supports recursive writer-lock requests. That is, a thread can call `AcquireWriterLock` multiple times, which increments the lock count each time. You must call once for each time you call `AcquireWriterLock`. Alternatively, you can call to reduce the lock count to zero immediately. - - Recursive lock requests are always granted immediately, without placing the requesting thread in the writer queue. - - For valid time-out values, see . - +> If a thread calls `AcquireWriterLock` while it still has a reader lock, it will block on its own reader lock; if an infinite time-out is specified, the thread will deadlock. To avoid such deadlocks, use to determine whether the current thread already has a reader lock. + + `AcquireWriterLock` supports recursive writer-lock requests. That is, a thread can call `AcquireWriterLock` multiple times, which increments the lock count each time. You must call once for each time you call `AcquireWriterLock`. Alternatively, you can call to reduce the lock count to zero immediately. + + Recursive lock requests are always granted immediately, without placing the requesting thread in the writer queue. + + For valid time-out values, see . + ]]> @@ -569,30 +567,30 @@ if the writer lock has been granted to any thread since the sequence number was obtained; otherwise, . - and `AnyWritersSince` to improve application performance. For example, a thread might cache the information it obtains while holding a reader lock. After releasing and later reacquiring the lock, the thread can use `AnyWritersSince` to determine whether other threads have written to the resource in the interim; if not, the cached information can be used. This technique is useful where reading the information protected by the lock is expensive; for example, running a database query. - - The caller must be holding a reader lock or a writer lock in order for the sequence number to be useful. - - - -## Examples - The following code example shows how to use the method and the property to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. - - This code is part of a larger example provided for the class. - + and `AnyWritersSince` to improve application performance. For example, a thread might cache the information it obtains while holding a reader lock. After releasing and later reacquiring the lock, the thread can use `AnyWritersSince` to determine whether other threads have written to the resource in the interim; if not, the cached information can be used. This technique is useful where reading the information protected by the lock is expensive; for example, running a database query. + + The caller must be holding a reader lock or a writer lock in order for the sequence number to be useful. + + + +## Examples + The following code example shows how to use the method and the property to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet6"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: + ]]> Managed Threading @@ -647,33 +645,33 @@ A returned by . Restores the lock status of the thread to what it was before was called. - releases the writer lock, regardless of the recursive lock count, and restores the reader lock that was held by the thread before upgrading to the writer lock. The lock count on the reader lock is restored. - + releases the writer lock, regardless of the recursive lock count, and restores the reader lock that was held by the thread before upgrading to the writer lock. The lock count on the reader lock is restored. + > [!NOTE] -> `DowngradeFromWriterLock` accepts a obtained by calling . Do not use a `LockCookie` returned by . - - A thread does not block when downgrading from the writer lock, even if other threads are waiting for the writer lock, because all reader-lock requests are granted when the writer lock is released. - - - -## Examples - The following code example shows how to request a reader lock, upgrade the reader lock to a writer lock, and downgrade to a reader lock again. - - This code is part of a larger example provided for the class. - +> `DowngradeFromWriterLock` accepts a obtained by calling . Do not use a `LockCookie` returned by . + + A thread does not block when downgrading from the writer lock, even if other threads are waiting for the writer lock, because all reader-lock requests are granted when the writer lock is released. + + + +## Examples + The following code example shows how to request a reader lock, upgrade the reader lock to a writer lock, and downgrade to a reader lock again. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet5"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: + ]]> The thread does not have the writer lock. @@ -717,11 +715,11 @@ Ensures that resources are freed and other cleanup operations are performed when the garbage collector reclaims the object. - when the current object is ready to be finalized. - + when the current object is ready to be finalized. + ]]> @@ -776,15 +774,15 @@ if the current thread holds a reader lock; otherwise, . - Managed Threading @@ -841,15 +839,15 @@ if the current thread holds the writer lock; otherwise, . - Managed Threading @@ -902,28 +900,28 @@ Releases the lock, regardless of the number of times the thread acquired the lock. A value representing the released lock. - releases the reader lock or writer lock, regardless of the recursive lock count. To restore the state of the lock, including the lock count, pass the to . - - - -## Examples - The following code example shows how to use the method to release the lock, regardless of how many times it has been acquired by the thread, and how to restore the state of the lock later. - - This code is part of a larger example provided for the class. - + releases the reader lock or writer lock, regardless of the recursive lock count. To restore the state of the lock, including the lock count, pass the to . + + + +## Examples + The following code example shows how to use the method to release the lock, regardless of how many times it has been acquired by the thread, and how to restore the state of the lock later. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet6"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: + ]]> Managed Threading @@ -979,31 +977,31 @@ Decrements the lock count. - decrements the lock count. When the count reaches zero, the lock is released. - + decrements the lock count. When the count reaches zero, the lock is released. + > [!NOTE] -> If a thread has the writer lock, calling `ReleaseReaderLock` has the same effect as calling . If a thread has no locks, calling `ReleaseReaderLock` throws an . - - - -## Examples - The following code example shows how to acquire and release a reader lock, and how to handle the exception thrown when a request times out. - - This code is part of a larger example provided for the class. - +> If a thread has the writer lock, calling `ReleaseReaderLock` has the same effect as calling . If a thread has no locks, calling `ReleaseReaderLock` throws an . + + + +## Examples + The following code example shows how to acquire and release a reader lock, and how to handle the exception thrown when a request times out. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet3"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: + ]]> The thread does not have any reader or writer locks. @@ -1060,31 +1058,31 @@ Decrements the lock count on the writer lock. - decrements the writer lock count. When the count reaches zero, the writer lock is released. - + decrements the writer lock count. When the count reaches zero, the writer lock is released. + > [!NOTE] -> If a thread has a reader lock, or no locks, calling `ReleaseWriterLock` throws an . - - - -## Examples - The following code example shows how to acquire and release a writer lock, and how to handle the exception thrown when a request times out. - - This code is part of a larger example provided for the class. - +> If a thread has a reader lock, or no locks, calling `ReleaseWriterLock` throws an . + + + +## Examples + The following code example shows how to acquire and release a writer lock, and how to handle the exception thrown when a request times out. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet4"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: + ]]> The thread does not have the writer lock. @@ -1144,35 +1142,35 @@ A returned by . Restores the lock status of the thread to what it was before calling . - [!CAUTION] -> Before calling `RestoreLock`, make sure you have released all locks acquired since the call to . For example, a thread deadlocks if it acquires a reader lock, and then attempts to restore an earlier writer lock. Use and to detect such additional locks. - - Do not use a returned from . - - - -## Examples - The following code example shows how to use the method to release the lock, regardless of how many times it has been acquired by the thread, and how to restore the state of the lock later. - - This code is part of a larger example provided for the class. - +> Before calling `RestoreLock`, make sure you have released all locks acquired since the call to . For example, a thread deadlocks if it acquires a reader lock, and then attempts to restore an earlier writer lock. Use and to detect such additional locks. + + Do not use a returned from . + + + +## Examples + The following code example shows how to use the method to release the lock, regardless of how many times it has been acquired by the thread, and how to restore the state of the lock later. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet6"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: + ]]> The address of is a null pointer. @@ -1243,37 +1241,37 @@ Upgrades a reader lock to the writer lock, using an value for the time-out. A value. - [!IMPORTANT] -> The time-out exception is not thrown until the thread that called the method can reacquire the reader lock. If there are no other threads waiting for the writer lock, this happens immediately. However, if another thread is queued for the writer lock, the thread that called the method cannot reacquire the reader lock until all current readers have released their locks, and one thread has acquired and released the writer lock. This is true even if the other thread that requested the writer lock requested it after the current thread called the method. - - To restore the lock state, call using the returned by `UpgradeToWriterLock`. Do not use this `LockCookie` with . - - When a thread has no reader lock, do not use `UpgradeToWriterLock`. Use instead. - - For valid time-out values, see . - - - -## Examples - The following code example shows how to request a reader lock, upgrade the reader lock to a writer lock, and downgrade to a reader lock again. - - This code is part of a larger example provided for the class. - +> The time-out exception is not thrown until the thread that called the method can reacquire the reader lock. If there are no other threads waiting for the writer lock, this happens immediately. However, if another thread is queued for the writer lock, the thread that called the method cannot reacquire the reader lock until all current readers have released their locks, and one thread has acquired and released the writer lock. This is true even if the other thread that requested the writer lock requested it after the current thread called the method. + + To restore the lock state, call using the returned by `UpgradeToWriterLock`. Do not use this `LockCookie` with . + + When a thread has no reader lock, do not use `UpgradeToWriterLock`. Use instead. + + For valid time-out values, see . + + + +## Examples + The following code example shows how to request a reader lock, upgrade the reader lock to a writer lock, and downgrade to a reader lock again. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet5"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: + ]]> @@ -1331,20 +1329,20 @@ Upgrades a reader lock to the writer lock, using a value for the time-out. A value. - [!IMPORTANT] -> The time-out exception is not thrown until the thread that called the method can reacquire the reader lock. If there are no other threads waiting for the writer lock, this happens immediately. However, if another thread is queued for the writer lock, the thread that called the method cannot reacquire the reader lock until all current readers have released their locks, and one thread has acquired and released the writer lock. This is true even if the other thread that requested the writer lock requested it after the current thread called the method. - - To restore the lock state, call using the returned by `UpgradeToWriterLock`. Do not use this `LockCookie` with . - - When a thread has no reader lock, do not use `UpgradeToWriterLock`. Use instead. - - For valid time-out values, see . - +> The time-out exception is not thrown until the thread that called the method can reacquire the reader lock. If there are no other threads waiting for the writer lock, this happens immediately. However, if another thread is queued for the writer lock, the thread that called the method cannot reacquire the reader lock until all current readers have released their locks, and one thread has acquired and released the writer lock. This is true even if the other thread that requested the writer lock requested it after the current thread called the method. + + To restore the lock state, call using the returned by `UpgradeToWriterLock`. Do not use this `LockCookie` with . + + When a thread has no reader lock, do not use `UpgradeToWriterLock`. Use instead. + + For valid time-out values, see . + ]]> @@ -1400,32 +1398,32 @@ Gets the current sequence number. The current sequence number. - at a later time, if you want to determine whether other threads have acquired the writer lock in the meantime. - - You can use `WriterSeqNum` to improve application performance. For example, a thread might cache the information it obtains while holding a reader lock. After releasing and later reacquiring the lock, the thread can determine whether other threads have written to the resource by calling `AnyWritersSince`; if not, the cached information can be used. This technique is useful when reading the information protected by the lock is expensive; for example, running a database query. - - The caller must be holding a reader lock or a writer lock in order for the sequence number to be useful. - - - -## Examples - The following code example shows how to use the property and the method to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. - - This code is part of a larger example provided for the class. - + at a later time, if you want to determine whether other threads have acquired the writer lock in the meantime. + + You can use `WriterSeqNum` to improve application performance. For example, a thread might cache the information it obtains while holding a reader lock. After releasing and later reacquiring the lock, the thread can determine whether other threads have written to the resource by calling `AnyWritersSince`; if not, the cached information can be used. This technique is useful when reading the information protected by the lock is expensive; for example, running a database query. + + The caller must be holding a reader lock or a writer lock in order for the sequence number to be useful. + + + +## Examples + The following code example shows how to use the property and the method to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet6"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/LockCookie/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ReaderWriterLock/VB/source.vb" id="Snippet7"::: + ]]> Managed Threading diff --git a/xml/System.Threading/ThreadPool.xml b/xml/System.Threading/ThreadPool.xml index 8368da0a63b..636a7ec553a 100644 --- a/xml/System.Threading/ThreadPool.xml +++ b/xml/System.Threading/ThreadPool.xml @@ -1534,7 +1534,7 @@ The thread pool will invoke the work item's - is . + is . The work item is a . The work item could not be queued. @@ -1668,7 +1668,7 @@ The thread pool will invoke the work item's if the method is successfully queued; is thrown if the work item could not be queued. To be added. - is . + is . The work item could not be queued. diff --git a/xml/System.Transactions/TransactionManager.xml b/xml/System.Transactions/TransactionManager.xml index 991d671edf0..cc40f2ce1ab 100644 --- a/xml/System.Transactions/TransactionManager.xml +++ b/xml/System.Transactions/TransactionManager.xml @@ -49,11 +49,11 @@ Contains methods used for transaction management. This class cannot be inherited. - Performing Recovery @@ -101,13 +101,13 @@ Gets the default timeout interval for new transactions. A value that specifies the timeout interval for new transactions. - @@ -150,13 +150,13 @@ Indicates that a distributed transaction has started. - [!CAUTION] -> Signing up for this event degrades the performance of all distributed transactions. Local transactions are not monitored as performance is affected even more. - + [!CAUTION] +> Signing up for this event degrades the performance of all distributed transactions. Local transactions are not monitored as performance is affected even more. + ]]> @@ -282,13 +282,13 @@ Gets the default maximum timeout interval for new transactions. A value that specifies the maximum timeout interval that is allowed when creating new transactions. - property. - - This value can be set in the `MachineSettingsSection` of the config file. - + property. + + This value can be set in the `MachineSettingsSection` of the config file. + ]]> @@ -334,13 +334,13 @@ A that uniquely identifies the resource to be recovered from. Notifies the transaction manager that a resource manager recovering from failure has finished reenlisting in all unresolved transactions. - method for each outstanding transaction. Only when all of the reenlistments are done should the resource manager call . - - For more information on recovery, see [Performing Recovery](/previous-versions/ms229982(v=vs.90)). - + method for each outstanding transaction. Only when all of the reenlistments are done should the resource manager call . + + For more information on recovery, see [Performing Recovery](/previous-versions/ms229982(v=vs.90)). + ]]> The parameter is . @@ -392,38 +392,38 @@ Reenlists a durable participant in a transaction. An that describes the enlistment. - method, the resource manager must provide the same `resourceManagerIdentifier` as it used when it originally called the method during enlistment, or a is thrown. - -When a participant is reenlisted using this method, the phase 2 methods of that correspond to the transaction's outcome (that is, , , or ) are called as appropriate. - -After the participants are successfully reenlisted, you should then call to complete the recovery. - -You should only call this method when a resource manager restarts from failure. In addition, you should only reenlist unresolved transactions logged by a resource manager during the initial Prepare phase of a two-phase commit. Any attempt to call this method at invalid times can produce erroneous results. - -If the transaction manager fails, and your resource manager performs recovery only a short time after you called the method on an enlistment in phase 1 of the Two-Phase Commit protocol, your resource manager might either receive the or callback. - -For more information on recovery, see [Performing Recovery](/previous-versions/ms229982(v=vs.90)). - + method, the resource manager must provide the same `resourceManagerIdentifier` as it used when it originally called the method during enlistment, or a is thrown. + +When a participant is reenlisted using this method, the phase 2 methods of that correspond to the transaction's outcome (that is, , , or ) are called as appropriate. + +After the participants are successfully reenlisted, you should then call to complete the recovery. + +You should only call this method when a resource manager restarts from failure. In addition, you should only reenlist unresolved transactions logged by a resource manager during the initial Prepare phase of a two-phase commit. Any attempt to call this method at invalid times can produce erroneous results. + +If the transaction manager fails, and your resource manager performs recovery only a short time after you called the method on an enlistment in phase 1 of the Two-Phase Commit protocol, your resource manager might either receive the or callback. + +For more information on recovery, see [Performing Recovery](/previous-versions/ms229982(v=vs.90)). + ]]> - is invalid. - - -or- - - Transaction Manager information in does not match the configured transaction manager. - - -or- - - is not recognized by . + is invalid. + + -or- + + Transaction Manager information in does not match the configured transaction manager. + + -or- + + is not recognized by . has already been called for the specified . The reenlistment is rejected. The does not match the content of the specified recovery information in .