diff --git a/xml/System.Text/CodePagesEncodingProvider.xml b/xml/System.Text/CodePagesEncodingProvider.xml index 27e633fc70a..9b29097d407 100644 --- a/xml/System.Text/CodePagesEncodingProvider.xml +++ b/xml/System.Text/CodePagesEncodingProvider.xml @@ -192,8 +192,8 @@ The .NET Framework supports a large number of character encodings and code pages - To be added. - To be added. + Returns an array that contains all the encodings that are supported by the . + An array that contains all the supported encodings. To be added. diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index c843272cb3d..9685bf43e31 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -271,7 +271,7 @@ The following table lists the encodings supported by .NET. It lists each encodin - Change to an application-specific behavior through use of the and classes with the U+FFFD Unicode replacement character. You should throw an exception on any data stream error. An app either uses a "throwonerror" flag when applicable or uses the and classes. Best fit fallback is often not recommended because it can cause data loss or confusion and is slower than simple character replacements. For ANSI encodings, the best fit behavior is the default. - + ## Examples The following example converts a string from one encoding to another. @@ -588,7 +588,7 @@ The following example demonstrates the effect of the ASCII encoding on character :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/VB/bigendianunicode1.vb" id="Snippet2"::: The returned object has , , and properties, which yield the name "unicodeFFFE". Although the UTF-16 big endian byte order mark is hexadecimal FEFF, the name "unicodeFFFE" was chosen because the byte order mark appears as hexadecimal FFFE on little endian Windows computers. - + ## Examples The following example reads a text file with a UTF-16 encoding using the big endian byte order. @@ -2497,7 +2497,7 @@ On .NET Core, the property always returns :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CS/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: ]]> @@ -2951,7 +2951,7 @@ On .NET Core, the property always returns :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CS/getchars.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: - + ]]> @@ -3728,7 +3728,7 @@ In .NET 5.0 and later versions, the code page name `utf-7` is not supported. ## Remarks > [!NOTE] -> - Some unsupported code pages cause the exception to be thrown, whereas others cause . Therefore, your code must catch all exceptions indicated in the Exceptions section. +> - Some unsupported code pages cause the exception to be thrown, whereas others cause . Therefore, your code must catch all exceptions indicated in the Exceptions section. > - In .NET 5.0 and later versions, the code page identifier `65000`, which represents UTF-7, is not supported. In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. @@ -3902,7 +3902,9 @@ In .NET 5.0 and later versions, the code page name `utf-7` is not supported. This method returns a list of supported encodings, uniquely distinguished by code page. For a table that lists the supported encodings, see . > [!NOTE] -> The list of supported encodings returned by the method does not include any additional encodings made available by any implementations that were registered by calls to the method. +> In .NET 5.0 and later versions, the list of supported encodings that returns includes any additional encodings made available by any implementations that were registered by calling . +> +> In .NET Framework and .NET Core, the returned list of supported encodings *does not* include these additional encodings. On .NET Framework, encodings 50220 and 50222 are both associated with the name "iso-2022-jp", but they are not identical. Encoding 50220 converts half-width Katakana characters to full-width Katakana characters, whereas encoding 50222 uses a shift-in/shift-out sequence to encode half-width Katakana characters. The display name for encoding 50222 is "Japanese (JIS-Allow 1 byte Kana - SO/SI)" to distinguish it from encoding 50220, which has the display name "Japanese (JIS)". diff --git a/xml/System.Text/EncodingExtensions.xml b/xml/System.Text/EncodingExtensions.xml index 2798135d7c6..7c1cf676319 100644 --- a/xml/System.Text/EncodingExtensions.xml +++ b/xml/System.Text/EncodingExtensions.xml @@ -14,7 +14,7 @@ - To be added. + Provides extension methods for the encoding types, such as , , and . To be added. @@ -322,7 +322,7 @@ The sequence to encode to bytes. The buffer to which the encoded bytes will be written. Encodes the specified to s using the specified and writes the result to . - To be added. + The number of bytes written to . To be added. contains data that cannot be encoded and is configured to throw when such data is seen. diff --git a/xml/System.Text/EncodingProvider.xml b/xml/System.Text/EncodingProvider.xml index e4e0b406906..e4fa505b63f 100644 --- a/xml/System.Text/EncodingProvider.xml +++ b/xml/System.Text/EncodingProvider.xml @@ -46,41 +46,41 @@ Provides the base class for an encoding provider, which supplies encodings that are unavailable on a particular platform. - method. .NET Core, on the other hand, by default supports only the following encodings: - -- ASCII (code page 20127), which is returned by the property. - -- ISO-8859-1 (code page 28591). - -- UTF-7 (code page 65000), which is returned by the property. - -- UTF-8 (code page 65001), which is returned by the property. - -- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. - -- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. - -- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. - -- UTF-32BE (code page 12001), which is instantiated by calling an constructor that has a `bigEndian` parameter and providing a value of `true` in the method call. - - Starting with the .NET Framework 4.6, is the base class that makes otherwise unavailable encodings available to the .NET Framework. This involves the following steps: - -1. Define a subclass of that overrides the two abstract overloads, and . These overloads return the otherwise unsupported encoding by code page identifier and by name. Note that you can also choose to return a default encoding if the method is called with an argument of 0. - -2. Optionally, you can override the virtual and methods. In most cases, this is not necessary, since the base class provides a default implementation. - -3. Pass the instance to the method to make the encodings supplied by the object available to the common language runtime. - -4. Call an overload to retrieve the encoding. The method will call the corresponding to determine whether it can supply the requested encoding. - - The .NET Framework Class Library provides one static property, , that returns an object that makes the full set of encodings available on the desktop .NET Framework Class Library available to [!INCLUDE[net_core](~/includes/net-core-md.md)] applications. In addition, you can derive from the class to make your own encodings available. - + method. .NET Core, on the other hand, by default supports only the following encodings: + +- ASCII (code page 20127), which is returned by the property. + +- ISO-8859-1 (code page 28591). + +- UTF-7 (code page 65000), which is returned by the property. + +- UTF-8 (code page 65001), which is returned by the property. + +- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. + +- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. + +- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. + +- UTF-32BE (code page 12001), which is instantiated by calling an constructor that has a `bigEndian` parameter and providing a value of `true` in the method call. + + Starting with the .NET Framework 4.6, is the base class that makes otherwise unavailable encodings available to the .NET Framework. This involves the following steps: + +1. Define a subclass of that overrides the two abstract overloads, and . These overloads return the otherwise unsupported encoding by code page identifier and by name. Note that you can also choose to return a default encoding if the method is called with an argument of 0. + +2. Optionally, you can override the virtual and methods. In most cases, this is not necessary, since the base class provides a default implementation. + +3. Pass the instance to the method to make the encodings supplied by the object available to the common language runtime. + +4. Call an overload to retrieve the encoding. The method will call the corresponding to determine whether it can supply the requested encoding. + + The .NET Framework Class Library provides one static property, , that returns an object that makes the full set of encodings available on the desktop .NET Framework Class Library available to [!INCLUDE[net_core](~/includes/net-core-md.md)] applications. In addition, you can derive from the class to make your own encodings available. + ]]> @@ -170,18 +170,18 @@ Returns the encoding associated with the specified code page identifier. The encoding that is associated with the specified code page, or if this cannot return a valid encoding that corresponds to . - ) method to return the encoding or encodings supported by your subclass. When user code attempts to retrieve an encoding by calling the [GetEncoding(Int32)]() method, the method passes the `codepage` identifier to every registered encoding provider until one returns a valid encoding. If none returns a valid encoding, the [GetEncoding(Int32)]() method attempts to retrieve a cached encoding whose code page identifier is `codepage`. Because of this, if `codepage` is not the code page identifier of an encoding that you support, the method should return `null`; it should never throw an exception. - + Note that you can also choose to return a default code page if the value of the `codepage` argument is 0. ## Notes to callers - + This method is called by the [Encoding.GetEncoding(Int32)]() method. You should not call it directly from user code. ]]> @@ -236,10 +236,10 @@ This method is called by the [Encoding.GetEncoding(Int32)](Returns the encoding with the specified name. The encoding that is associated with the specified name, or if this cannot return a valid encoding that corresponds to . - ) method to return the encoding or encodings supported by your subclass. When user code attempts to retrieve an encoding by calling the [GetEncoding(String)]() method, the method passes the `name` argument to every registered encoding provider until one returns a valid encoding. If none returns a valid encoding, the [GetEncoding(String)]() method attempts to retrieve a cached encoding whose name is `name`. Because of this, if `name` is not the name of an encoding that you support, the method should return `null`. The only case in which the method should throw an exception is if `name` is `null`. ## Notes to callers @@ -301,17 +301,17 @@ This method is called by the [Encoding.GetEncoding(String)](Returns the encoding associated with the specified code page identifier. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. The encoding that is associated with the specified code page, or if this cannot return a valid encoding that corresponds to . - , 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. - -- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. - -- Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. - + , 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. + +- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. + +- Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. + ]]> @@ -368,17 +368,17 @@ This method is called by the [Encoding.GetEncoding(String)](Returns the encoding associated with the specified name. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. The encoding that is associated with the specified name, or if this cannot return a valid encoding that corresponds to . - , 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. - -- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. - -- Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. - + , 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. + +- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. + +- Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. + ]]> @@ -413,9 +413,18 @@ This method is called by the [Encoding.GetEncoding(String)]( - To be added. - To be added. - To be added. + Returns an array that contains all the encodings that are supported by the . + An array that contains all the supported encodings. + + , uniquely distinguished by code page. + +> [!NOTE] +> Starting in .NET 5.0, the list of supported encodings returned by includes encodings made available by any implementations that were registered by calls to the method. + + ]]> +