org.apache.commons.io

## Class Charsets

- java.lang.Object
- - org.apache.commons.io.Charsets

-     public class Charsets
      extends Object

  Charsets required of every implementation of the Java platform. From the Java documentation Standard charsets:

  Every implementation of the Java platform is required to support the following character encodings. Consult the release documentation for your implementation to see if any other encodings are supported. Consult the release documentation for your implementation to see if any other encodings are supported.

  - `US-ASCII`
    Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set.
  - `ISO-8859-1`
    ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.
  - `UTF-8`
    Eight-bit Unicode Transformation Format.
  - `UTF-16BE`
    Sixteen-bit Unicode Transformation Format, big-endian byte order.
  - `UTF-16LE`
    Sixteen-bit Unicode Transformation Format, little-endian byte order.
  - `UTF-16`
    Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either order accepted on input, big-endian used on output.)
  See Also:
    Standard charsets

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `isAlias(Charset charset, String charsetName)` Tests whether the given non-null Charset has an alias of the given name.
    `static boolean` | `isUTF8(Charset charset)` Tests whether a given encoding is UTF-8.
    `static SortedMap<String,Charset>` | `requiredCharsets()` Constructs a sorted map from canonical charset names to charset objects required of every implementation of the Java platform.
    `static Charset` | `toCharset(Charset charset)` Returns the given Charset or the `default Charset` if the given Charset is null.
    `static Charset` | `toCharset(Charset charset, Charset defaultCharset)` Returns the given charset if non-null, otherwise return defaultCharset.
    `static Charset` | `toCharset(String charsetName)` Returns a Charset for the named charset.
    `static Charset` | `toCharset(String charsetName, Charset defaultCharset)` Returns a Charset for the named charset.
    `static Charset` | `toCharsetDefault(String charsetName, Charset defaultCharset)` Returns a Charset for the named charset or the `defaultCharset`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### isAlias

          public static boolean isAlias(Charset charset,
                                        String charsetName)

      Tests whether the given non-null Charset has an alias of the given name.
      Parameters:
        `charset` - a non-null Charset.
        `charsetName` - The name to test.
      Returns:
        whether the given non-null charset name is a UTF-8 alias.

    - #### isUTF8

          public static boolean isUTF8(Charset charset)

      Tests whether a given encoding is UTF-8. If the given charset is null, then check the platform's default encoding.
      Parameters:
        `charset` - If the given charset is null, then check the platform's default encoding.
      Returns:
        whether a given encoding is UTF-8.

    - #### requiredCharsets

          public static SortedMap<String,Charset> requiredCharsets()

      Constructs a sorted map from canonical charset names to charset objects required of every implementation of the Java platform.

      From the Java documentation Standard charsets:

      Returns:
        An immutable, case-insensitive map from canonical charset names to charset objects.
      See Also:
        `Charset.availableCharsets()`

    - #### toCharset

          public static Charset toCharset(Charset charset)

      Returns the given Charset or the `default Charset` if the given Charset is null.
      Parameters:
        `charset` - A charset or null.
      Returns:
        the given Charset or the default Charset if the given Charset is null
      See Also:
        `Charset.defaultCharset()`

    - #### toCharset

          public static Charset toCharset(Charset charset,
                                          Charset defaultCharset)

      Returns the given charset if non-null, otherwise return defaultCharset.
      Parameters:
        `charset` - The charset to test, may be null.
        `defaultCharset` - The charset to return if charset is null, may be null.
      Returns:
        a Charset.

    - #### toCharset

          public static Charset toCharset(String charsetName)
                                   throws UnsupportedCharsetException

      Returns a Charset for the named charset. If the name is null, return the `default Charset`.
      Parameters:
        `charsetName` - The name of the requested charset, may be null.
      Returns:
        a Charset for the named charset.
      Throws:
        `UnsupportedCharsetException` - If the named charset is unavailable (unchecked exception).
      See Also:
        `Charset.defaultCharset()`

    - #### toCharset

          public static Charset toCharset(String charsetName,
                                          Charset defaultCharset)
                                   throws UnsupportedCharsetException

      Returns a Charset for the named charset. If the name is null, return the given default Charset.
      Parameters:
        `charsetName` - The name of the requested charset, may be null.
        `defaultCharset` - The charset to return if charsetName is null, may be null.
      Returns:
        a Charset for the named charset.
      Throws:
        `UnsupportedCharsetException` - If the named charset is unavailable (unchecked exception).

    - #### toCharsetDefault

          public static Charset toCharsetDefault(String charsetName,
                                                 Charset defaultCharset)

      Returns a Charset for the named charset or the `defaultCharset`.

      If `charsetName` cannot load a charset, return `defaultCharset`. Therefore, this method should never fail and always return a Charset.

      Parameters:
        `charsetName` - The name of the requested charset, may be null.
        `defaultCharset` - The charset to return if charsetName is null or there is a problem, may be null which returns `Charset.defaultCharset()`.
      Returns:
        a Charset for the named charset or `defaultCharset` if any errors occur.
      See Also:
        `Charset.defaultCharset()`