diff --git a/.github/workflows/quest-bulk.yml b/.github/workflows/quest-bulk.yml index cff69481a0b..3441aeab0f5 100644 --- a/.github/workflows/quest-bulk.yml +++ b/.github/workflows/quest-bulk.yml @@ -1,8 +1,8 @@ name: "bulk quest import" on: schedule: - - cron: '0 10 * * *' # UTC time, that's 5:00 am EST, 2:00 am PST. - - cron: '0 9 6 * *' # This is the morning of the 6th. + - cron: '30 10 1-5,7-31 * *' # UTC time, that's 5:30 am EST, 2:30 am PST. + - cron: '30 10 6 * *' # This is the morning of the 6th. workflow_dispatch: inputs: reason: @@ -50,4 +50,4 @@ jobs: org: ${{ github.repository_owner }} repo: ${{ github.repository }} issue: '-1' - duration: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.duration || github.event.schedule == '0 9 6 * *' && -1 || 5 }} + duration: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.duration || github.event.schedule == '30 10 6 * *' && -1 || 5 }} 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 . diff --git a/xml/System.Windows/DataObject.xml b/xml/System.Windows/DataObject.xml index 475591ebaeb..1c97b8be28c 100644 --- a/xml/System.Windows/DataObject.xml +++ b/xml/System.Windows/DataObject.xml @@ -2319,7 +2319,7 @@ E_NOTIMPL - The direction specified by the parameter is not supported. + The direction specified by the parameter is not supported. OLE_S_USEREG @@ -2387,7 +2387,7 @@ DATA_S_SAMEFORMATETC - The structures are the same and is returned in the parameter. + The structures are the same and is returned in the parameter. DV_E_LINDEX @@ -2395,7 +2395,7 @@ DV_E_FORMATETC - There is an invalid value for the parameter. + There is an invalid value for the parameter. OLE_E_NOTRUNNING @@ -2563,7 +2563,7 @@ DV_E_FORMATETC - An invalid value for the parameter. + An invalid value for the parameter. DV_E_TYMED diff --git a/xml/System.Windows/DependencyObjectType.xml b/xml/System.Windows/DependencyObjectType.xml index b21347e2336..60001235c10 100644 --- a/xml/System.Windows/DependencyObjectType.xml +++ b/xml/System.Windows/DependencyObjectType.xml @@ -23,13 +23,13 @@ Implements an underlying type cache for all derived types. - represents a specific underlying system (CLR) of a . is essentially a wrapper for the (CLR) so that it can extend some of its capabilities. - - This class has no public constructor. Instances of this class can only be obtained through properties on other objects (such as ), or through the static method . - + represents a specific underlying system (CLR) of a . is essentially a wrapper for the (CLR) so that it can extend some of its capabilities. + + This class has no public constructor. Instances of this class can only be obtained through properties on other objects (such as ), or through the static method . + ]]> @@ -99,19 +99,19 @@ Returns a that represents a given system (CLR) type. A that represents the system (CLR) type. - maintains a property that returns a , but this requires having a particular instance. You can use this static utility method if you do not yet have a instance and require a . - - - -## Examples - The following example calls , creating a based on the type of the class. - + maintains a property that returns a , but this requires having a particular instance. You can use this static utility method if you do not yet have a instance and require a . + + + +## Examples + The following example calls , creating a based on the type of the class. + :::code language="csharp" source="~/snippets/csharp/System.Windows/DependencyObjectType/FromSystemType/page3.xaml.cs" id="Snippetdotfromsystemtype"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PropertiesOvwSupport/visualbasic/page3.xaml.vb" id="Snippetdotfromsystemtype"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PropertiesOvwSupport/visualbasic/page3.xaml.vb" id="Snippetdotfromsystemtype"::: + ]]> @@ -143,11 +143,11 @@ Returns the hash code for this . A 32-bit signed integer hash code. - property. - + property. + ]]> @@ -184,11 +184,11 @@ Gets a zero-based unique identifier for constant-time array lookup operations. An internal identifier. - @@ -222,13 +222,13 @@ The object to compare with the current . Determines whether the specified object is an instance of the current . - if the class represented by the current is in the inheritance hierarchy of the passed as ; otherwise, . + if the class represented by the current is in the inheritance hierarchy of the passed as ; otherwise, . - @@ -292,11 +292,11 @@ Gets the name of the represented common language runtime (CLR) system type. The name of the represented CLR system type. - is the same string as the name of the type name of the . - + is the same string as the name of the type name of the . + ]]> diff --git a/xml/System.Windows/FrameworkElement.xml b/xml/System.Windows/FrameworkElement.xml index 37f1238a972..e771edbb800 100644 --- a/xml/System.Windows/FrameworkElement.xml +++ b/xml/System.Windows/FrameworkElement.xml @@ -441,7 +441,7 @@ The actual size used. To be added. - Control authors who want to customize the arrange pass of layout processing should override this method. The implementation pattern should call on each visible child element, and pass the final desired size for each child element as the parameter. Parent elements should call on each child, otherwise the child elements will not be rendered. + Control authors who want to customize the arrange pass of layout processing should override this method. The implementation pattern should call on each visible child element, and pass the final desired size for each child element as the parameter. Parent elements should call on each child, otherwise the child elements will not be rendered. Many derived classes offer implementations of this method. Prominent ones include: , and . @@ -5896,7 +5896,7 @@ The key identifier of the resource to be found. Searches for a resource with the specified key, and returns that resource if found. - The found resource, or if no resource with the provided is found. + The found resource, or if no resource with the provided is found. Represents the length of elements that explicitly support unit types. - and use this type to describe width and height in order to support variable distribution of available space. - - -## XAML Attribute Usage - + and use this type to describe width and height in order to support variable distribution of available space. + + +## XAML Attribute Usage + ```xaml - + ``` -or- ```xaml - -``` - - -## XAML Values - *doubleLength* - The element's length, described as either a value that specifies a device-independent units (1/96th inch per unit) measure, or as a *qualifiedDouble* (see below). - - *autoValue* - The element's length, described by either the value Auto or *. See for more information on the values Auto and *. - - *qualifiedDouble* - A *double* value as described above for any of the measures, followed by one of the following unit declaration strings: `px`, `in`, `cm`, `pt`. - - `px` (default) is device-independent units (1/96th inch per unit) - - `in` is inches; 1in==96px - - `cm` is centimeters; 1cm==(96/2.54) px - - `pt` is points; 1pt==(96/72) px - + +``` + + +## XAML Values + *doubleLength* + The element's length, described as either a value that specifies a device-independent units (1/96th inch per unit) measure, or as a *qualifiedDouble* (see below). + + *autoValue* + The element's length, described by either the value Auto or *. See for more information on the values Auto and *. + + *qualifiedDouble* + A *double* value as described above for any of the measures, followed by one of the following unit declaration strings: `px`, `in`, `cm`, `pt`. + + `px` (default) is device-independent units (1/96th inch per unit) + + `in` is inches; 1in==96px + + `cm` is centimeters; 1cm==(96/2.54) px + + `pt` is points; 1pt==(96/72) px + ]]> @@ -117,7 +117,7 @@ Initializes a new instance of the structure using the specified absolute value in pixels. To be added. - is equal to , , or . + is equal to , , or . @@ -389,11 +389,11 @@ if the property is ; otherwise, . - value is . Therefore, this property returns `true` if you do not specify a when creating the instance. - + value is . Therefore, this property returns `true` if you do not specify a when creating the instance. + ]]> diff --git a/xml/System.Windows/NameScope.xml b/xml/System.Windows/NameScope.xml index 2efb1d2dc3a..98cc6ca8f0e 100644 --- a/xml/System.Windows/NameScope.xml +++ b/xml/System.Windows/NameScope.xml @@ -300,7 +300,7 @@ ]]> - is . + is . diff --git a/xml/System.Windows/Point.xml b/xml/System.Windows/Point.xml index c98210adb86..6abeb4e775a 100644 --- a/xml/System.Windows/Point.xml +++ b/xml/System.Windows/Point.xml @@ -42,38 +42,38 @@ Represents an x- and y-coordinate pair in two-dimensional space. - and values of a can be either a comma or a space. - - Some cultures might use the comma character as the decimal delimiter instead of the period character. XAML processing for invariant culture defaults to en-US in most XAML processor implementations, and expects the period to be the decimal delimiter. You should avoid using the comma character as the decimal delimiter if specifying a in XAML, because that will clash with the string type conversion of a attribute value into the and components. - - -## XAML Attribute Usage - -``` - --or- - -``` - - -## XAML Values - *x* - The x-coordinate of this . - - *y* - The y-coordinate of this . - - - -## Examples - The following example shows how to check if two structures are not equal. It also illustrates how to assign values to a structure when the structure is being declared and after the structure has been declared. - + and values of a can be either a comma or a space. + + Some cultures might use the comma character as the decimal delimiter instead of the period character. XAML processing for invariant culture defaults to en-US in most XAML processor implementations, and expects the period to be the decimal delimiter. You should avoid using the comma character as the decimal delimiter if specifying a in XAML, because that will clash with the string type conversion of a attribute value into the and components. + + +## XAML Attribute Usage + +``` + +-or- + +``` + + +## XAML Values + *x* + The x-coordinate of this . + + *y* + The y-coordinate of this . + + + +## Examples + The following example shows how to check if two structures are not equal. It also illustrates how to assign values to a structure when the structure is being declared and after the structure has been declared. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetpointinequalityexample"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetpointinequalityexample"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetpointinequalityexample"::: + ]]> @@ -146,18 +146,18 @@ Adds a to a and returns the result as a structure. Returns the sum of and . - structure to a structure is prohibited. - - - -## Examples - This example adds a to a and returns the result as a structure. - - :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetaddpointandvectorexample_csharp"::: - + structure to a structure is prohibited. + + + +## Examples + This example adds a to a and returns the result as a structure. + + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetaddpointandvectorexample_csharp"::: + ]]> @@ -203,18 +203,18 @@ if is a and contains the same and values as this ; otherwise, . - coordinates are described using values. Because the value of a can lose precision when operated upon, a comparison between two values that are logically equal might fail. - - - -## Examples - The following example shows how to check if two structures are equal using the non-static method. - - :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetnonstaticequalsexample_csharp"::: - + coordinates are described using values. Because the value of a can lose precision when operated upon, a comparison between two values that are logically equal might fail. + + + +## Examples + The following example shows how to check if two structures are equal using the non-static method. + + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetnonstaticequalsexample_csharp"::: + ]]> @@ -251,11 +251,11 @@ if both structures contain the same and values; otherwise, . - coordinates are expressed using values. Because the value of a can lose precision when operated on, a comparison between two values that are logically equal might fail. - + coordinates are expressed using values. Because the value of a can lose precision when operated on, a comparison between two values that are logically equal might fail. + ]]> @@ -294,18 +294,18 @@ if and contain the same and values; otherwise, . - values. Because the value of a can lose precision when operated upon, a comparison between two values that are logically equal might fail. - - - -## Examples - The following example shows how to check if two structures are equal using the static method. - - :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetstaticequalsexample_csharp"::: - + values. Because the value of a can lose precision when operated upon, a comparison between two values that are logically equal might fail. + + + +## Examples + The following example shows how to check if two structures are equal using the static method. + + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetstaticequalsexample_csharp"::: + ]]> @@ -338,13 +338,13 @@ Returns the hash code for this . The hash code for this structure. - structure. - - :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetgethashcodeexample_csharp"::: - + structure. + + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetgethashcodeexample_csharp"::: + ]]> @@ -381,13 +381,13 @@ Transforms the specified structure by the specified structure. The transformed point. - structure by a structure using the method. - - :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetmultiplypointbymatrixexample_csharp"::: - + structure by a structure using the method. + + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetmultiplypointbymatrixexample_csharp"::: + ]]> @@ -424,20 +424,20 @@ The amount to offset the point's coordinate. Offsets a point's and coordinates by the specified amounts. - to a . - - Note that calling the method will only have an effect if you can change the and properties directly. Because is a value type, if you reference a object by using a property or indexer, you get a copy of the object, not a reference to the object. If you attempt to change or on a property or indexer reference, a compiler error occurs. Similarly, calling on the property or indexer will not change the underlying object. If you want to change the value of a that is referenced as a property or indexer, create a new , modify its fields, and then assign the back to the property or indexer. - - - -## Examples - The following example shows how to offset the and values of a structure. - - :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetoffsetexample_csharp"::: - + to a . + + Note that calling the method will only have an effect if you can change the and properties directly. Because is a value type, if you reference a object by using a property or indexer, you get a copy of the object, not a reference to the object. If you attempt to change or on a property or indexer reference, a compiler error occurs. Similarly, calling on the property or indexer will not change the underlying object. If you want to change the value of a that is referenced as a property or indexer, create a new , modify its fields, and then assign the back to the property or indexer. + + + +## Examples + The following example shows how to offset the and values of a structure. + + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetoffsetexample_csharp"::: + ]]> @@ -474,14 +474,14 @@ Translates the specified by the specified and returns the result. The result of translating the specified point by the specified vector. - to a using the overloaded (+) operator. - + to a using the overloaded (+) operator. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetoverloadedadditionoperatorexample"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedadditionoperatorexample"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedadditionoperatorexample"::: + ]]> @@ -520,19 +520,19 @@ if both the and coordinates of and are equal; otherwise, . - values. Because the value of can lose precision when arithmetic operations are performed on them, a comparison between two values that are logically equal might fail. - - - -## Examples - The following example shows how to check if two structures are equal using the overloaded (==) operator. - + values. Because the value of can lose precision when arithmetic operations are performed on them, a comparison between two values that are logically equal might fail. + + + +## Examples + The following example shows how to check if two structures are equal using the overloaded (==) operator. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetoverloadedequalityoperatorexample"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedequalityoperatorexample"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedequalityoperatorexample"::: + ]]> @@ -577,19 +577,19 @@ Creates a structure with a equal to this point's value and a equal to this point's value. A structure with a equal to this point's value and a equal to this point's value. - structure cannot be negative, the absolute values of the point's and properties are used. - - - -## Examples - The following example shows how to explicitly convert a into a . - + structure cannot be negative, the absolute values of the point's and properties are used. + + + +## Examples + The following example shows how to explicitly convert a into a . + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetoverloadedexplicitoperatorsizeexample"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedexplicitoperatorsizeexample"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedexplicitoperatorsizeexample"::: + ]]> @@ -624,14 +624,14 @@ Creates a structure with an value equal to the point's value and a value equal to the point's value. A vector with an value equal to the point's value and a value equal to the point's value. - into a . - + into a . + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetoverloadedexplicitoperatorvectorexample"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedexplicitoperatorvectorexample"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedexplicitoperatorvectorexample"::: + ]]> @@ -669,19 +669,19 @@ if and have different or coordinates; if and have the same and coordinates. - and coordinates are described using values. Because values can lose precision when operated on, a comparison between two values that are logically equal might fail. - - - -## Examples - The following example shows how to check whether two structures are not equal, using the overloaded (!=) operator. - + and coordinates are described using values. Because values can lose precision when operated on, a comparison between two values that are logically equal might fail. + + + +## Examples + The following example shows how to check whether two structures are not equal, using the overloaded (!=) operator. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetoverloadedinequalityoperatorexample"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedinequalityoperatorexample"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedinequalityoperatorexample"::: + ]]> @@ -718,14 +718,14 @@ Transforms the specified by the specified . The result of transforming the specified point using the specified matrix. - by a using the overloaded (*) operator. - + by a using the overloaded (*) operator. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetoverloadedmultiplypointbymatrixoperatorexample"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedmultiplypointbymatrixoperatorexample"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedmultiplypointbymatrixoperatorexample"::: + ]]> @@ -772,14 +772,14 @@ Subtracts the specified from another specified and returns the difference as a . The difference between and . - from another and return a using the overloaded (-) operator. - + from another and return a using the overloaded (-) operator. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetoverloadedsubtractionoperatorexample2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedsubtractionoperatorexample2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedsubtractionoperatorexample2"::: + ]]> @@ -813,18 +813,18 @@ The point from which is subtracted. - The vector to subtract from . + The vector to subtract from . Subtracts the specified from the specified and returns the resulting . The difference between and . - from a using the overloaded (-) operator. - + from a using the overloaded (-) operator. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetoverloadedsubtractionoperatorexample1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedsubtractionoperatorexample1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetoverloadedsubtractionoperatorexample1"::: + ]]> @@ -860,23 +860,23 @@ Constructs a from the specified . The equivalent structure. - method to convert a representation of a point into a structure. - + method to convert a representation of a point into a structure. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetparseexample"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetparseexample"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetparseexample"::: + ]]> is not composed of two comma- or space-delimited double values. - does not contain two numbers. - - -or- - + does not contain two numbers. + + -or- + contains too many delimiters. @@ -921,14 +921,14 @@ Subtracts the specified from another specified and returns the difference as a . The difference between and . - from another using the static method. - + from another using the static method. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetsubtractexample2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetsubtractexample2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetsubtractexample2"::: + ]]> @@ -966,14 +966,14 @@ Subtracts the specified from the specified and returns the resulting . The difference between and . - from a using the static method. - + from a using the static method. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetsubtractexample1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetsubtractexample1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetsubtractexample1"::: + ]]> @@ -1015,15 +1015,15 @@ - The string specifying the format to use. - - -or- - + The string specifying the format to use. + + -or- + to use the default format defined for the type of the implementation. - The to use to format the value. - - -or- - + The to use to format the value. + + -or- + to obtain the numeric format information from the current locale setting of the operating system. This member supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used directly from your code. For a description of this member, see . A string containing the value of the current instance in the specified format. @@ -1072,14 +1072,14 @@ Creates a representation of this . A containing the and values of this structure. - method to get a representation of a structure. - + method to get a representation of a structure. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippettostringexample"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippettostringexample"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippettostringexample"::: + ]]> @@ -1158,14 +1158,14 @@ Gets or sets the -coordinate value of this structure. The -coordinate value of this structure. The default value is 0. - structures are not equal. It also illustrates how to assign values to a structure when the structure is being declared and after the structure has been declared. - + structures are not equal. It also illustrates how to assign values to a structure when the structure is being declared and after the structure has been declared. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetpointinequalityexample"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetpointinequalityexample"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetpointinequalityexample"::: + ]]> @@ -1207,14 +1207,14 @@ Gets or sets the -coordinate value of this . The -coordinate value of this structure. The default value is 0. - structures are not equal. It also illustrates how to assign values to a structure when the structure is being declared and after the structure has been declared. - + structures are not equal. It also illustrates how to assign values to a structure when the structure is being declared and after the structure has been declared. + :::code language="csharp" source="~/snippets/csharp/System.Windows/Point/Overview/PointExample.cs" id="Snippetpointinequalityexample"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetpointinequalityexample"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PointExamples_snip/visualbasic/pointexample.vb" id="Snippetpointinequalityexample"::: + ]]> diff --git a/xml/System.Windows/SizeConverter.xml b/xml/System.Windows/SizeConverter.xml index db4f84ef930..74dffc7543f 100644 --- a/xml/System.Windows/SizeConverter.xml +++ b/xml/System.Windows/SizeConverter.xml @@ -23,11 +23,11 @@ Converts instances of other types to and from instances of the class. - class supports conversion of values and base values that the class supports. - + class supports conversion of values and base values that the class supports. + ]]> @@ -171,13 +171,13 @@ Culture-specific information that should be respected during conversion. The source object that is being converted. Attempts to convert a specified object to an instance of . - The instance of that is created from the converted . + The instance of that is created from the converted . To be added. - is . - --or- + is . + +-or- cannot be converted to a . diff --git a/xml/System.Windows/StrokeCollectionConverter.xml b/xml/System.Windows/StrokeCollectionConverter.xml index c95d846cfcc..ff61d281f36 100644 --- a/xml/System.Windows/StrokeCollectionConverter.xml +++ b/xml/System.Windows/StrokeCollectionConverter.xml @@ -23,19 +23,19 @@ Converts a to a string. - converts a to a string that represents the in base-64, encoded Ink Serialized Format (ISF). It is useful to store ink data as base-64, encoded ISF when it is not possible to store raw byte data, such as in Web pages. - -## Examples - The following example demonstrates how to convert a base-64, encoded ISF string to a . This assumes that there is an called `presenter`. - + converts a to a string that represents the in base-64, encoded Ink Serialized Format (ISF). It is useful to store ink data as base-64, encoded ISF when it is not possible to store raw byte data, such as in Web pages. + +## Examples + The following example demonstrates how to convert a base-64, encoded ISF string to a . This assumes that there is an called `presenter`. + :::code language="csharp" source="~/snippets/csharp/System.Windows/StrokeCollectionConverter/Overview/InkEraser.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/InkEraser/VisualBasic/InkEraser.vb" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/InkEraser/VisualBasic/InkEraser.vb" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Windows/StrokeCollectionConverter/Overview/InkEraser.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/InkEraser/VisualBasic/InkEraser.vb" id="Snippet3"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/InkEraser/VisualBasic/InkEraser.vb" id="Snippet3"::: + ]]> @@ -138,7 +138,7 @@ The to convert to. Returns a value that indicates whether the can convert a to the specified type. - if the can convert a to the ; otherwise, . + if the can convert a to the ; otherwise, . To be added. @@ -177,21 +177,21 @@ Converts the specified object to a . A converted from . - method returns `null` if `value` is not a . - - - -## Examples - The following example demonstrates how to convert a base-64, encoded Ink Serialized Format (ISF) string to a . This assumes that there is an called `presenter`. - + method returns `null` if `value` is not a . + + + +## Examples + The following example demonstrates how to convert a base-64, encoded Ink Serialized Format (ISF) string to a . This assumes that there is an called `presenter`. + :::code language="csharp" source="~/snippets/csharp/System.Windows/StrokeCollectionConverter/Overview/InkEraser.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/InkEraser/VisualBasic/InkEraser.vb" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/InkEraser/VisualBasic/InkEraser.vb" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Windows/StrokeCollectionConverter/Overview/InkEraser.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/InkEraser/VisualBasic/InkEraser.vb" id="Snippet3"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/InkEraser/VisualBasic/InkEraser.vb" id="Snippet3"::: + ]]> @@ -239,13 +239,13 @@ Converts a to a string. An object that represents the specified . - method returns `null` if `value` is not a , or if `destinationType` is not or . - - The method returns a base-64, encoded Ink Serialized Format (ISF). It is useful to store ink data as base-64, encoded ISF when it is not possible to store raw byte data, such as in Web pages. - + method returns `null` if `value` is not a , or if `destinationType` is not or . + + The method returns a base-64, encoded Ink Serialized Format (ISF). It is useful to store ink data as base-64, encoded ISF when it is not possible to store raw byte data, such as in Web pages. + ]]> diff --git a/xml/System.Windows/UIElement.xml b/xml/System.Windows/UIElement.xml index 4a133e1a850..29cf3d46293 100644 --- a/xml/System.Windows/UIElement.xml +++ b/xml/System.Windows/UIElement.xml @@ -2138,9 +2138,8 @@ For this call to be successful, some other element in the application needed to is the Microsoft .NET property accessor for what is in reality a dependency property. This particular dependency property quite frequently has its apparent "default" value set differently in derived element classes, particularly in controls. This commonly occurs in one of two ways: -- The dependency property is inherited by a particular derived class, but that derived class overrides the metadata of the dependency property and changes the property default value. - -- A style or template is applied to an element, which sets that dependency property value differently. +- The dependency property is inherited by a particular derived class, but that derived class overrides the metadata of the dependency property and changes the property default value. +- A style or template is applied to an element, which sets that dependency property value differently. For example, the apparent "default" of for a control will be `true`, even though inherits as a common language runtime (CLR) property directly from . This is because the applied metadata value for the dependency property was overridden within the static constructor of the base class, which is situated between and in the class hierarchy. @@ -2156,8 +2155,6 @@ For this call to be successful, some other element in the application needed to |Identifier field|| |Metadata properties set to `true`|None| - - ## Examples The following example code illustrates a control template for a particular custom control, which sets `false` on one of the elements within the template. @@ -2171,7 +2168,7 @@ For this call to be successful, some other element in the application needed to :::code language="csharp" source="~/snippets/csharp/System.Windows/ComponentResourceKey/.ctor/corepseudocode.cs" id="Snippetuielementshortoverride"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/CorePseudocode/visualbasic/corepseudocode.vb" id="Snippetuielementshortoverride"::: - where should be the class name of the type that you are overriding the metadata value on. + should be the class name of the type that you are overriding the metadata value on. diff --git a/xml/System.Xaml.Schema/XamlTypeInvoker.xml b/xml/System.Xaml.Schema/XamlTypeInvoker.xml index 512104801e6..2493819f140 100644 --- a/xml/System.Xaml.Schema/XamlTypeInvoker.xml +++ b/xml/System.Xaml.Schema/XamlTypeInvoker.xml @@ -169,7 +169,7 @@ Internally, the base implementation calls , and throws if the result is . - The base implementation does not necessarily use its own implementation. First, a cast of to is attempted. If this succeeds, a call to is made and the method returns. Otherwise, the base implementation uses CLR to invoke the underlying method, as obtained from a call to for this . + The base implementation does not necessarily use its own implementation. First, a cast of to is attempted. If this succeeds, a call to is made and the method returns. Otherwise, the base implementation uses CLR to invoke the underlying method, as obtained from a call to for this . In the base implementation no exception is raised at this level if is . It is still possible that the underlying method will raise an exception when invoked. Other run time exceptions are possible if does not return a valid result. @@ -228,7 +228,7 @@ Internally, the base implementation calls , and throws if the result is . - The base implementation does not necessarily use its own implementation. First, a cast of to is attempted. If this succeeds, a call to is made and the method returns. Otherwise, the base implementation uses CLR to invoke the underlying method, as obtained from a call to for this . + The base implementation does not necessarily use its own implementation. First, a cast of to is attempted. If this succeeds, a call to is made and the method returns. Otherwise, the base implementation uses CLR to invoke the underlying method, as obtained from a call to for this . In the base implementation no exception is raised at this level if or is . It is still possible that the underlying method will raise an exception when invoked. Other run time exceptions are possible if does not return a valid result. @@ -399,7 +399,7 @@ The base implementation includes a call to the internal helper ThrowIfUnknown. This helper always throws for cases where a is based on an unknown , which includes cases where the of the is . - The base implementation does not necessarily use its own implementation. First, a cast of to is attempted. If this succeeds, a call to is made and the method returns that return value. Otherwise, the base implementation uses CLR to invoke the underlying method, as obtained from a call to for this . + The base implementation does not necessarily use its own implementation. First, a cast of to is attempted. If this succeeds, a call to is made and the method returns that return value. Otherwise, the base implementation uses CLR to invoke the underlying method, as obtained from a call to for this . diff --git a/xml/System.Xaml/AttachableMemberIdentifier.xml b/xml/System.Xaml/AttachableMemberIdentifier.xml index a69a1bfd2f6..e10fb703f19 100644 --- a/xml/System.Xaml/AttachableMemberIdentifier.xml +++ b/xml/System.Xaml/AttachableMemberIdentifier.xml @@ -24,7 +24,7 @@ - Provides a XAML type system identifier representation for attachable members. The identifier structure parallels the string form for attachable member usage. + Provides a XAML type system identifier representation for attachable members. The identifier structure parallels the string form for attachable member usage. To be added. @@ -96,11 +96,11 @@ Gets or sets the component value of the . The component value of the . - value should match the name of the of the attachable member's XAML type system information. - + value should match the name of the of the attachable member's XAML type system information. + ]]> @@ -179,11 +179,11 @@ if the objects have the same value; otherwise, . - and . - + and . + ]]> @@ -247,11 +247,11 @@ Gets or sets the component value of the . The component value of the . - value should match the of the attachable member's XAML type system information. - + value should match the of the attachable member's XAML type system information. + ]]> @@ -350,11 +350,11 @@ Returns a that represents the current . A that represents the current . - diff --git a/xml/System.Xaml/XamlNodeQueue.xml b/xml/System.Xaml/XamlNodeQueue.xml index 1f99250583a..36d0512c26a 100644 --- a/xml/System.Xaml/XamlNodeQueue.xml +++ b/xml/System.Xaml/XamlNodeQueue.xml @@ -22,13 +22,13 @@ Provides a buffer for writing nodes and reading them again. - when they are read by the XAML reader. If you require a list of XAML nodes that can be replayed, or a list model that supports random access, see . - - When you create a , you create a writer delegate that exists as the value. The writer delegate is based on an internal XAML writer class that is specifically for XAML nodes. - + when they are read by the XAML reader. If you require a list of XAML nodes that can be replayed, or a list model that supports random access, see . + + When you create a , you create a writer delegate that exists as the value. The writer delegate is based on an internal XAML writer class that is specifically for XAML nodes. + ]]> @@ -58,15 +58,15 @@ The schema context to use for node operations. Initializes a new instance of the class using a provided XAML schema context. - value. - + value. + ]]> - is . + is . diff --git a/xml/System.Xaml/XamlObjectWriter.xml b/xml/System.Xaml/XamlObjectWriter.xml index 7c0e9d2b771..7ad5c72b86f 100644 --- a/xml/System.Xaml/XamlObjectWriter.xml +++ b/xml/System.Xaml/XamlObjectWriter.xml @@ -26,35 +26,35 @@ Creates an object graph from a source XAML node stream. - implement a pattern so that the uses the that is defined by the method. logic switches between the `Write` methods, depending on which node type is at the current position in the reader. - -## Scope - A has a concept of scope; that is, the maintains a conceptual point of reference in its output object graph. For a particular scope, certain operations might be valid or invalid, or produce a no-operation result. For example, if you call to write directives for initialization on an object that already exists as an instance, the default implementation throws an exception. - - A possible technique for tracking scope in a custom is to align the node actions with a stack or frame class. The stack or frame can keep track of push and pop for each level of object-model depth that is entered or exited while the writes the object graph. - -## Callbacks - To support intermediate and advanced scenarios, the mechanism of writing an object graph provides callback entry points that occur when a commits or is about to commit certain actions. Some callbacks are enabled in the settings and are not specific to the object type or the member being written; however, callback information is often available in context or is in the event data that is sent through the callback. The following is a list of relevant callbacks: - -- The callback that is declared by is invoked when the scope goes to a new object and at the phase of object lifetime for each created object. - -- The callback that is declared by is invoked when the scope goes to a new object and at the phase of object lifetime for each created object. - -- The callback that is declared by is invoked when the scope starts in an object, and occurs when the first call to that object scope is made but not yet committed. - -- The callback that is declared by is invoked when the scope starts in an object, and happens when the call to that object scope is made but not yet committed. - -- The callback that is declared by is invoked when is called. - -## Writing Dictionary Keys - The default implementation of supports type conversion on the constraints of a before the dictionary contents are added to the object graph. In this manner, a generic dictionary can be keyed at run time by objects and can match the relevant generic `Add` and indexer behavior. However, as implemented for the base , this capability exists only for object graph creation from the base class and not for derived classes of . - -## Checks for Disposed - XAML writers are potentially used for deferred operations or where a call is made against a XAML writer instance that has been disposed in the interim. Various APIs of might throw in these cases. - + implement a pattern so that the uses the that is defined by the method. logic switches between the `Write` methods, depending on which node type is at the current position in the reader. + +## Scope + A has a concept of scope; that is, the maintains a conceptual point of reference in its output object graph. For a particular scope, certain operations might be valid or invalid, or produce a no-operation result. For example, if you call to write directives for initialization on an object that already exists as an instance, the default implementation throws an exception. + + A possible technique for tracking scope in a custom is to align the node actions with a stack or frame class. The stack or frame can keep track of push and pop for each level of object-model depth that is entered or exited while the writes the object graph. + +## Callbacks + To support intermediate and advanced scenarios, the mechanism of writing an object graph provides callback entry points that occur when a commits or is about to commit certain actions. Some callbacks are enabled in the settings and are not specific to the object type or the member being written; however, callback information is often available in context or is in the event data that is sent through the callback. The following is a list of relevant callbacks: + +- The callback that is declared by is invoked when the scope goes to a new object and at the phase of object lifetime for each created object. + +- The callback that is declared by is invoked when the scope goes to a new object and at the phase of object lifetime for each created object. + +- The callback that is declared by is invoked when the scope starts in an object, and occurs when the first call to that object scope is made but not yet committed. + +- The callback that is declared by is invoked when the scope starts in an object, and happens when the call to that object scope is made but not yet committed. + +- The callback that is declared by is invoked when is called. + +## Writing Dictionary Keys + The default implementation of supports type conversion on the constraints of a before the dictionary contents are added to the object graph. In this manner, a generic dictionary can be keyed at run time by objects and can match the relevant generic `Add` and indexer behavior. However, as implemented for the base , this capability exists only for object graph creation from the base class and not for derived classes of . + +## Checks for Disposed + XAML writers are potentially used for deferred operations or where a call is made against a XAML writer instance that has been disposed in the interim. Various APIs of might throw in these cases. + ]]> @@ -337,15 +337,15 @@ The object to report as the source to the handler. The name of the property to set, which is passed to the handler as part of . - The value to provide for the property that is named by . The value is passed to the handler as part of . + The value to provide for the property that's named by . The value is passed to the handler as part of . Invokes any referenced method that is associated with for this writer, as long as in event data is not . A Boolean value that is set by any associated handler; otherwise, . - is declared in ), this method creates new and passes them to the handler. The return value is set by reading the value that is passed through the event data. If no handler exists and this method is invoked, the call returns `false`. - + is declared in ), this method creates new and passes them to the handler. The return value is set by reading the value that is passed through the event data. If no handler exists and this method is invoked, the call returns `false`. + ]]> @@ -381,13 +381,13 @@ Gets the last object that was written. Typically only called when the node stream is at its end and the object graph is complete. The last object written, or . - is to call it only when the node stream is known to be at its end, and the object graph is complete. Otherwise, the object graph is likely to be incomplete, and is not useful for most platform scenarios. - - typically only contains a non-null value if it is called immediately after a call to , and if the current scope is in the member where the object provides a value. - + is to call it only when the node stream is known to be at its end, and the object graph is complete. Otherwise, the object graph is likely to be incomplete, and is not useful for most platform scenarios. + + typically only contains a non-null value if it is called immediately after a call to , and if the current scope is in the member where the object provides a value. + ]]> @@ -417,11 +417,11 @@ Gets the service that maintains the XAML namescope for the absolute node root of the XAML object writer. The service that maintains the XAML namescope for the current root of the object writer. - @@ -451,11 +451,11 @@ Gets the active XAML schema context. The XAML schema context. - @@ -493,11 +493,11 @@ The line position from the reader. Implements and provides line information for exceptions. - and expect to report a context where line numbers are unavailable or not useful, this method may be called. - + and expect to report a context where line numbers are unavailable or not useful, this method may be called. + ]]> @@ -531,11 +531,11 @@ if line information is used by the writer; otherwise, . - @@ -593,13 +593,13 @@ Closes the current object scope in the writer. The new object scope becomes the parent member scope. - might not yet have created the object because an object member might be a necessary initialization pathway, such as initialization text or initialization parameters. For these cases, the call to actually writes the object. - + might not yet have created the object because an object member might be a necessary initialization pathway, such as initialization text or initialization parameters. For these cases, the call to actually writes the object. + ]]> @@ -629,15 +629,15 @@ Writes the conceptual into the object graph when the specified object is a default or implicit value of the parent property. The implicit value comes from information that is obtained from the XAML schema context and backing type information, instead of being specified as an object value in the input XAML node set. - and writing with can be seen in the resulting object graph. does not construct an instance of a type because the API has no information to inform the object graph of what to construct. Instead, the object was created when the parent property was initialized; so a does not need to construct it. In contrast, specifies that an instance of that type should be constructed and inserted into the object graph. - - If you think of the XAML node stream as a series of frames, a is balanced to a call. Therefore, the number of plus calls should equal the number of calls as part of a complete object-writing evaluation of the XAML node stream. - - The conceptual `StartObject` position for an implicit object in the object graph is necessary because although the object value itself is an implicit default, that object might still have members that need to be written based on the XAML node stream. A typical scenario where this occurs is when writes member nodes for a collection property, and the collection initialization is implicit to creating the object that owns the collection property. - + and writing with can be seen in the resulting object graph. does not construct an instance of a type because the API has no information to inform the object graph of what to construct. Instead, the object was created when the parent property was initialized; so a does not need to construct it. In contrast, specifies that an instance of that type should be constructed and inserted into the object graph. + + If you think of the XAML node stream as a series of frames, a is balanced to a call. Therefore, the number of plus calls should equal the number of calls as part of a complete object-writing evaluation of the XAML node stream. + + The conceptual `StartObject` position for an implicit object in the object graph is necessary because although the object value itself is an implicit default, that object might still have members that need to be written based on the XAML node stream. A typical scenario where this occurs is when writes member nodes for a collection property, and the collection initialization is implicit to creating the object that owns the collection property. + ]]> @@ -670,15 +670,15 @@ The namespace declaration to write. Defines a namespace declaration that applies to the next object scope or member scope. - can only be called immediately before a call to one of the following: , , or . The consecutive case is for writing multiple namespace declarations to the same node. Eventually, either or must be called. - - does not use a `Start`/`End` metaphor. Although a XAML namespace has members in the CLR representation sense, the members are known and do not need to be represented as a special type of for extensibility. To access the values of a , you access its and properties. - - A namespace declaration may have a value for the prefix. A prefix represents a declaration of the default XAML namespace. Do not attempt to use null to represent the default prefix; it throws an exception in this API. For more information, see . - + can only be called immediately before a call to one of the following: , , or . The consecutive case is for writing multiple namespace declarations to the same node. Eventually, either or must be called. + + does not use a `Start`/`End` metaphor. Although a XAML namespace has members in the CLR representation sense, the members are known and do not need to be represented as a special type of for extensibility. To access the values of a , you access its and properties. + + A namespace declaration may have a value for the prefix. A prefix represents a declaration of the default XAML namespace. Do not attempt to use null to represent the default prefix; it throws an exception in this API. For more information, see . + ]]> The is . @@ -714,24 +714,24 @@ The XAML property to write. Typically you obtain this value from a XAML reader through the XAML node stream intermediate. Writes a new member node into the current object scope, and the scope becomes a new member scope. - [!TIP] -> Watch for a , which occurs when the same XAML property is set twice in the XAML input. In simple cases, such as when the same property is set in both attribute syntax and property element syntax, you can easily see this exception in the input markup. However, more subtle cases can occur that are more difficult to spot. For example, this exception might occur if you set a XAML content property, if you involve XAML ambient properties, and if a property enables both an attachable usage and an instance usage. In the debugging phases of development, you can often locate this exception by viewing the intermediate XAML node representation that connects the markup read and the object graph write. - +> Watch for a , which occurs when the same XAML property is set twice in the XAML input. In simple cases, such as when the same property is set in both attribute syntax and property element syntax, you can easily see this exception in the input markup. However, more subtle cases can occur that are more difficult to spot. For example, this exception might occur if you set a XAML content property, if you involve XAML ambient properties, and if a property enables both an attachable usage and an instance usage. In the debugging phases of development, you can often locate this exception by viewing the intermediate XAML node representation that connects the markup read and the object graph write. + ]]> - has set to . - - -or- - - passed, which indicates that the XAML node stream contained content for an object that does not support content. - - -or- - + has set to . + + -or- + + passed, which indicates that the XAML node stream contained content for an object that does not support content. + + -or- + Attempted to write a start member in an invalid scope. specifies a property that is already explicitly set in the parent object scope. @@ -767,10 +767,10 @@ The type to write. Typically you obtain this value from a XAML reader. Writes an object node into the current scope, and sets the scope to a new object scope. To be added. - Processing an type and cannot create an object. - - -or- - + Processing an type and cannot create an object. + + -or- + Attempted to write a start object in an invalid scope. Attempted to write a root object when the root object was already provided in the settings. diff --git a/xml/System.Xaml/XamlServices.xml b/xml/System.Xaml/XamlServices.xml index f2064f8fcc8..ee8122c236b 100644 --- a/xml/System.Xaml/XamlServices.xml +++ b/xml/System.Xaml/XamlServices.xml @@ -22,14 +22,14 @@ Provides higher-level services (static methods) for the common XAML tasks of reading XAML and writing an object graph; or reading an object graph and writing XAML file output for serialization purposes. - class that are used in the most common XAML reading and writing scenarios rely on creating instances of XAML readers and XAML writers. These readers and writers are specialized but internal implementations of public classes, such as , , and . To use for most scenarios, you can rely on the default internal implementations to obtain the results that you want. For more specialized scenarios, you might define readers and writers yourself, and then pass them as arguments for overloads of the methods. - + class that are used in the most common XAML reading and writing scenarios rely on creating instances of XAML readers and XAML writers. These readers and writers are specialized but internal implementations of public classes, such as , , and . To use for most scenarios, you can rely on the default internal implementations to obtain the results that you want. For more specialized scenarios, you might define readers and writers yourself, and then pass them as arguments for overloads of the methods. + > [!IMPORTANT] -> is not the recommended XAML reading or XAML writing API set if you are processing WPF-defined types, or types based on WPF. For WPF usage, use for reading or loading XAML (or BAML); and for writing back XAML. These classes use .NET Framework XAML Services APIs and the XAML readers and XAML writers internally in their implementation; however, they also provide support and specialized XAML schema context for WPF-specific concepts, such as optimizations for dependency properties and WPF known types. - +> is not the recommended XAML reading or XAML writing API set if you are processing WPF-defined types, or types based on WPF. For WPF usage, use for reading or loading XAML (or BAML); and for writing back XAML. These classes use .NET Framework XAML Services APIs and the XAML readers and XAML writers internally in their implementation; however, they also provide support and specialized XAML schema context for WPF-specific concepts, such as optimizations for dependency properties and WPF known types. + ]]> @@ -72,22 +72,22 @@ Loads a source for a XAML reader and writes its output as an object graph. The object graph that is written as output. - method specify different types of input for the source XAML. The internal implementation first creates an by calling and then creates a new instance of a specialized that processes the input. - - In order for the call to successfully create an object graph, the following must be true: - -- The source is well-formed and valid XML. - -- The source is valid XAML at the language level. - -- The XAML types that are specified in the source XAML must resolve to backing types in the relevant XAML namespaces. For example, XAML types for WPF namespaces can resolve to a WPF XAML namespace as specified in the XAML; the assemblies for WPF must be included in the project or available in the run time; and so on. - + method specify different types of input for the source XAML. The internal implementation first creates an by calling and then creates a new instance of a specialized that processes the input. + + In order for the call to successfully create an object graph, the following must be true: + +- The source is well-formed and valid XML. + +- The source is valid XAML at the language level. + +- The XAML types that are specified in the source XAML must resolve to backing types in the relevant XAML namespaces. For example, XAML types for WPF namespaces can resolve to a WPF XAML namespace as specified in the XAML; the assemblies for WPF must be included in the project or available in the run time; and so on. + > [!IMPORTANT] -> is not the recommended XAML reading or XAML writing API set if you are processing Windows Presentation Foundation (WPF) types, or types based on WPF. For WPF usage, use for reading or loading XAML; and for writing back XAML. These classes use APIs internally in their implementation; however, they also provide support for WPF-specific concepts that influence the nature of XAML reading and writing, such as optimizations for dependency properties. - +> is not the recommended XAML reading or XAML writing API set if you are processing Windows Presentation Foundation (WPF) types, or types based on WPF. For WPF usage, use for reading or loading XAML; and for writing back XAML. These classes use APIs internally in their implementation; however, they also provide support for WPF-specific concepts that influence the nature of XAML reading and writing, such as optimizations for dependency properties. + ]]> @@ -123,11 +123,11 @@ Creates a XAML reader from a , and returns an object graph. The object graph that is returned. - that is constructed by using a valid XAML-as-string input for the constructor. - + that is constructed by using a valid XAML-as-string input for the constructor. + ]]> @@ -163,19 +163,19 @@ Loads a source for a XAML reader and returns an object graph. The object graph that is returned. - method specify different types of input for the source XAML. The internal implementation first creates an by calling and then creates a new instance of a specialized that processes the input. - - In order for the call to successfully create an object graph, the following must be true: - -- The source is well-formed and valid XML. - -- The source is valid XAML at the language level. - -- The XAML types that are specified in the source XAML must resolve to backing types in the relevant XAML namespaces. For example, XAML types for WPF namespaces can resolve to a WPF XAML namespace as specified in the XAML; the assemblies for WPF must be included in the project or be available in the run time; and so on. - + method specify different types of input for the source XAML. The internal implementation first creates an by calling and then creates a new instance of a specialized that processes the input. + + In order for the call to successfully create an object graph, the following must be true: + +- The source is well-formed and valid XML. + +- The source is valid XAML at the language level. + +- The XAML types that are specified in the source XAML must resolve to backing types in the relevant XAML namespaces. For example, XAML types for WPF namespaces can resolve to a WPF XAML namespace as specified in the XAML; the assemblies for WPF must be included in the project or be available in the run time; and so on. + ]]> @@ -211,15 +211,15 @@ Loads a specific XAML reader implementation and returns an object graph. The object graph that is returned. - . - -- You specified settings for a that differ from the default settings. - + . + +- You specified settings for a that differ from the default settings. + ]]> @@ -255,15 +255,15 @@ Loads a specific XML reader implementation and returns an object graph. The output object graph. - . - + . + ]]> - input is . + input is . @@ -295,20 +295,20 @@ Reads XAML as string output and returns an object graph. The object graph that is returned. - call to successfully create an object tree, the following must be true: - -- The `xaml` input is well-formed and valid XML. - -- The `xaml` input is valid XAML at the language level. - -- The XAML types that are specified in the `xaml` input must resolve to backing types in the relevant XAML namespaces. For example, XAML types for a WPF namespace can resolve to a WPF XAML namespace as specified in the XAML; the assemblies for WPF must be included in the project or be available in the run time; and so on. - + call to successfully create an object tree, the following must be true: + +- The `xaml` input is well-formed and valid XML. + +- The `xaml` input is valid XAML at the language level. + +- The XAML types that are specified in the `xaml` input must resolve to backing types in the relevant XAML namespaces. For example, XAML types for a WPF namespace can resolve to a WPF XAML namespace as specified in the XAML; the assemblies for WPF must be included in the project or be available in the run time; and so on. + > [!IMPORTANT] -> is not the recommended XAML reading or XAML writing API set if you are processing Windows Presentation Foundation (WPF) types, or types based on WPF. For WPF usage, use for reading or loading XAML, and for writing back XAML. These classes use APIs internally in their implementation; however, they also provide support for WPF-specific concepts that influence the nature of XAML reading and writing, such as optimizations for dependency properties. - +> is not the recommended XAML reading or XAML writing API set if you are processing Windows Presentation Foundation (WPF) types, or types based on WPF. For WPF usage, use for reading or loading XAML, and for writing back XAML. These classes use APIs internally in their implementation; however, they also provide support for WPF-specific concepts that influence the nature of XAML reading and writing, such as optimizations for dependency properties. + ]]> @@ -353,13 +353,13 @@ Processes a provided object tree into a XAML node representation, and returns a string representation of the output XAML. The XAML markup output as a string. - that is created by the method call. That is created by using the following settings: is `true`; and is `true`. - - The returned string can be loaded as valid XML through the method if you processed the string into a stream, or into a reader more specifically dedicated for XAML. - + that is created by the method call. That is created by using the following settings: is `true`; and is `true`. + + The returned string can be loaded as valid XML through the method if you processed the string into a stream, or into a reader more specifically dedicated for XAML. + ]]> @@ -394,13 +394,13 @@ The root of the object graph to process. Processes a provided object graph into a XAML node representation and then into an output stream for serialization. - [!IMPORTANT] -> is not the recommended XAML reading or XAML writing API set if you are processing Windows Presentation Foundation (WPF) types, or types based on WPF. For WPF usage, use for reading or loading XAML; and for writing back XAML. These classes use APIs internally in their implementation; however, they also provide support for WPF-specific concepts that influence the nature of XAML reading and writing, such as optimizations for dependency properties. - +> is not the recommended XAML reading or XAML writing API set if you are processing Windows Presentation Foundation (WPF) types, or types based on WPF. For WPF usage, use for reading or loading XAML; and for writing back XAML. These classes use APIs internally in their implementation; however, they also provide support for WPF-specific concepts that influence the nature of XAML reading and writing, such as optimizations for dependency properties. + ]]> @@ -471,11 +471,11 @@ The root of the object graph to process. Processes a provided object graph into a XAML node representation and then writes it to an output file at a provided location. - , which creates a as part of the method call. - + , which creates a as part of the method call. + ]]> @@ -514,15 +514,15 @@ The root of the object graph to process. Processes a provided object graph into a XAML node representation and then writes it to the provided XAML writer. - . - -- You specified settings for the that differ from the default settings. - + . + +- You specified settings for the that differ from the default settings. + ]]> @@ -608,11 +608,11 @@ The to use. Connects a and a to use a common XAML node set intermediary. Potentially transforms the content, depending on the types of readers and writers that are provided. - , where `closeWriter` is specified as `true`. - + , where `closeWriter` is specified as `true`. + ]]> diff --git a/xml/System.Xaml/XamlXmlReader.xml b/xml/System.Xaml/XamlXmlReader.xml index 307d09371a6..884a614383b 100644 --- a/xml/System.Xaml/XamlXmlReader.xml +++ b/xml/System.Xaml/XamlXmlReader.xml @@ -26,13 +26,13 @@ Processes XAML markup from XML files by using an intermediary, and produces a XAML node stream. - , an is required. The purpose of this design is to use established .NET Framework APIs for XML processing in order to handle stream input, to obtain a stream from a file, and so on. - - is the first component of the standard load path for XAML operations and is incorporated by as well as by several existing framework XAML implementations for loading XAML. - + , an is required. The purpose of this design is to use established .NET Framework APIs for XML processing in order to handle stream input, to obtain a stream from a file, and so on. + + is the first component of the standard load path for XAML operations and is incorporated by as well as by several existing framework XAML implementations for loading XAML. + ]]> @@ -161,11 +161,11 @@ The to use as the intermediary XML processor. Initializes a new instance of the class using the provided . - @@ -230,11 +230,11 @@ The specific reader settings. Initializes a new instance of the class, based on a stream, with XAML-specific settings. - . - + . + ]]> @@ -269,10 +269,10 @@ Initializes a new instance of the class, based on a , with a supplied schema context and XAML-specific settings. To be added. - is . - - -or- - + is . + + -or- + is . @@ -303,11 +303,11 @@ The specific reader settings. Initializes a new instance of the class, based on a , and using XAML-specific settings. - . - + . + ]]> @@ -403,11 +403,11 @@ The XAML schema context for XAML processing. Initializes a new instance of the class using the provided and schema context. - @@ -441,15 +441,15 @@ The specific XAML reader settings. Initializes a new instance of the class, using the provided and reader settings. - . - + . + ]]> - or is . + or is . @@ -481,11 +481,11 @@ The specific reader settings. Initializes a new instance of the class, based on a stream, with a supplied XAML schema context and XAML-specific settings. - . - + . + ]]> @@ -521,18 +521,18 @@ The specific reader settings. Initializes a new instance of the class, based on a , and using a supplied schema context and XAML-specific settings. - . - + . + ]]> - is . - - -or- - + is . + + -or- + is . @@ -565,18 +565,18 @@ The specific reader settings. Initializes a new instance of the class, based on the file name of a file to load into a default XML reader, and using a supplied XAML schema context and XAML-specific reader settings. - . - + . + ]]> - is . - - -or- - + is . + + -or- + is . @@ -609,11 +609,11 @@ The specific XAML reader settings. Initializes a new instance of the class using the provided , schema context, and reader settings. - . - + . + ]]> @@ -649,11 +649,11 @@ if line information is available; otherwise, . - implementation. The result is partially based on the reader settings that were used to initialize this . - + implementation. The result is partially based on the reader settings that were used to initialize this . + ]]> @@ -684,11 +684,11 @@ if the position is at the conceptual end-of-file in the node stream; otherwise, . - after exiting the bounds of the subtree. For more information, see . - + after exiting the bounds of the subtree. For more information, see . + ]]> @@ -721,11 +721,11 @@ Gets the line number to report. The line number to report. - implementation. Node types of , , , or can return a line number. Other node types return a value of 0. All node types return 0 if is `false`. - + implementation. Node types of , , , or can return a line number. Other node types return a value of 0. All node types return 0 if is `false`. + ]]> @@ -758,11 +758,11 @@ Gets the line position to report. The line position to report. - implementation. Node types of , , , or can return a line position. Other node types return a value of 0. All node types return 0 if is `false`. - + implementation. Node types of , , , or can return a line position. Other node types return a value of 0. All node types return 0 if is `false`. + ]]> @@ -820,11 +820,11 @@ Gets the XAML namespace from the current node. The XAML namespace from the current node, if it is available; otherwise, . - of the current position is . This property does not report the XAML namespace that applies to objects or members in a general scoping sense. Your implementation should cache XAML namespace information if you need it for specific operations. For default operations that involve the loaded XAML schema context, the acting XAML namespace is internally cached by XAML writer implementations. - + of the current position is . This property does not report the XAML namespace that applies to objects or members in a general scoping sense. Your implementation should cache XAML namespace information if you need it for specific operations. For default operations that involve the loaded XAML schema context, the acting XAML namespace is internally cached by XAML writer implementations. + ]]> @@ -883,15 +883,15 @@ if a node is available; otherwise, . - returns `false` also returns `true` for . - - Calling generally has the side effect of advancing the or . - - The next operation after calling and getting a `true` result is typically to check . For more information about XAML node stream concepts, see [Understanding XAML Node Stream Structures and Concepts](/dotnet/framework/xaml-services/understanding-xaml-node-stream-structures-and-concepts). - + returns `false` also returns `true` for . + + Calling generally has the side effect of advancing the or . + + The next operation after calling and getting a `true` result is typically to check . For more information about XAML node stream concepts, see [Understanding XAML Node Stream Structures and Concepts](/dotnet/framework/xaml-services/understanding-xaml-node-stream-structures-and-concepts). + ]]> @@ -923,11 +923,11 @@ Gets an object that provides schema information for the information set. An object that provides schema information for the information set. - of the reader is generally used by any associated writer. - + of the reader is generally used by any associated writer. + ]]> @@ -957,11 +957,11 @@ Gets the of the current node. The of the current node; or , if the position is not on an object. - of the current position is . - + of the current position is . + ]]> Understanding XAML Node Streams diff --git a/xml/System.Xml.Linq/XAttribute.xml b/xml/System.Xml.Linq/XAttribute.xml index 2db4848d75c..c407262531e 100644 --- a/xml/System.Xml.Linq/XAttribute.xml +++ b/xml/System.Xml.Linq/XAttribute.xml @@ -64,21 +64,21 @@ Represents an XML attribute. - contains a list of the attributes for that element. Attributes must have a qualified name that is unique to the element. Attributes are not derived from ; they are not nodes in the XML tree. Instead, they are simply name/value pairs associated with an element. - - Attributes are maintained in the XML tree in the order that they were added to the element. When a collection of attributes is returned by , they are returned in the order that they were added to the element, and are not sorted. - - Technically, in XML, namespace declarations are not attributes proper. However, this distinction is not normally made by many XML programmers. Instead, because namespace declarations have exactly the same XML syntax as attributes, most XML programmers think of namespaces as attributes. To simplify the LINQ to XML programming interface, namespaces are represented in the XML tree as attributes. Such namespace attributes impact serialization of an XML tree. When serializing, LINQ to XML attempts to serialize with the namespace prefix specified in namespace attributes. You can use the to determine if an attribute is really a namespace declaration. - - The class derives from . You can add annotations to attributes, and observe events for them. - - Some methods can be used from XAML. For more information, see [LINQ to XML Dynamic Properties](/dotnet/desktop/wpf/data/linq-to-xml-dynamic-properties). - + contains a list of the attributes for that element. Attributes must have a qualified name that is unique to the element. Attributes are not derived from ; they are not nodes in the XML tree. Instead, they are simply name/value pairs associated with an element. + + Attributes are maintained in the XML tree in the order that they were added to the element. When a collection of attributes is returned by , they are returned in the order that they were added to the element, and are not sorted. + + Technically, in XML, namespace declarations are not attributes proper. However, this distinction is not normally made by many XML programmers. Instead, because namespace declarations have exactly the same XML syntax as attributes, most XML programmers think of namespaces as attributes. To simplify the LINQ to XML programming interface, namespaces are represented in the XML tree as attributes. Such namespace attributes impact serialization of an XML tree. When serializing, LINQ to XML attempts to serialize with the namespace prefix specified in namespace attributes. You can use the to determine if an attribute is really a namespace declaration. + + The class derives from . You can add annotations to attributes, and observe events for them. + + Some methods can be used from XAML. For more information, see [LINQ to XML Dynamic Properties](/dotnet/desktop/wpf/data/linq-to-xml-dynamic-properties). + ]]> @@ -144,44 +144,44 @@ An object to copy from. Initializes a new instance of the class from another object. - "); -// Make a deep copy. -XElement root2 = new XElement(root1); -if (root1.Attribute("Att1") == root2.Attribute("Att1")) - Console.WriteLine("This will not be printed"); -else - Console.WriteLine("Creating a deep copy created a new attribute from the original."); -``` - -```vb -Dim root1 As XElement = -' Make a deep copy. -Dim root2 As XElement = New XElement(root1) -If root1.Attribute("Att1") Is root2.Attribute("Att1") Then - Console.WriteLine("This will not be printed") -Else - Console.WriteLine("Creating a deep copy created a new attribute from the original.") -End If -``` - - This example produces the following output: - -``` - -Creating a deep copy created a new attribute from the original. -``` - + "); +// Make a deep copy. +XElement root2 = new XElement(root1); +if (root1.Attribute("Att1") == root2.Attribute("Att1")) + Console.WriteLine("This will not be printed"); +else + Console.WriteLine("Creating a deep copy created a new attribute from the original."); +``` + +```vb +Dim root1 As XElement = +' Make a deep copy. +Dim root2 As XElement = New XElement(root1) +If root1.Attribute("Att1") Is root2.Attribute("Att1") Then + Console.WriteLine("This will not be printed") +Else + Console.WriteLine("Creating a deep copy created a new attribute from the original.") +End If +``` + + This example produces the following output: + +``` + +Creating a deep copy created a new attribute from the original. +``` + ]]> The parameter is . @@ -234,88 +234,88 @@ Creating a deep copy created a new attribute from the original. An containing the value of the attribute. Initializes a new instance of the class from the specified name and value. - . Typical use of this constructor is to specify a string as the first parameter instead of creating a new , as follows: - -```csharp -XElement root = new XElement("Root", - new XAttribute("AnAttributeName", "Content") -); -``` - - You can also use the addition operator overload with an and a string to create an , as follows: - -```csharp -XNamespace aw = "http://www.adventure-works.com"; -XElement root = new XElement(aw + "Root", - new XAttribute(aw + "AnAttributeName", "Content") -); -``` - - For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). - - These same approaches will work for Visual Basic, however XML literals provide a better approach for creating XML trees. - - The `value` parameter can be a , `double`, `float`, `decimal`, `bool`, , or . If the value is a or , the value of the attribute is formatted correctly per the W3C specifications. - - - -## Examples - The following example uses this constructor to create attributes. It passes strings as the first argument to the constructor, which are then implicitly converted to objects. The attributes are added to an element. - -```csharp -XElement root; - -double dbl = 12.345; -XAttribute[] attArray = { - new XAttribute("Att4", 1), - new XAttribute("Att5", 2), - new XAttribute("Att6", 3) -}; -DateTime dt = new DateTime(2006, 10, 6, 12, 30, 00); - -// string content -root = new XElement("Root", - new XAttribute("Att1", "Some text"), - - // double content - new XAttribute("Att2", dbl), - - // DateTime content - new XAttribute("Att3", dt), - - // XAttribute array content - attArray -); - -Console.WriteLine(root); -``` - -```vb -Dim dbl As Double = 12.345 -Dim attArray As XAttribute() = { _ - New XAttribute("Att4", 1), _ - New XAttribute("Att5", 2), _ - New XAttribute("Att6", 3) _ -} -Dim dt As DateTime = New DateTime(2006, 10, 6, 12, 30, 0) -Dim root As XElement = - Att3=<%= dt %> - <%= attArray %> - /> -Console.WriteLine(root) -``` - - This example produces the following output: - -``` - - -``` - + . Typical use of this constructor is to specify a string as the first parameter instead of creating a new , as follows: + +```csharp +XElement root = new XElement("Root", + new XAttribute("AnAttributeName", "Content") +); +``` + + You can also use the addition operator overload with an and a string to create an , as follows: + +```csharp +XNamespace aw = "http://www.adventure-works.com"; +XElement root = new XElement(aw + "Root", + new XAttribute(aw + "AnAttributeName", "Content") +); +``` + + For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). + + These same approaches will work for Visual Basic, however XML literals provide a better approach for creating XML trees. + + The `value` parameter can be a , `double`, `float`, `decimal`, `bool`, , or . If the value is a or , the value of the attribute is formatted correctly per the W3C specifications. + + + +## Examples + The following example uses this constructor to create attributes. It passes strings as the first argument to the constructor, which are then implicitly converted to objects. The attributes are added to an element. + +```csharp +XElement root; + +double dbl = 12.345; +XAttribute[] attArray = { + new XAttribute("Att4", 1), + new XAttribute("Att5", 2), + new XAttribute("Att6", 3) +}; +DateTime dt = new DateTime(2006, 10, 6, 12, 30, 00); + +// string content +root = new XElement("Root", + new XAttribute("Att1", "Some text"), + + // double content + new XAttribute("Att2", dbl), + + // DateTime content + new XAttribute("Att3", dt), + + // XAttribute array content + attArray +); + +Console.WriteLine(root); +``` + +```vb +Dim dbl As Double = 12.345 +Dim attArray As XAttribute() = { _ + New XAttribute("Att4", 1), _ + New XAttribute("Att5", 2), _ + New XAttribute("Att6", 3) _ +} +Dim dt As DateTime = New DateTime(2006, 10, 6, 12, 30, 0) +Dim root As XElement = + Att3=<%= dt %> + <%= attArray %> + /> +Console.WriteLine(root) +``` + + This example produces the following output: + +``` + + +``` + ]]> The or parameter is . @@ -366,11 +366,11 @@ Console.WriteLine(root) Gets an empty collection of attributes. An of containing an empty collection. - objects. - + objects. + ]]> @@ -419,51 +419,51 @@ Console.WriteLine(root) if this attribute is a namespace declaration; otherwise . - - -For Each att As XAttribute In root.Attributes() - If (att.IsNamespaceDeclaration) Then - Console.WriteLine("{0} is a namespace declaration", att.Name) - Else - Console.WriteLine("{0} is not a namespace declaration", att.Name) - End If -Next -``` - - This example produces the following output: - -``` -{http://www.w3.org/2000/xmlns/}aw is a namespace declaration -{http://www.adventure-works.com}Att is not a namespace declaration -``` - + + +For Each att As XAttribute In root.Attributes() + If (att.IsNamespaceDeclaration) Then + Console.WriteLine("{0} is a namespace declaration", att.Name) + Else + Console.WriteLine("{0} is not a namespace declaration", att.Name) + End If +Next +``` + + This example produces the following output: + +``` +{http://www.w3.org/2000/xmlns/}aw is a namespace declaration +{http://www.adventure-works.com}Att is not a namespace declaration +``` + ]]> @@ -516,71 +516,71 @@ Next Gets the expanded name of this attribute. An containing the name of this attribute. - - -For Each att As XAttribute In root.Attributes() - Console.WriteLine("{0}={1}", att.Name, att.Value) -Next -Console.WriteLine("") - -Dim NewRoot As XElement = _ ->_ - - -For Each att As XAttribute In NewRoot.Attributes() - Console.WriteLine("{0}={1}", att.Name, att.Value) -Next - -``` - - This example produces the following output: - -``` -{http://www.w3.org/2000/xmlns/}aw=http://www.adventure-works.com -{http://www.adventure-works.com}Att=content -Att2=different content - -Att2=new content -``` - + + +For Each att As XAttribute In root.Attributes() + Console.WriteLine("{0}={1}", att.Name, att.Value) +Next +Console.WriteLine("") + +Dim NewRoot As XElement = _ +>_ + + +For Each att As XAttribute In NewRoot.Attributes() + Console.WriteLine("{0}={1}", att.Name, att.Value) +Next + +``` + + This example produces the following output: + +``` +{http://www.w3.org/2000/xmlns/}aw=http://www.adventure-works.com +{http://www.adventure-works.com}Att=content +Att2=different content + +Att2=new content +``` + ]]> @@ -636,52 +636,52 @@ Att2=new content Gets the next attribute of the parent element. An containing the next attribute of the parent element. - , they are returned in the order that they were added, and are not sorted. When you request the next attribute through this property, this property returns the attribute that was added after this attribute. - - If this attribute does not have a parent, or if there is no next attribute, then this property returns `null`. - - - -## Examples - The following example shows how to iterate through the attributes of an element using this property. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att1", 1), - new XAttribute("Att2", 2), - new XAttribute("Att3", 3), - new XAttribute("Att4", 4) -); - -XAttribute att = root.FirstAttribute; -do { - Console.WriteLine(att); -} -while((att = att.NextAttribute) != null); -``` - -```vb -Dim root As XElement = -Dim att As XAttribute = root.FirstAttribute -Dim val As Boolean = True -Do - Console.WriteLine(att) - att = att.NextAttribute -Loop While (Not (att Is Nothing)) -``` - - This example produces the following output: - -``` -Att1="1" -Att2="2" -Att3="3" -Att4="4" -``` - + , they are returned in the order that they were added, and are not sorted. When you request the next attribute through this property, this property returns the attribute that was added after this attribute. + + If this attribute does not have a parent, or if there is no next attribute, then this property returns `null`. + + + +## Examples + The following example shows how to iterate through the attributes of an element using this property. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att1", 1), + new XAttribute("Att2", 2), + new XAttribute("Att3", 3), + new XAttribute("Att4", 4) +); + +XAttribute att = root.FirstAttribute; +do { + Console.WriteLine(att); +} +while((att = att.NextAttribute) != null); +``` + +```vb +Dim root As XElement = +Dim att As XAttribute = root.FirstAttribute +Dim val As Boolean = True +Do + Console.WriteLine(att) + att = att.NextAttribute +Loop While (Not (att Is Nothing)) +``` + + This example produces the following output: + +``` +Att1="1" +Att2="2" +Att3="3" +Att4="4" +``` + ]]> @@ -728,38 +728,38 @@ Att4="4" Gets the node type for this node. The node type. For objects, this value is . - contain a property, you can write code that operates on collections of concrete subclass of . Your code can then test for the node type of each node in the collection. - - - -## Examples - The following example creates an attribute, and then displays the node type using this property. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", "content") -); - -XAttribute att = root.FirstAttribute; -Console.WriteLine(att.NodeType); -``` - -```vb -Dim root As XElement = -Dim att As XAttribute = root.FirstAttribute -Console.WriteLine(att.NodeType.ToString) -``` - - This example produces the following output: - -``` - -Attribute -``` - + contain a property, you can write code that operates on collections of concrete subclass of . Your code can then test for the node type of each node in the collection. + + + +## Examples + The following example creates an attribute, and then displays the node type using this property. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", "content") +); + +XAttribute att = root.FirstAttribute; +Console.WriteLine(att.NodeType); +``` + +```vb +Dim root As XElement = +Dim att As XAttribute = root.FirstAttribute +Console.WriteLine(att.NodeType.ToString) +``` + + This example produces the following output: + +``` + +Attribute +``` + ]]> @@ -817,34 +817,34 @@ Attribute Cast the value of this to a . A that contains the content of this . - from an attribute or element, allowed values are "0", "1", and any string that produces "true" or "false" after trimming and conversion to lower case. - -## Examples - The following example creates an attribute with a value, then casts it to . - -```csharp -XElement root = new XElement("Root", - new XAttribute("BoolValue", true) -); -bool bv = (bool)root.Attribute("BoolValue"); -Console.WriteLine("(bool)BoolValue={0}", bv); -``` - -```vb -Dim root As XElement = -Dim bv As Boolean = CBool(root.Attribute("BoolValue")) -Console.WriteLine("(bool)BoolValue={0}", bv) -``` - - This example produces the following output: - -``` -(bool)BoolValue=True -``` - + from an attribute or element, allowed values are "0", "1", and any string that produces "true" or "false" after trimming and conversion to lower case. + +## Examples + The following example creates an attribute with a value, then casts it to . + +```csharp +XElement root = new XElement("Root", + new XAttribute("BoolValue", true) +); +bool bv = (bool)root.Attribute("BoolValue"); +Console.WriteLine("(bool)BoolValue={0}", bv); +``` + +```vb +Dim root As XElement = +Dim bv As Boolean = CBool(root.Attribute("BoolValue")) +Console.WriteLine("(bool)BoolValue={0}", bv) +``` + + This example produces the following output: + +``` +(bool)BoolValue=True +``` + ]]> The attribute does not contain a valid value. @@ -903,71 +903,71 @@ Console.WriteLine("(bool)BoolValue={0}", bv) Cast the value of this to a . A that contains the content of this . - from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a . - - This conversion operator uses to convert from a . - -## Examples - The following example creates an attribute with date and time content. It then casts it to to retrieve the value. - -```csharp -// Behavior is strict when formatting an XML element or attribute from a DateTime, -// but behavior is lax when casting to a DateTime from an element or attribute. - -XElement root = new XElement("Root", - new XAttribute("Att", new DateTime(2006, 10, 6, 12, 30, 0)) -); -Console.WriteLine(root); - -// casting from a strictly formatted XML attribute -DateTime dt = (DateTime)root.Attribute("Att"); -Console.WriteLine("dt={0}", dt); -Console.WriteLine("-----"); - -// if root is formatted in some different way than the standard ISO 8601, if at all possible, -// the value is appropriately converted to DateTime - -XAttribute dtAtt = new XAttribute("OrderDate", "October 6, 2006"); -Console.WriteLine(dtAtt); -DateTime orderDate = (DateTime)dtAtt; -Console.WriteLine("OrderDate={0:d}", orderDate); -``` - -```vb -' Behavior is strict when formatting an XML element or attribute from a DateTime, -' but behavior is lax when casting to a DateTime from an element or attribute. -Dim root As XElement = /> - -Console.WriteLine(root) - -' casting from a strictly formatted XML attribute -Dim dt As DateTime = CType(root.Attribute("Att"), DateTime) -Console.WriteLine("dt={0}", dt) -Console.WriteLine("-----") - -' if root is formatted in some different way than the standard ISO 8601, if at all possible, -' the value is appropriately converted to DateTime -Dim dtAtt As XAttribute = New XAttribute("OrderDate", "October 6, 2006") -Console.WriteLine(dtAtt) -Dim orderDate As DateTime = CType(dtAtt, DateTime) -Console.WriteLine("OrderDate={0:d}", orderDate) -``` - - This example produces the following output: - -``` - -dt=10/6/2006 12:30:00 PM ------ -OrderDate="October 6, 2006" -OrderDate=10/6/2006 -``` - + from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a . + + This conversion operator uses to convert from a . + +## Examples + The following example creates an attribute with date and time content. It then casts it to to retrieve the value. + +```csharp +// Behavior is strict when formatting an XML element or attribute from a DateTime, +// but behavior is lax when casting to a DateTime from an element or attribute. + +XElement root = new XElement("Root", + new XAttribute("Att", new DateTime(2006, 10, 6, 12, 30, 0)) +); +Console.WriteLine(root); + +// casting from a strictly formatted XML attribute +DateTime dt = (DateTime)root.Attribute("Att"); +Console.WriteLine("dt={0}", dt); +Console.WriteLine("-----"); + +// if root is formatted in some different way than the standard ISO 8601, if at all possible, +// the value is appropriately converted to DateTime + +XAttribute dtAtt = new XAttribute("OrderDate", "October 6, 2006"); +Console.WriteLine(dtAtt); +DateTime orderDate = (DateTime)dtAtt; +Console.WriteLine("OrderDate={0:d}", orderDate); +``` + +```vb +' Behavior is strict when formatting an XML element or attribute from a DateTime, +' but behavior is lax when casting to a DateTime from an element or attribute. +Dim root As XElement = /> + +Console.WriteLine(root) + +' casting from a strictly formatted XML attribute +Dim dt As DateTime = CType(root.Attribute("Att"), DateTime) +Console.WriteLine("dt={0}", dt) +Console.WriteLine("-----") + +' if root is formatted in some different way than the standard ISO 8601, if at all possible, +' the value is appropriately converted to DateTime +Dim dtAtt As XAttribute = New XAttribute("OrderDate", "October 6, 2006") +Console.WriteLine(dtAtt) +Dim orderDate As DateTime = CType(dtAtt, DateTime) +Console.WriteLine("OrderDate={0:d}", orderDate) +``` + + This example produces the following output: + +``` + +dt=10/6/2006 12:30:00 PM +----- +OrderDate="October 6, 2006" +OrderDate=10/6/2006 +``` + ]]> The attribute does not contain a valid value. @@ -1026,43 +1026,43 @@ OrderDate=10/6/2006 Cast the value of this to a . A that contains the content of this . - class to do the conversion. - -## Examples - The following example creates an attribute with date and time content. It then casts it to to retrieve the value. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", new DateTimeOffset(new DateTime(2006, 10, 6, 12, 30, 0))) -); -Console.WriteLine(root); - -// casting from a strictly formatted XML attribute -DateTimeOffset dt = (DateTimeOffset)root.Attribute("Att"); -Console.WriteLine("dt={0}", dt); -``` - -```vb -Dim root As XElement = _ - /> -Console.WriteLine(root) - -' casting from a strictly formatted XML attribute -Dim dt As DateTimeOffset = CType(root.Attribute("Att"), DateTimeOffset) -Console.WriteLine("dt={0}", dt) -``` - - This example produces the following output: - -``` - -dt=10/6/2006 12:30:00 PM -07:00 -``` - + class to do the conversion. + +## Examples + The following example creates an attribute with date and time content. It then casts it to to retrieve the value. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", new DateTimeOffset(new DateTime(2006, 10, 6, 12, 30, 0))) +); +Console.WriteLine(root); + +// casting from a strictly formatted XML attribute +DateTimeOffset dt = (DateTimeOffset)root.Attribute("Att"); +Console.WriteLine("dt={0}", dt); +``` + +```vb +Dim root As XElement = _ + /> +Console.WriteLine(root) + +' casting from a strictly formatted XML attribute +Dim dt As DateTimeOffset = CType(root.Attribute("Att"), DateTimeOffset) +Console.WriteLine("dt={0}", dt) +``` + + This example produces the following output: + +``` + +dt=10/6/2006 12:30:00 PM -07:00 +``` + ]]> The attribute does not contain a valid value. @@ -1121,29 +1121,29 @@ dt=10/6/2006 12:30:00 PM -07:00 Cast the value of this to a . A that contains the content of this . - . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", "79228162514264337593543950335") -); -decimal value = (decimal)root.Attribute("Att"); -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = -Dim value As Decimal = CDec(root.Attribute("Att")) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=79228162514264337593543950335 -``` - + . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", "79228162514264337593543950335") +); +decimal value = (decimal)root.Attribute("Att"); +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = +Dim value As Decimal = CDec(root.Attribute("Att")) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=79228162514264337593543950335 +``` + ]]> The attribute does not contain a valid value. @@ -1202,29 +1202,29 @@ value=79228162514264337593543950335 Cast the value of this to a . A that contains the content of this . - content. It then retrieves the value by casting to . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 1.79769313486231e308) -); -double value = (double)root.Attribute("Att"); -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = -Dim value As Double = CDbl(root.Attribute("Att")) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=1.79769313486231E+308 -``` - + content. It then retrieves the value by casting to . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 1.79769313486231e308) +); +double value = (double)root.Attribute("Att"); +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = +Dim value As Double = CDbl(root.Attribute("Att")) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=1.79769313486231E+308 +``` + ]]> The attribute does not contain a valid value. @@ -1283,29 +1283,29 @@ value=1.79769313486231E+308 Cast the value of this to a . A that contains the content of this . - . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", new Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730")) -); -Guid value = (Guid)root.Attribute("Att"); -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = /> -Dim value As Guid = CType(root.Attribute("Att"), Guid) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 -``` - + . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", new Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730")) +); +Guid value = (Guid)root.Attribute("Att"); +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = /> +Dim value As Guid = CType(root.Attribute("Att"), Guid) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 +``` + ]]> The attribute does not contain a valid value. @@ -1364,29 +1364,29 @@ value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 Cast the value of this to an . A that contains the content of this . - . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 2147483647) -); -int value = (int)root.Attribute("Att"); -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = -Dim value As Integer = CInt(root.Attribute("Att")) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=2147483647 -``` - + . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 2147483647) +); +int value = (int)root.Attribute("Att"); +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = +Dim value As Integer = CInt(root.Attribute("Att")) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=2147483647 +``` + ]]> The attribute does not contain a valid value. @@ -1445,29 +1445,29 @@ value=2147483647 Cast the value of this to an . A that contains the content of this . - . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 9223372036854775807) -); -long value = (long)root.Attribute("Att"); -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = -Dim value As Long = CLng(root.Attribute("Att")) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=9223372036854775807 -``` - + . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 9223372036854775807) +); +long value = (long)root.Attribute("Att"); +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = +Dim value As Long = CLng(root.Attribute("Att")) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=9223372036854775807 +``` + ]]> The attribute does not contain a valid value. @@ -1527,40 +1527,40 @@ value=9223372036854775807 Cast the value of this to a of . A of that contains the content of this . - from an attribute or element, allowed values are "0", "1", and any string that produces "true" or "false" after trimming and conversion to lower case. - -## Examples - The following example creates an attribute with Boolean content. It then retrieves the value by casting to of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("BoolValue1", true), - new XAttribute("BoolValue2", false) -); -bool? bool1 = (bool?)root.Attribute("BoolValue1"); -bool? bool2 = (bool?)root.Attribute("BoolValue2"); -Console.WriteLine("Nullable boolean: BoolValue1={0}", bool1); -Console.WriteLine("Nullable boolean: BoolValue2={0}", bool2); -``` - -```vb -Dim root As XElement = -Dim bool1 As Nullable(Of Boolean) = CType(root.Attribute("BoolValue1"), Nullable(Of Boolean)) -Dim bool2 As Nullable(Of Boolean) = CType(root.Attribute("BoolValue2"), Nullable(Of Boolean)) -Console.WriteLine("Nullable boolean: BoolValue1={0}", bool1) -Console.WriteLine("Nullable boolean: BoolValue2={0}", bool2) -``` - - This example produces the following output: - -``` -Nullable boolean: BoolValue1=True -Nullable boolean: BoolValue2=False -``` - + from an attribute or element, allowed values are "0", "1", and any string that produces "true" or "false" after trimming and conversion to lower case. + +## Examples + The following example creates an attribute with Boolean content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("BoolValue1", true), + new XAttribute("BoolValue2", false) +); +bool? bool1 = (bool?)root.Attribute("BoolValue1"); +bool? bool2 = (bool?)root.Attribute("BoolValue2"); +Console.WriteLine("Nullable boolean: BoolValue1={0}", bool1); +Console.WriteLine("Nullable boolean: BoolValue2={0}", bool2); +``` + +```vb +Dim root As XElement = +Dim bool1 As Nullable(Of Boolean) = CType(root.Attribute("BoolValue1"), Nullable(Of Boolean)) +Dim bool2 As Nullable(Of Boolean) = CType(root.Attribute("BoolValue2"), Nullable(Of Boolean)) +Console.WriteLine("Nullable boolean: BoolValue1={0}", bool1) +Console.WriteLine("Nullable boolean: BoolValue2={0}", bool2) +``` + + This example produces the following output: + +``` +Nullable boolean: BoolValue1=True +Nullable boolean: BoolValue2=False +``` + ]]> The attribute does not contain a valid value. @@ -1619,38 +1619,38 @@ Nullable boolean: BoolValue2=False Cast the value of this to a of . A of that contains the content of this . - of from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a of . - - This conversion operator uses to convert from a . - -## Examples - The following example creates an attribute with a date and time as content. It then retrieves the value by casting to of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", new DateTime(2006, 10, 6, 12, 30, 0)) -); -DateTime? value = (DateTime?)root.Attribute("Att"); -Console.WriteLine("Nullable DateTime: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = /> -Dim value As Nullable(Of DateTime) = CType(root.Attribute("Att"), Nullable(Of DateTime)) -Console.WriteLine("Nullable DateTime: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable DateTime: value=10/6/2006 12:30:00 PM -``` - + of from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a of . + + This conversion operator uses to convert from a . + +## Examples + The following example creates an attribute with a date and time as content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", new DateTime(2006, 10, 6, 12, 30, 0)) +); +DateTime? value = (DateTime?)root.Attribute("Att"); +Console.WriteLine("Nullable DateTime: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = /> +Dim value As Nullable(Of DateTime) = CType(root.Attribute("Att"), Nullable(Of DateTime)) +Console.WriteLine("Nullable DateTime: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable DateTime: value=10/6/2006 12:30:00 PM +``` + ]]> The attribute does not contain a valid value. @@ -1709,36 +1709,36 @@ Nullable DateTime: value=10/6/2006 12:30:00 PM Cast the value of this to a of . A of that contains the content of this . - class to do the conversion. - -## Examples - The following example creates an attribute with a date and time as content. It then retrieves the value by casting to of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", new DateTimeOffset(new DateTime(2006, 10, 6, 12, 30, 0))) -); -DateTimeOffset? value = (DateTimeOffset?)root.Attribute("Att"); -Console.WriteLine("Nullable DateTimeOffset: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = _ - /> -Dim value As Nullable(Of DateTimeOffset) = CType(root.Attribute("Att"), Nullable(Of DateTimeOffset)) -Console.WriteLine("Nullable DateTimeOffset: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable DateTimeOffset: value=10/6/2006 12:30:00 PM -07:00 -``` - + class to do the conversion. + +## Examples + The following example creates an attribute with a date and time as content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", new DateTimeOffset(new DateTime(2006, 10, 6, 12, 30, 0))) +); +DateTimeOffset? value = (DateTimeOffset?)root.Attribute("Att"); +Console.WriteLine("Nullable DateTimeOffset: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = _ + /> +Dim value As Nullable(Of DateTimeOffset) = CType(root.Attribute("Att"), Nullable(Of DateTimeOffset)) +Console.WriteLine("Nullable DateTimeOffset: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable DateTimeOffset: value=10/6/2006 12:30:00 PM -07:00 +``` + ]]> The attribute does not contain a valid value. @@ -1795,29 +1795,29 @@ Nullable DateTimeOffset: value=10/6/2006 12:30:00 PM -07:00 Cast the value of this to a of . A of that contains the content of this . - of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", "79228162514264337593543950335") -); -decimal? value = (decimal?)root.Attribute("Att"); -Console.WriteLine("Nullable decimal: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = -Dim value As Nullable(Of Decimal) = CType(root.Attribute("Att"), Nullable(Of Decimal)) -Console.WriteLine("Nullable decimal: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable decimal: value=79228162514264337593543950335 -``` - + of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", "79228162514264337593543950335") +); +decimal? value = (decimal?)root.Attribute("Att"); +Console.WriteLine("Nullable decimal: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = +Dim value As Nullable(Of Decimal) = CType(root.Attribute("Att"), Nullable(Of Decimal)) +Console.WriteLine("Nullable decimal: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable decimal: value=79228162514264337593543950335 +``` + ]]> The attribute does not contain a valid value. @@ -1876,29 +1876,29 @@ Nullable decimal: value=79228162514264337593543950335 Cast the value of this to a of . A of that contains the content of this . - of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 1.79769313486231e308) -); -double? value = (double?)root.Attribute("Att"); -Console.WriteLine("Nullable double: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = -Dim value As Nullable(Of Double) = CType(root.Attribute("Att"), Nullable(Of Double)) -Console.WriteLine("Nullable double: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable double: value=1.79769313486231E+308 -``` - + of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 1.79769313486231e308) +); +double? value = (double?)root.Attribute("Att"); +Console.WriteLine("Nullable double: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = +Dim value As Nullable(Of Double) = CType(root.Attribute("Att"), Nullable(Of Double)) +Console.WriteLine("Nullable double: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable double: value=1.79769313486231E+308 +``` + ]]> The attribute does not contain a valid value. @@ -1957,29 +1957,29 @@ Nullable double: value=1.79769313486231E+308 Cast the value of this to a of . A of that contains the content of this . - of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", new Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730")) -); -Guid? value = (Guid?)root.Attribute("Att"); -Console.WriteLine("Nullable Guid: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = /> -Dim value As Nullable(Of Guid) = CType(root.Attribute("Att"), Nullable(Of Guid)) -Console.WriteLine("Nullable Guid: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable Guid: value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 -``` - + of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", new Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730")) +); +Guid? value = (Guid?)root.Attribute("Att"); +Console.WriteLine("Nullable Guid: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = /> +Dim value As Nullable(Of Guid) = CType(root.Attribute("Att"), Nullable(Of Guid)) +Console.WriteLine("Nullable Guid: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable Guid: value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 +``` + ]]> The attribute does not contain a valid value. @@ -2038,29 +2038,29 @@ Nullable Guid: value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 Cast the value of this to a of . A of that contains the content of this . - of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 2147483647) -); -int? value = (int?)root.Attribute("Att"); -Console.WriteLine("Nullable int: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = -Dim value As Nullable(Of Integer) = CType(root.Attribute("Att"), Nullable(Of Integer)) -Console.WriteLine("Nullable int: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable int: value=2147483647 -``` - + of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 2147483647) +); +int? value = (int?)root.Attribute("Att"); +Console.WriteLine("Nullable int: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = +Dim value As Nullable(Of Integer) = CType(root.Attribute("Att"), Nullable(Of Integer)) +Console.WriteLine("Nullable int: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable int: value=2147483647 +``` + ]]> @@ -2118,29 +2118,29 @@ Nullable int: value=2147483647 Cast the value of this to a of . A of that contains the content of this . - of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 9223372036854775807) -); -long? value = (long?)root.Attribute("Att"); -Console.WriteLine("Nullable long: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = -Dim value As Nullable(Of Long) = CType(root.Attribute("Att"), Nullable(Of Long)) -Console.WriteLine("Nullable long: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable long: value=9223372036854775807 -``` - + of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 9223372036854775807) +); +long? value = (long?)root.Attribute("Att"); +Console.WriteLine("Nullable long: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = +Dim value As Nullable(Of Long) = CType(root.Attribute("Att"), Nullable(Of Long)) +Console.WriteLine("Nullable long: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable long: value=9223372036854775807 +``` + ]]> The attribute does not contain a valid value. @@ -2199,29 +2199,29 @@ Nullable long: value=9223372036854775807 Cast the value of this to a of . A of that contains the content of this . - of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 3.402823e38) -); -float? value = (float?)root.Attribute("Att"); -Console.WriteLine("Nullable Single: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = -Dim value As Nullable(Of Single) = CType(root.Attribute("Att"), Nullable(Of Single)) -Console.WriteLine("Nullable Single: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable Single: value=3.402823E+38 -``` - + of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 3.402823e38) +); +float? value = (float?)root.Attribute("Att"); +Console.WriteLine("Nullable Single: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = +Dim value As Nullable(Of Single) = CType(root.Attribute("Att"), Nullable(Of Single)) +Console.WriteLine("Nullable Single: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable Single: value=3.402823E+38 +``` + ]]> The attribute does not contain a valid value. @@ -2280,36 +2280,36 @@ Nullable Single: value=3.402823E+38 Cast the value of this to a of . A of that contains the content of this . - of from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a of . - -## Examples - The following example creates an attribute with time span content. It then retrieves the value by casting to of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", new TimeSpan(1, 5, 30)) -); -TimeSpan? value = (TimeSpan?)root.Attribute("Att"); -Console.WriteLine("Nullable TimeSpan: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = /> -Dim value As Nullable(Of TimeSpan) = CType(root.Attribute("Att"), Nullable(Of TimeSpan)) -Console.WriteLine("Nullable TimeSpan: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable TimeSpan: value=01:05:30 -``` - + of from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a of . + +## Examples + The following example creates an attribute with time span content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", new TimeSpan(1, 5, 30)) +); +TimeSpan? value = (TimeSpan?)root.Attribute("Att"); +Console.WriteLine("Nullable TimeSpan: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = /> +Dim value As Nullable(Of TimeSpan) = CType(root.Attribute("Att"), Nullable(Of TimeSpan)) +Console.WriteLine("Nullable TimeSpan: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable TimeSpan: value=01:05:30 +``` + ]]> The attribute does not contain a valid value. @@ -2368,29 +2368,29 @@ Nullable TimeSpan: value=01:05:30 Cast the value of this to a of . A of that contains the content of this . - of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 4294967295) -); -uint? value = (uint?)root.Attribute("Att"); -Console.WriteLine("Nullable uint: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = -Dim value As Nullable(Of UInteger) = CType(root.Attribute("Att"), Nullable(Of UInteger)) -Console.WriteLine("Nullable uint: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable uint: value=4294967295 -``` - + of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 4294967295) +); +uint? value = (uint?)root.Attribute("Att"); +Console.WriteLine("Nullable uint: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = +Dim value As Nullable(Of UInteger) = CType(root.Attribute("Att"), Nullable(Of UInteger)) +Console.WriteLine("Nullable uint: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable uint: value=4294967295 +``` + ]]> The attribute does not contain a valid value. @@ -2449,29 +2449,29 @@ Nullable uint: value=4294967295 Cast the value of this to a of . A of that contains the content of this . - of . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 9223372036854775807) -); -ulong? value = (ulong?)root.Attribute("Att"); -Console.WriteLine("Nullable ulong: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = -Dim value As Nullable(Of ULong) = CType(root.Attribute("Att"), Nullable(Of ULong)) -Console.WriteLine("Nullable ulong: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable ulong: value=9223372036854775807 -``` - + of . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 9223372036854775807) +); +ulong? value = (ulong?)root.Attribute("Att"); +Console.WriteLine("Nullable ulong: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = +Dim value As Nullable(Of ULong) = CType(root.Attribute("Att"), Nullable(Of ULong)) +Console.WriteLine("Nullable ulong: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable ulong: value=9223372036854775807 +``` + ]]> The attribute does not contain a valid value. @@ -2529,29 +2529,29 @@ Nullable ulong: value=9223372036854775807 Cast the value of this to a . A that contains the content of this . - . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 3.402823e38) -); -float value = (float)root.Attribute("Att"); -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = -Dim value As Single = CSng(root.Attribute("Att")) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=3.402823E+38 -``` - + . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 3.402823e38) +); +float value = (float)root.Attribute("Att"); +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = +Dim value As Single = CSng(root.Attribute("Att")) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=3.402823E+38 +``` + ]]> The attribute does not contain a valid value. @@ -2611,31 +2611,31 @@ value=3.402823E+38 Cast the value of this to a . A that contains the content of this . - . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", "attribute content") -); -XAttribute att = root.Attribute("Att"); -string str = (string)att; -Console.WriteLine("(string)att={0}", str); -``` - -```vb -Dim root As XElement = -Dim att As XAttribute = root.Attribute("Att") -Dim str As String = CStr(att) -Console.WriteLine("(string)att={0}", str) -``` - - This example produces the following output: - -``` -(string)att=attribute content -``` - + . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", "attribute content") +); +XAttribute att = root.Attribute("Att"); +string str = (string)att; +Console.WriteLine("(string)att={0}", str); +``` + +```vb +Dim root As XElement = +Dim att As XAttribute = root.Attribute("Att") +Dim str As String = CStr(att) +Console.WriteLine("(string)att={0}", str) +``` + + This example produces the following output: + +``` +(string)att=attribute content +``` + ]]> @@ -2692,36 +2692,36 @@ Console.WriteLine("(string)att={0}", str) Cast the value of this to a . A that contains the content of this . - from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a . - -## Examples - The following example creates an attribute with time span content. It then retrieves the value by casting to . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", new TimeSpan(1, 5, 30)) -); -TimeSpan value = (TimeSpan)root.Attribute("Att"); -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = /> -Dim value As TimeSpan = CType(root.Attribute("Att"), TimeSpan) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=01:05:30 -``` - + from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a . + +## Examples + The following example creates an attribute with time span content. It then retrieves the value by casting to . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", new TimeSpan(1, 5, 30)) +); +TimeSpan value = (TimeSpan)root.Attribute("Att"); +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = /> +Dim value As TimeSpan = CType(root.Attribute("Att"), TimeSpan) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=01:05:30 +``` + ]]> The attribute does not contain a valid value. @@ -2780,29 +2780,29 @@ value=01:05:30 Cast the value of this to a . A that contains the content of this . - . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 4294967295) -); -uint value = (uint)root.Attribute("Att"); -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = -Dim value As UInteger = CUInt(root.Attribute("Att")) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=4294967295 -``` - + . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 4294967295) +); +uint value = (uint)root.Attribute("Att"); +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = +Dim value As UInteger = CUInt(root.Attribute("Att")) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=4294967295 +``` + ]]> The attribute does not contain a valid value. @@ -2861,29 +2861,29 @@ value=4294967295 Cast the value of this to a . A that contains the content of this . - . - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", 1844674407370955161) -); -ulong value = (ulong)root.Attribute("Att"); -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = -Dim value As ULong = CULng(root.Attribute("Att")) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=1844674407370955161 -``` - + . + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", 1844674407370955161) +); +ulong value = (ulong)root.Attribute("Att"); +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = +Dim value As ULong = CULng(root.Attribute("Att")) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=1844674407370955161 +``` + ]]> The attribute does not contain a valid value. @@ -2939,53 +2939,53 @@ value=1844674407370955161 Gets the previous attribute of the parent element. An containing the previous attribute of the parent element. - , they are returned in the order that they were added, and are not sorted. When you request the previous attribute through this property, this property returns the attribute that was added before this attribute. - - If this attribute does not have a parent, or if this attribute is the first attribute, then this property returns `null`. - - The class stores its attributes as a singly-linked list of objects. This means that the property must traverse the list of attributes that belong to the element. Therefore, using this property might affect your performance. - - - -## Examples - The following example shows how to iterate through the attributes of an element using this property. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att1", 1), - new XAttribute("Att2", 2), - new XAttribute("Att3", 3), - new XAttribute("Att4", 4) -); -XAttribute att = root.LastAttribute; -do { - Console.WriteLine(att); -} -while((att = att.PreviousAttribute) != null); -``` - -```vb -Dim root As XElement = -Dim att As XAttribute = root.LastAttribute -Dim val As Boolean = True -Do - Console.WriteLine(att) - att = att.PreviousAttribute -Loop While (Not (att Is Nothing)) -``` - - This example produces the following output: - -``` -Att4="4" -Att3="3" -Att2="2" -Att1="1" -``` - + , they are returned in the order that they were added, and are not sorted. When you request the previous attribute through this property, this property returns the attribute that was added before this attribute. + + If this attribute does not have a parent, or if this attribute is the first attribute, then this property returns `null`. + + The class stores its attributes as a singly-linked list of objects. This means that the property must traverse the list of attributes that belong to the element. Therefore, using this property might affect your performance. + + + +## Examples + The following example shows how to iterate through the attributes of an element using this property. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att1", 1), + new XAttribute("Att2", 2), + new XAttribute("Att3", 3), + new XAttribute("Att4", 4) +); +XAttribute att = root.LastAttribute; +do { + Console.WriteLine(att); +} +while((att = att.PreviousAttribute) != null); +``` + +```vb +Dim root As XElement = +Dim att As XAttribute = root.LastAttribute +Dim val As Boolean = True +Do + Console.WriteLine(att) + att = att.PreviousAttribute +Loop While (Not (att Is Nothing)) +``` + + This example produces the following output: + +``` +Att4="4" +Att3="3" +Att2="2" +Att1="1" +``` + ]]> @@ -3032,44 +3032,44 @@ Att1="1" Removes this attribute from its parent element. - using the extension method. Then you can iterate over the list, removing the attributes. For more information, see [Mixed Declarative Code/Imperative Code Bugs (LINQ to XML)](/dotnet/standard/linq/mixed-declarative-imperative-code-bugs). - - Alternatively, if you want to remove a set of attributes, it is recommended that you use the method. This method copies the attributes to a list, then iterates over the list, removing the attributes. - - - -## Examples - The following example creates an element with three attributes. It then removes one of the attributes. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att1", "content1"), - new XAttribute("Att2", "content2"), - new XAttribute("Att3", "content3") -); -XAttribute att = root.Attribute("Att2"); -att.Remove(); -Console.WriteLine(root); -``` - -```vb -Dim root As XElement = -Dim att As XAttribute = root.Attribute("Att2") -att.Remove() -Console.WriteLine(root) -``` - - This example produces the following output: - -``` - -``` - + using the extension method. Then you can iterate over the list, removing the attributes. For more information, see [Mixed Declarative Code/Imperative Code Bugs (LINQ to XML)](/dotnet/standard/linq/mixed-declarative-imperative-code-bugs). + + Alternatively, if you want to remove a set of attributes, it is recommended that you use the method. This method copies the attributes to a list, then iterates over the list, removing the attributes. + + + +## Examples + The following example creates an element with three attributes. It then removes one of the attributes. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att1", "content1"), + new XAttribute("Att2", "content2"), + new XAttribute("Att3", "content3") +); +XAttribute att = root.Attribute("Att2"); +att.Remove(); +Console.WriteLine(root); +``` + +```vb +Dim root As XElement = +Dim att As XAttribute = root.Attribute("Att2") +att.Remove() +Console.WriteLine(root) +``` + + This example produces the following output: + +``` + +``` + ]]> The parent element is . @@ -3119,44 +3119,44 @@ Console.WriteLine(root) The value to assign to this attribute. Sets the value of this attribute. - property. - - It is invalid to pass an instance of a class that derives from , such as or . - - This method will raise the and the events. - - - -## Examples - The following example creates an element with several attributes. It then changes the contents of one of the attributes. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att1", "content1"), - new XAttribute("Att2", "content2"), - new XAttribute("Att3", "content3") -); -XAttribute att = root.Attribute("Att2"); -att.SetValue("new content"); -Console.WriteLine(root); -``` - -```vb -Dim root As XElement = -Dim att As XAttribute = root.Attribute("Att2") -att.SetValue("new content") -Console.WriteLine(root) -``` - - This example produces the following output: - -``` - -``` - + property. + + It is invalid to pass an instance of a class that derives from , such as or . + + This method will raise the and the events. + + + +## Examples + The following example creates an element with several attributes. It then changes the contents of one of the attributes. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att1", "content1"), + new XAttribute("Att2", "content2"), + new XAttribute("Att3", "content3") +); +XAttribute att = root.Attribute("Att2"); +att.SetValue("new content"); +Console.WriteLine(root); +``` + +```vb +Dim root As XElement = +Dim att As XAttribute = root.Attribute("Att2") +att.SetValue("new content") +Console.WriteLine(root) +``` + + This example produces the following output: + +``` + +``` + ]]> The parameter is . @@ -3209,41 +3209,41 @@ Console.WriteLine(root) Converts the current object to a string representation. A containing the XML text representation of an attribute and its value. - [!WARNING] -> When this method is called and contains control character, an exception is thrown with a message like: hexadecimal value 0x0B, is an invalid character. - - - -## Examples - The following example creates an element with several attributes. It then gets an attribute and displays it and its content by calling this method. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att1", "content1"), - new XAttribute("Att2", "content2"), - new XAttribute("Att3", "content3") -); -XAttribute att = root.Attribute("Att2"); -Console.WriteLine(att.ToString()); -``` - -```vb -Dim root As XElement = -Dim att As XAttribute = root.Attribute("Att2") -Console.WriteLine(att.ToString()) -``` - - This example produces the following output: - -``` -Att2="content2" -``` - +> When this method is called and contains control character, an exception is thrown with a message like: hexadecimal value 0x0B, is an invalid character. + + + +## Examples + The following example creates an element with several attributes. It then gets an attribute and displays it and its content by calling this method. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att1", "content1"), + new XAttribute("Att2", "content2"), + new XAttribute("Att3", "content3") +); +XAttribute att = root.Attribute("Att2"); +Console.WriteLine(att.ToString()); +``` + +```vb +Dim root As XElement = +Dim att As XAttribute = root.Attribute("Att2") +Console.WriteLine(att.ToString()) +``` + + This example produces the following output: + +``` +Att2="content2" +``` + ]]> @@ -3298,185 +3298,183 @@ Att2="content2" Gets or sets the value of this attribute. A containing the value of this attribute. - and the events. - - If you are getting the value and the attribute might not exist, it is more convenient to use the explicit conversion operators, and assign the attribute to a nullable type such as `string` or of . If the attribute does not exist, then the nullable type is set to `null`. Before using this property, you must make sure that the method does not return `null`. - - - -## Examples - The following example creates an element with an attribute. It then retrieves the value of the attribute, and then sets it. - - Note that the Visual Basic example uses the XML attribute property. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att", "content") -); -XAttribute att = root.FirstAttribute; -Console.WriteLine(att.Value); -att.Value = "new text"; -Console.WriteLine(att.Value); -``` - -```vb -Dim root As XElement = -Console.WriteLine(root.@Att) -root.@Att = "new text" -Console.WriteLine(root.@Att) -``` - - This example produces the following output: - -``` -content -new text -``` - - The following example shows the benefit of using the explicit conversion operators to get the value of an attribute that might not exist: - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att1", "attribute 1 content"), - new XAttribute("Att2", "2") -); - -// The following assignments demonstrate why it is easier to use -// casting when the attribute might or might not exist. - -string c1 = (string)root.Attribute("Att1"); -Console.WriteLine("c1:{0}", c1 == null ? "attribute does not exist" : c1); - -int? c2 = (int?)root.Attribute("Att2"); -Console.WriteLine("c2:{0}", c2 == null ? "attribute does not exist" : c2.ToString()); - -string c3 = (string)root.Attribute("Att3"); -Console.WriteLine("c3:{0}", c3 == null ? "attribute does not exist" : c3); - -int? c4 = (int?)root.Attribute("Att4"); -Console.WriteLine("c4:{0}", c4 == null ? "attribute does not exist" : c4.ToString()); - -Console.WriteLine(); - -// The following assignments show the necessary code when using -// the value property when the attribute might or might not exist. - -XAttribute att1 = root.Attribute("Att1"); -string v1; -if (att1 == null) - v1 = null; -else - v1 = att1.Value; -Console.WriteLine("v1:{0}", v1 == null ? "attribute does not exist" : v1); - -XAttribute att2 = root.Attribute("Att2"); -int? v2; -if (att2 == null) - v2 = null; -else - v2 = Int32.Parse(att2.Value); -Console.WriteLine("v2:{0}", v2 == null ? "attribute does not exist" : v2.ToString()); - -XAttribute att3 = root.Attribute("Att3"); -string v3; -if (att3 == null) - v3 = null; -else - v3 = att3.Value; -Console.WriteLine("v3:{0}", v3 == null ? "attribute does not exist" : v3); - -XAttribute att4 = root.Attribute("Att4"); -int? v4; -if (att4 == null) - v4 = null; -else - v4 = Int32.Parse(att4.Value); -Console.WriteLine("v4:{0}", v4 == null ? "attribute does not exist" : v4.ToString()); -``` - -```vb -Dim root As XElement = - -' The following assignments demonstrate why it is easier to use -' casting when the attribute might or might not exist. - -Dim c1 As String = CStr(root.Attribute("Att1")) -Console.WriteLine("c1:{0}", IIf(c1 Is Nothing, "attribute does not exist", c1)) - -Dim c2 As Nullable(Of Integer) = CType(root.Attribute("Att2"), Nullable(Of Integer)) -Console.WriteLine("c2:{0}", IIf(c2.HasValue, c2, "attribute does not exist")) - -Dim c3 As String = CStr(root.Attribute("Att3")) -Console.WriteLine("c3:{0}", IIf(c3 Is Nothing, "attribute does not exist", c3)) - -Dim c4 As Nullable(Of Integer) = CType(root.Attribute("Att4"), Nullable(Of Integer)) -Console.WriteLine("c4:{0}", IIf(c4.HasValue, c4, "attribute does not exist")) - -Console.WriteLine() - -' The following assignments show the necessary code when using -' the value property when the attribute might or might not exist. - -Dim att1 As XAttribute = root.Attribute("Att1") -Dim v1 As String -If att1 Is Nothing Then - v1 = Nothing -Else - v1 = att1.Value -End If - -Console.WriteLine("v1:{0}", IIf(v1 Is Nothing, "attribute does not exist", v1)) - -Dim att2 As XAttribute = root.Attribute("Att2") -Dim v2 As Nullable(Of Integer) -If att2 Is Nothing Then - v2 = Nothing -Else - v2 = Int32.Parse(att2.Value) -End If - -Console.WriteLine("v2:{0}", IIf(v2.HasValue, v2, "attribute does not exist")) - -Dim att3 As XAttribute = root.Attribute("Att3") -Dim v3 As String -If att3 Is Nothing Then - v3 = Nothing -Else - v3 = att3.Value -End If - -Console.WriteLine("v3:{0}", IIf(v3 Is Nothing, "attribute does not exist", v3)) - -Dim att4 As XAttribute = root.Attribute("Att4") -Dim v4 As Nullable(Of Integer) -If att4 Is Nothing Then - v4 = Nothing -Else - v4 = Int32.Parse(att4.Value) -End If - -Console.WriteLine("v4:{0}", IIf(v4.HasValue, v4, "attribute does not exist")) -``` - - This example produces the following output: - -``` -c1:attribute 1 content -c2:2 -c3:attribute does not exist -c4:attribute does not exist - -v1:attribute 1 content -v2:2 -v3:attribute does not exist -v4:attribute does not exist -``` - + and the events. + + If you're getting the value and the attribute might not exist, it is more convenient to use the explicit conversion operators, and assign the attribute to a nullable type such as `string` or of . If the attribute does not exist, then the nullable type is set to `null`. Before using this property, you must make sure that the method does not return `null`. + +## Examples + The following example creates an element with an attribute. It then retrieves the value of the attribute, and then sets it. + + Note that the Visual Basic example uses the XML attribute property. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att", "content") +); +XAttribute att = root.FirstAttribute; +Console.WriteLine(att.Value); +att.Value = "new text"; +Console.WriteLine(att.Value); +``` + +```vb +Dim root As XElement = +Console.WriteLine(root.@Att) +root.@Att = "new text" +Console.WriteLine(root.@Att) +``` + + This example produces the following output: + +``` +content +new text +``` + + The following example shows the benefit of using the explicit conversion operators to get the value of an attribute that might not exist: + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att1", "attribute 1 content"), + new XAttribute("Att2", "2") +); + +// The following assignments demonstrate why it is easier to use +// casting when the attribute might or might not exist. + +string c1 = (string)root.Attribute("Att1"); +Console.WriteLine("c1:{0}", c1 == null ? "attribute does not exist" : c1); + +int? c2 = (int?)root.Attribute("Att2"); +Console.WriteLine("c2:{0}", c2 == null ? "attribute does not exist" : c2.ToString()); + +string c3 = (string)root.Attribute("Att3"); +Console.WriteLine("c3:{0}", c3 == null ? "attribute does not exist" : c3); + +int? c4 = (int?)root.Attribute("Att4"); +Console.WriteLine("c4:{0}", c4 == null ? "attribute does not exist" : c4.ToString()); + +Console.WriteLine(); + +// The following assignments show the necessary code when using +// the value property when the attribute might or might not exist. + +XAttribute att1 = root.Attribute("Att1"); +string v1; +if (att1 == null) + v1 = null; +else + v1 = att1.Value; +Console.WriteLine("v1:{0}", v1 == null ? "attribute does not exist" : v1); + +XAttribute att2 = root.Attribute("Att2"); +int? v2; +if (att2 == null) + v2 = null; +else + v2 = Int32.Parse(att2.Value); +Console.WriteLine("v2:{0}", v2 == null ? "attribute does not exist" : v2.ToString()); + +XAttribute att3 = root.Attribute("Att3"); +string v3; +if (att3 == null) + v3 = null; +else + v3 = att3.Value; +Console.WriteLine("v3:{0}", v3 == null ? "attribute does not exist" : v3); + +XAttribute att4 = root.Attribute("Att4"); +int? v4; +if (att4 == null) + v4 = null; +else + v4 = Int32.Parse(att4.Value); +Console.WriteLine("v4:{0}", v4 == null ? "attribute does not exist" : v4.ToString()); +``` + +```vb +Dim root As XElement = + +' The following assignments demonstrate why it is easier to use +' casting when the attribute might or might not exist. + +Dim c1 As String = CStr(root.Attribute("Att1")) +Console.WriteLine("c1:{0}", IIf(c1 Is Nothing, "attribute does not exist", c1)) + +Dim c2 As Nullable(Of Integer) = CType(root.Attribute("Att2"), Nullable(Of Integer)) +Console.WriteLine("c2:{0}", IIf(c2.HasValue, c2, "attribute does not exist")) + +Dim c3 As String = CStr(root.Attribute("Att3")) +Console.WriteLine("c3:{0}", IIf(c3 Is Nothing, "attribute does not exist", c3)) + +Dim c4 As Nullable(Of Integer) = CType(root.Attribute("Att4"), Nullable(Of Integer)) +Console.WriteLine("c4:{0}", IIf(c4.HasValue, c4, "attribute does not exist")) + +Console.WriteLine() + +' The following assignments show the necessary code when using +' the value property when the attribute might or might not exist. + +Dim att1 As XAttribute = root.Attribute("Att1") +Dim v1 As String +If att1 Is Nothing Then + v1 = Nothing +Else + v1 = att1.Value +End If + +Console.WriteLine("v1:{0}", IIf(v1 Is Nothing, "attribute does not exist", v1)) + +Dim att2 As XAttribute = root.Attribute("Att2") +Dim v2 As Nullable(Of Integer) +If att2 Is Nothing Then + v2 = Nothing +Else + v2 = Int32.Parse(att2.Value) +End If + +Console.WriteLine("v2:{0}", IIf(v2.HasValue, v2, "attribute does not exist")) + +Dim att3 As XAttribute = root.Attribute("Att3") +Dim v3 As String +If att3 Is Nothing Then + v3 = Nothing +Else + v3 = att3.Value +End If + +Console.WriteLine("v3:{0}", IIf(v3 Is Nothing, "attribute does not exist", v3)) + +Dim att4 As XAttribute = root.Attribute("Att4") +Dim v4 As Nullable(Of Integer) +If att4 Is Nothing Then + v4 = Nothing +Else + v4 = Int32.Parse(att4.Value) +End If + +Console.WriteLine("v4:{0}", IIf(v4.HasValue, v4, "attribute does not exist")) +``` + + This example produces the following output: + +``` +c1:attribute 1 content +c2:2 +c3:attribute does not exist +c4:attribute does not exist + +v1:attribute 1 content +v2:2 +v3:attribute does not exist +v4:attribute does not exist +``` + ]]> When setting, the is . diff --git a/xml/System.Xml.Linq/XProcessingInstruction.xml b/xml/System.Xml.Linq/XProcessingInstruction.xml index 3664bc780f0..285353713a6 100644 --- a/xml/System.Xml.Linq/XProcessingInstruction.xml +++ b/xml/System.Xml.Linq/XProcessingInstruction.xml @@ -52,13 +52,13 @@ Represents an XML processing instruction. - node. - + node. + ]]> LINQ to XML overview @@ -116,11 +116,11 @@ The node to copy from. Initializes a new instance of the class. - LINQ to XML overview @@ -168,27 +168,27 @@ The string data for this . Initializes a new instance of the class. - , and specifies a target and the string data for the processing instruction. - -```csharp -XProcessingInstruction pi = new XProcessingInstruction("xml-stylesheet", "type='text/xsl' href='hello.xsl'"); -Console.WriteLine(pi); -``` - -```vb -Dim pi As XProcessingInstruction = -Console.WriteLine(pi) -``` - - This example produces the following output: - -``` - -``` - + , and specifies a target and the string data for the processing instruction. + +```csharp +XProcessingInstruction pi = new XProcessingInstruction("xml-stylesheet", "type='text/xsl' href='hello.xsl'"); +Console.WriteLine(pi); +``` + +```vb +Dim pi As XProcessingInstruction = +Console.WriteLine(pi) +``` + + This example produces the following output: + +``` + +``` + ]]> The or parameter is . @@ -240,40 +240,38 @@ Console.WriteLine(pi) Gets or sets the string value of this processing instruction. - A that contains the string value of this processing instruction. + The string value of this processing instruction. - property to retrieve the string value of a processing instruction. - -```csharp -XProcessingInstruction pi = - new XProcessingInstruction("xml-stylesheet", "type='text/xsl' href='hello.xsl'"); -Console.WriteLine(pi.Data); -pi.Data = "type='text/xsl' href='xform.xsl'"; -Console.WriteLine(pi.Data); -``` - -```vb -Dim pi As XProcessingInstruction = -Console.WriteLine(pi.Data) -pi.Data = "type='text/xsl' href='xform.xsl'" -Console.WriteLine(pi.Data) -``` - - This example produces the following output: - -``` -type='text/xsl' href='hello.xsl' -type='text/xsl' href='xform.xsl' -``` - + property to retrieve the string value of a processing instruction. + +```csharp +XProcessingInstruction pi = + new XProcessingInstruction("xml-stylesheet", "type='text/xsl' href='hello.xsl'"); +Console.WriteLine(pi.Data); +pi.Data = "type='text/xsl' href='xform.xsl'"; +Console.WriteLine(pi.Data); +``` + +```vb +Dim pi As XProcessingInstruction = +Console.WriteLine(pi.Data) +pi.Data = "type='text/xsl' href='xform.xsl'" +Console.WriteLine(pi.Data) +``` + + This example produces the following output: + +``` +type='text/xsl' href='hello.xsl' +type='text/xsl' href='xform.xsl' +``` + ]]> The string is . @@ -320,34 +318,34 @@ type='text/xsl' href='xform.xsl' Gets the node type for this node. The node type. For objects, this value is . - contain a property, you can write code that operates on collections of concrete subclass of . Your code can then test for the node type of each node in the collection. - - - -## Examples - The following example creates a processing instruction, and then prints its node type. - -```csharp -XProcessingInstruction pi = - new XProcessingInstruction("xml-stylesheet", "type=\"text/xsl\" href=\"hello.xsl\""); -Console.WriteLine(pi.NodeType); -``` - -```vb -Dim pi As XProcessingInstruction = _ - -Console.WriteLine(pi.NodeType.ToString) -``` - - This example produces the following output: - -``` -ProcessingInstruction -``` - + contain a property, you can write code that operates on collections of concrete subclass of . Your code can then test for the node type of each node in the collection. + + + +## Examples + The following example creates a processing instruction, and then prints its node type. + +```csharp +XProcessingInstruction pi = + new XProcessingInstruction("xml-stylesheet", "type=\"text/xsl\" href=\"hello.xsl\""); +Console.WriteLine(pi.NodeType); +``` + +```vb +Dim pi As XProcessingInstruction = _ + +Console.WriteLine(pi.NodeType.ToString) +``` + + This example produces the following output: + +``` +ProcessingInstruction +``` + ]]> LINQ to XML overview @@ -396,36 +394,36 @@ ProcessingInstruction System.String - Gets or sets a string containing the target application for this processing instruction. - A containing the target application for this processing instruction. + Gets or sets the target application for this processing instruction. + The target application for this processing instruction. - property to retrieve the target application for a processing instruction. - -```csharp -XProcessingInstruction pi = - new XProcessingInstruction("xml-stylesheet", "type=\"text/xsl\" href=\"hello.xsl\""); -Console.WriteLine(pi.Target); -``` - -```vb -Dim pi As XProcessingInstruction = _ - -Console.WriteLine(pi.Target) -``` - - This example produces the following output: - -``` -xml-stylesheet -``` - + property to retrieve the target application for a processing instruction. + +```csharp +XProcessingInstruction pi = + new XProcessingInstruction("xml-stylesheet", "type=\"text/xsl\" href=\"hello.xsl\""); +Console.WriteLine(pi.Target); +``` + +```vb +Dim pi As XProcessingInstruction = _ + +Console.WriteLine(pi.Target) +``` + + This example produces the following output: + +``` +xml-stylesheet +``` + ]]> The string is . - The does not follow the constraints of an XML name. + The target does not follow the constraints of an XML name. LINQ to XML overview @@ -472,11 +470,11 @@ xml-stylesheet The to write this processing instruction to. Writes this processing instruction to an . - . - + . + ]]> LINQ to XML overview diff --git a/xml/System.Xml.Resolvers/XmlPreloadedResolver.xml b/xml/System.Xml.Resolvers/XmlPreloadedResolver.xml index 0f7ea6e6333..9a5d21bcf52 100644 --- a/xml/System.Xml.Resolvers/XmlPreloadedResolver.xml +++ b/xml/System.Xml.Resolvers/XmlPreloadedResolver.xml @@ -48,11 +48,11 @@ Represents a class that is used to prepopulate the cache with DTDs or XML streams. - type is used as a resolver when automatic calls to the network are not desired or are not possible. For example, this type can be used for loading cached external DTDs. Or, you might use to preload well-known DTDs that are defined in XHTML 1.0. Preloading well-known DTDs does not start any network connections because these DTDs are already embedded in the System.Xml.Utils assembly. Currently, includes the DTDs that are defined in XHTML 1.0 and RSS 0.91. - + type is used as a resolver when automatic calls to the network are not desired or are not possible. For example, this type can be used for loading cached external DTDs. Or, you might use to preload well-known DTDs that are defined in XHTML 1.0. Preloading well-known DTDs does not start any network connections because these DTDs are already embedded in the System.Xml.Utils assembly. Currently, includes the DTDs that are defined in XHTML 1.0 and RSS 0.91. + ]]> @@ -296,11 +296,11 @@ The implementation of the generic interface to use when you compare URIs. Initializes a new instance of the class with the specified fallback resolver, preloaded well-known DTDs, and URI equality comparer. - @@ -502,10 +502,10 @@ or is . - or is less than 0. - - -or- - + or is less than 0. + + -or- + The length of the minus is less than . @@ -601,19 +601,19 @@ Maps a URI to an object that contains the actual resource. A or object that corresponds to the actual source. - will first try to look up the resource in its store of preloaded data. If it cannot find it, it will call the fallback resolver's `GetEntity` method. If no fallback resolver was provided in the constructor, an exception is thrown. - + will first try to look up the resource in its store of preloaded data. If it cannot find it, it will call the fallback resolver's `GetEntity` method. If no fallback resolver was provided in the constructor, an exception is thrown. + ]]> is . - Cannot resolve URI passed in . - - -or- - + Cannot resolve URI passed in . + + -or- + is not of a supported type. @@ -758,11 +758,11 @@ The URI of the data that should be removed from the store. Removes the data that corresponds to the URI from the . - @@ -820,7 +820,7 @@ The representing the absolute URI or if the relative URI cannot be resolved. To be added. - is . + is . @@ -876,7 +876,7 @@ if the is supported; otherwise, . To be added. - is . + is . diff --git a/xml/System.Xml.Schema/XmlSchemaObjectCollection.xml b/xml/System.Xml.Schema/XmlSchemaObjectCollection.xml index 0e7a8d5210c..8ab6167a680 100644 --- a/xml/System.Xml.Schema/XmlSchemaObjectCollection.xml +++ b/xml/System.Xml.Schema/XmlSchemaObjectCollection.xml @@ -50,11 +50,11 @@ A collection of s. - for an example using this class. - + for an example using this class. + ]]> @@ -199,49 +199,43 @@ - The . + The to add to the collection. Adds an to the . The index at which the item has been added. - method expects only and its derived types (, , and ) as parameters. The following example illustrates adding an included schema to the collection of an existing object. - -```vb -Dim schema As XmlSchema = New XmlSchema() - -Dim textReader As XmlTextReader = New XmlTextReader("include.xsd") -Dim includeSchema As XmlSchema = XmlSchema.Read(textReader, null) - -Dim include As XmlSchemaInclude = New XmlSchemaInclude() -include.Schema = includeSchema; -schema.Includes.Add(include); -``` - -```csharp -XmlSchema schema = new XmlSchema(); - -XmlTextReader textReader = new XmlTextReader("include.xsd"); -XmlSchema includeSchema = XmlSchema.Read(textReader, null); - -XmlSchemaInclude include = new XmlSchemaInclude(); -include.Schema = includeSchema; -schema.Includes.Add(include); -``` - + method expects only and its derived types (, , and ) as parameters. The following example illustrates adding an included schema to the collection of an existing object. + +```vb +Dim schema As XmlSchema = New XmlSchema() + +Dim textReader As XmlTextReader = New XmlTextReader("include.xsd") +Dim includeSchema As XmlSchema = XmlSchema.Read(textReader, null) + +Dim include As XmlSchemaInclude = New XmlSchemaInclude() +include.Schema = includeSchema; +schema.Includes.Add(include); +``` + +```csharp +XmlSchema schema = new XmlSchema(); + +XmlTextReader textReader = new XmlTextReader("include.xsd"); +XmlSchema includeSchema = XmlSchema.Read(textReader, null); + +XmlSchemaInclude include = new XmlSchemaInclude(); +include.Schema = includeSchema; +schema.Includes.Add(include); +``` + ]]> - - is less than zero. - - -or- - - is greater than . The parameter specified is not of type or its derived types , , and . @@ -335,13 +329,13 @@ schema.Includes.Add(include); The zero-based index in the array at which copying begins. Copies all the s from the collection into the given array, starting at the given index. - to copy the elements. - + to copy the elements. + ]]> @@ -349,14 +343,14 @@ schema.Includes.Add(include); is less than zero. - is multi-dimensional. - + is multi-dimensional. + -or- - - is equal to or greater than the length of . - + + is equal to or greater than the length of . + -or- - + The number of elements in the source is greater than the available space from index to the end of the destination array. The type of the source cannot be cast automatically to the type of the destination array. @@ -492,22 +486,22 @@ schema.Includes.Add(include); The to insert. Inserts an to the . - - is less than zero. - - -or- - + is less than zero. + + -or- + is greater than . @@ -786,15 +780,15 @@ schema.Includes.Add(include); The to remove. Removes an from the . - . That is, this method is an O(`n`) operation, where `n` is . - - This method determines equality by calling . - - The elements that follow the removed element move up to occupy the vacated spot. - + . That is, this method is an O(`n`) operation, where `n` is . + + This method determines equality by calling . + + The elements that follow the removed element move up to occupy the vacated spot. + ]]> diff --git a/xml/System.Xml.Serialization/XmlAttributeEventArgs.xml b/xml/System.Xml.Serialization/XmlAttributeEventArgs.xml index f2b2666612d..b31ff71a068 100644 --- a/xml/System.Xml.Serialization/XmlAttributeEventArgs.xml +++ b/xml/System.Xml.Serialization/XmlAttributeEventArgs.xml @@ -50,29 +50,29 @@ Provides data for the event. - event occurs only when you call the method. - - - -## Examples - The following example deserializes a class named `Group` from a file named UnknownAttributes.xml. Whenever an element is found in the file that has no corresponding member in the class, the event occurs. To try the example, paste the following XML code into a file named UnknownAttributes.xml. - -``` - - - MyGroup - -``` - + event occurs only when you call the method. + + + +## Examples + The following example deserializes a class named `Group` from a file named UnknownAttributes.xml. Whenever an element is found in the file that has no corresponding member in the class, the event occurs. To try the example, paste the following XML code into a file named UnknownAttributes.xml. + +``` + + + MyGroup + +``` + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributeEventArgs/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -123,22 +123,22 @@ Gets an object that represents the unknown XML attribute. An that represents the unknown XML attribute. - event occurs. To try the example, paste the following XML code into a file named UnknownAttributes.xml. - -``` - - - MyGroup - -``` - + event occurs. To try the example, paste the following XML code into a file named UnknownAttributes.xml. + +``` + + + MyGroup + +``` + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributeEventArgs/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -181,7 +181,7 @@ Gets a comma-delimited list of XML attribute names expected to be in an XML document instance. - A comma-delimited list of XML attribute names. Each name is in the following format: :. + A comma-delimited list of XML attribute names. Each name is in the following format: :. To be added. @@ -230,22 +230,22 @@ Gets the line number of the unknown XML attribute. The line number of the unknown XML attribute. - event occurs. To try the example, paste the following XML code into a file named UnknownAttributes.xml. - -``` - - - MyGroup - -``` - + event occurs. To try the example, paste the following XML code into a file named UnknownAttributes.xml. + +``` + + + MyGroup + +``` + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributeEventArgs/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -295,22 +295,22 @@ Gets the position in the line of the unknown XML attribute. The position number of the unknown XML attribute. - event occurs. To try the example, paste the following XML code into a file named UnknownAttributes.xml. - -``` - - - MyGroup - -``` - + event occurs. To try the example, paste the following XML code into a file named UnknownAttributes.xml. + +``` + + + MyGroup + +``` + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributeEventArgs/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlSerializer.UnknownAttribute Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -365,15 +365,15 @@ Gets the object being deserialized. The object being deserialized. - method when the method encounters an unknown attribute. - + method when the method encounters an unknown attribute. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributeEventArgs.ObjectBeingDeserialized Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributeEventArgs/ObjectBeingDeserialized/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeEventArgs.ObjectBeingDeserialized Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeEventArgs.ObjectBeingDeserialized Example/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Xml.Serialization/XmlSerializationReader+CollectionFixup.xml b/xml/System.Xml.Serialization/XmlSerializationReader+CollectionFixup.xml index 68d9772b821..443df2a50e3 100644 --- a/xml/System.Xml.Serialization/XmlSerializationReader+CollectionFixup.xml +++ b/xml/System.Xml.Serialization/XmlSerializationReader+CollectionFixup.xml @@ -49,15 +49,15 @@ Holds an delegate instance, plus the method's inputs; also supplies the method's parameters. - class. During this process, the infrastructure generates methods that implement the delegate. Additionally, it instantiates class objects to store the fix-up methods along with their inputs. The infrastructure does so for SOAP-encoded arrays or SOAP-encoded, multireferenced elements whose data types, in either case, map to .NET Framework collections or enumerations. Then, as necessary, the methods are invoked during deserialization to fill in array items or multireferenced objects. - - Do not directly instantiate or . - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + class. During this process, the infrastructure generates methods that implement the delegate. Additionally, it instantiates class objects to store the fix-up methods along with their inputs. The infrastructure does so for SOAP-encoded arrays or SOAP-encoded, multireferenced elements whose data types, in either case, map to .NET Framework collections or enumerations. Then, as necessary, the methods are invoked during deserialization to fill in array items or multireferenced objects. + + Do not directly instantiate or . + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -121,11 +121,11 @@ An array into which the callback method copies a collection. Initializes a new instance of the class with parameters for a callback method. - class or the delegate. - + class or the delegate. + ]]> @@ -224,14 +224,14 @@ System.Object - Gets the for the callback method. + Gets the object collection for the callback method. The collection that is used for the fixup. - property gets the collection into which the method that implements the delegate copies the array that is obtained through the property. - + property gets the collection into which the method that implements the delegate copies the array that is obtained through the property. + ]]> @@ -281,11 +281,11 @@ Gets the array into which the callback method copies a collection. The array into which the callback method copies a collection. - property gets the array that the method that implements the delegate copies into the collection object that is obtained through the property. - + property gets the array that the method that implements the delegate copies into the collection object that is obtained through the property. + ]]> diff --git a/xml/System.Xml.Xsl/XslCompiledTransform.xml b/xml/System.Xml.Xsl/XslCompiledTransform.xml index aa88980fb6e..3cfc2f6aedb 100644 --- a/xml/System.Xml.Xsl/XslCompiledTransform.xml +++ b/xml/System.Xml.Xsl/XslCompiledTransform.xml @@ -1566,8 +1566,6 @@ xslt.Load(typeof(bookOrders)); An with default settings is used to load the input document. DTD processing is disabled on the . If you require DTD processing, create an with this feature enabled, and pass it to the method. - - ## Examples The following example uses an object to create a parameter representing the current date and time. @@ -1588,7 +1586,7 @@ xslt.Load(typeof(bookOrders)); The or value is . There was an error executing the XSLT transform. - The value includes a filename or directory cannot be found. + The value includes a filename or directory cannot be found. The value cannot be resolved. -or- diff --git a/xml/System.Xml/UniqueId.xml b/xml/System.Xml/UniqueId.xml index dc546e8db02..fecf145a7d4 100644 --- a/xml/System.Xml/UniqueId.xml +++ b/xml/System.Xml/UniqueId.xml @@ -52,11 +52,11 @@ A unique identifier optimized for Guids. - s. - + s. + ]]> @@ -149,11 +149,11 @@ A byte array that represents a . Creates a new instance of this class using a byte array that represents a . - @@ -260,11 +260,11 @@ A string used to generate the . Creates a new instance of this class using a string. - @@ -328,11 +328,11 @@ Offset position within the array that represents a . Creates a new instance of this class starting from an offset within a array that represents a . - @@ -770,23 +770,21 @@ The array. - Position in the array to start inserting the value. + The position in the array to start inserting the value. Puts the value into a array. - Number of entries in the array filled by the value. + The number of entries in the array filled by the value. - is . less than zero or greater than the length of the array. - - and provide less than 16 valid bytes. @@ -896,15 +894,11 @@ - The if successful; otherwise . + When this method returns, contains the if successful; otherwise . Tries to get the value of the as a . if the UniqueId represents a ; otherwise . To be added. - - is . - - and provide less than 16 valid bytes. @@ -969,11 +963,11 @@ if the value stored in this instance of is a ; otherwise . - diff --git a/xml/System.Xml/XmlConvert.xml b/xml/System.Xml/XmlConvert.xml index 041bb47ba17..dc76605aed8 100644 --- a/xml/System.Xml/XmlConvert.xml +++ b/xml/System.Xml/XmlConvert.xml @@ -2936,7 +2936,7 @@ The to be converted. - The format to which is converted. The format parameter can be any subset of the W3C Recommendation for the XML dateTime type. (For more information, see the dateTime section of the XML Schema specification..) + The format to which is converted. The format parameter can be any subset of the W3C Recommendation for the XML dateTime type. (For more information, see the dateTime section of the XML Schema specification..) Converts the supplied to a in the specified format. A representation in the specified format of the supplied . diff --git a/xml/System.Xml/XmlDictionaryReader.xml b/xml/System.Xml/XmlDictionaryReader.xml index 9a2be1d9524..a7f42c3156d 100644 --- a/xml/System.Xml/XmlDictionaryReader.xml +++ b/xml/System.Xml/XmlDictionaryReader.xml @@ -1023,7 +1023,7 @@ ]]> - is . + is . diff --git a/xml/System.Xml/XmlNodeReader.xml b/xml/System.Xml/XmlNodeReader.xml index 1bb11b42eb1..58283892266 100644 --- a/xml/System.Xml/XmlNodeReader.xml +++ b/xml/System.Xml/XmlNodeReader.xml @@ -598,14 +598,14 @@ Output: ## Remarks -> [!NOTE] -> In the .NET Framework 2.0, the recommended practice is to create instances using the class and the method. This allows you to take full advantage of all the new features introduced in the .NET Framework. For more information, see the Remarks section in the reference page. +The recommended practice is to create instances using the class and the method. - This method does not move the reader. +This method does not move the reader. ]]> - The parameter is less than 0 or greater than or equal to . + + is less than 0 or greater than or equal to . @@ -1056,14 +1056,14 @@ String dt4 = reader.GetAttribute("dt",http://www.w3.org/2000/xmlns/); ## Remarks -> [!NOTE] -> In the .NET Framework 2.0, the recommended practice is to create instances using the class and the method. This allows you to take full advantage of all the new features introduced in the .NET Framework. For more information, see the Remarks section in the reference page. +The recommended practice is to create instances using the class and the method. This property does not move the reader. ]]> - The parameter is less than 0 or greater than or equal to . + + is less than 0 or greater than or equal to . diff --git a/xml/System.Xml/XmlWriter.xml b/xml/System.Xml/XmlWriter.xml index 82a353e41b1..f2c88699b43 100644 --- a/xml/System.Xml/XmlWriter.xml +++ b/xml/System.Xml/XmlWriter.xml @@ -336,8 +336,6 @@ An method was called before a previous asy Also, XmlWriter always writes a Byte Order Mark (BOM) to the underlying data stream; however, some streams must not have a BOM. To omit the BOM, create a new object and set the Encoding property to be a new object with the Boolean value in the constructor set to false. - - ## Examples The following example writes an XML fragment to a memory stream. (It uses the overload, which also configures the settings on the new XML writer instance.) @@ -346,7 +344,8 @@ An method was called before a previous asy ]]> - The value is . + + is . @@ -423,8 +422,6 @@ An method was called before a previous asy If you want to specify the features to support on the created writer, use an overload that takes an object as one of its arguments, and pass in an object with your custom settings. - - ## Examples The following example creates a writer that outputs to the console. @@ -433,7 +430,8 @@ An method was called before a previous asy ]]> - The value is . + + is . @@ -507,8 +505,6 @@ An method was called before a previous asy If you want to specify the features to support on the created XML writer, use an overload that takes an object as one of its arguments, and pass in a object with your custom settings. - - ## Examples The following example creates an object and writes a book node. @@ -517,7 +513,7 @@ An method was called before a previous asy ]]> - The value is . + is . @@ -596,7 +592,8 @@ An method was called before a previous asy ]]> - The value is . + + is . @@ -677,7 +674,8 @@ An method was called before a previous asy ]]> - The value is . + + is . @@ -742,8 +740,6 @@ An method was called before a previous asy ## Remarks XmlWriter always writes a Byte Order Mark (BOM) to the underlying data stream; however, some streams must not have a BOM. To omit the BOM, create a new object and set the Encoding property to be a new object with the Boolean value in the constructor set to false. - - ## Examples The following example writes an XML fragment to a memory stream. @@ -752,7 +748,8 @@ An method was called before a previous asy ]]> - The value is . + + is . @@ -822,7 +819,8 @@ An method was called before a previous asy ]]> - The value is . + + is . @@ -889,7 +887,8 @@ An method was called before a previous asy ]]> - The value is . + + is . @@ -949,7 +948,8 @@ An method was called before a previous asy Creates a new instance using the and objects. An object. To be added. - The value is . + + is . @@ -1016,7 +1016,8 @@ An method was called before a previous asy ]]> - The value is . + + is .