StringUtils (Encode/Decode Utilities (Version 1.10))
Date: 2018-05-06

org.apache.commons.codec.binary

## Class StringUtils

- java.lang.Object
- - org.apache.commons.codec.binary.StringUtils

-     public class StringUtils
      extends java.lang.Object

  Converts String to and from bytes using the encodings required by the Java specification. These encodings are specified in Standard charsets.

  This class is immutable and thread-safe.

  Since:
    1.4
  Version:
    $Id: StringUtils.java 1634456 2014-10-27 05:26:56Z ggregory $
  See Also:
    `CharEncoding`, Standard charsets

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `StringUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `equals(java.lang.CharSequence cs1, java.lang.CharSequence cs2)` Compares two CharSequences, returning `true` if they represent equal sequences of characters.
    `private static byte[]` | `getBytes(java.lang.String string, java.nio.charset.Charset charset)` Calls `String.getBytes(Charset)`
    `static byte[]` | `getBytesIso8859_1(java.lang.String string)` Encodes the given string into a sequence of bytes using the ISO-8859-1 charset, storing the result into a new byte array.
    `static byte[]` | `getBytesUnchecked(java.lang.String string, java.lang.String charsetName)` Encodes the given string into a sequence of bytes using the named charset, storing the result into a new byte array.
    `static byte[]` | `getBytesUsAscii(java.lang.String string)` Encodes the given string into a sequence of bytes using the US-ASCII charset, storing the result into a new byte array.
    `static byte[]` | `getBytesUtf16(java.lang.String string)` Encodes the given string into a sequence of bytes using the UTF-16 charset, storing the result into a new byte array.
    `static byte[]` | `getBytesUtf16Be(java.lang.String string)` Encodes the given string into a sequence of bytes using the UTF-16BE charset, storing the result into a new byte array.
    `static byte[]` | `getBytesUtf16Le(java.lang.String string)` Encodes the given string into a sequence of bytes using the UTF-16LE charset, storing the result into a new byte array.
    `static byte[]` | `getBytesUtf8(java.lang.String string)` Encodes the given string into a sequence of bytes using the UTF-8 charset, storing the result into a new byte array.
    `private static java.lang.IllegalStateException` | `newIllegalStateException(java.lang.String charsetName, java.io.UnsupportedEncodingException e)`
    `private static java.lang.String` | `newString(byte[] bytes, java.nio.charset.Charset charset)` Constructs a new `String` by decoding the specified array of bytes using the given charset.
    `static java.lang.String` | `newString(byte[] bytes, java.lang.String charsetName)` Constructs a new `String` by decoding the specified array of bytes using the given charset.
    `static java.lang.String` | `newStringIso8859_1(byte[] bytes)` Constructs a new `String` by decoding the specified array of bytes using the ISO-8859-1 charset.
    `static java.lang.String` | `newStringUsAscii(byte[] bytes)` Constructs a new `String` by decoding the specified array of bytes using the US-ASCII charset.
    `static java.lang.String` | `newStringUtf16(byte[] bytes)` Constructs a new `String` by decoding the specified array of bytes using the UTF-16 charset.
    `static java.lang.String` | `newStringUtf16Be(byte[] bytes)` Constructs a new `String` by decoding the specified array of bytes using the UTF-16BE charset.
    `static java.lang.String` | `newStringUtf16Le(byte[] bytes)` Constructs a new `String` by decoding the specified array of bytes using the UTF-16LE charset.
    `static java.lang.String` | `newStringUtf8(byte[] bytes)` Constructs a new `String` by decoding the specified array of bytes using the UTF-8 charset.

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

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

- - ### Constructor Detail

    - #### StringUtils

          public StringUtils()

  - ### Method Detail

    - #### equals

          public static boolean equals(java.lang.CharSequence cs1,
                       java.lang.CharSequence cs2)

      Compares two CharSequences, returning `true` if they represent equal sequences of characters.

      `null`s are handled without exceptions. Two `null` references are considered to be equal. The comparison is case sensitive.

           StringUtils.equals(null, null)   = true
           StringUtils.equals(null, "abc")  = false
           StringUtils.equals("abc", null)  = false
           StringUtils.equals("abc", "abc") = true
           StringUtils.equals("abc", "ABC") = false

      Copied from Apache Commons Lang r1583482 on April 10, 2014 (day of 3.3.2 release).

      Parameters:
        `cs1` - the first CharSequence, may be `null`
        `cs2` - the second CharSequence, may be `null`
      Returns:
        `true` if the CharSequences are equal (case-sensitive), or both `null`
      Since:
        1.10
      See Also:
        `Object.equals(Object)`

    - #### getBytes

          private static byte[] getBytes(java.lang.String string,
                        java.nio.charset.Charset charset)

      Calls `String.getBytes(Charset)`
      Parameters:
        `string` - The string to encode (if null, return null).
        `charset` - The `Charset` to encode the `String`
      Returns:
        the encoded bytes

    - #### getBytesIso8859_1

          public static byte[] getBytesIso8859_1(java.lang.String string)

      Encodes the given string into a sequence of bytes using the ISO-8859-1 charset, storing the result into a new byte array.
      Parameters:
        `string` - the String to encode, may be `null`
      Returns:
        encoded bytes, or `null` if the input string was `null`
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.ISO_8859_1` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException
      See Also:
        Standard charsets, `getBytesUnchecked(String, String)`

    - #### getBytesUnchecked

          public static byte[] getBytesUnchecked(java.lang.String string,
                                 java.lang.String charsetName)

      Encodes the given string into a sequence of bytes using the named charset, storing the result into a new byte array.

      This method catches `UnsupportedEncodingException` and rethrows it as `IllegalStateException`, which should never happen for a required charset name. Use this method when the encoding is required to be in the JRE.

      Parameters:
        `string` - the String to encode, may be `null`
        `charsetName` - The name of a required `Charset`
      Returns:
        encoded bytes, or `null` if the input string was `null`
      Throws:
        `java.lang.IllegalStateException` - Thrown when a `UnsupportedEncodingException` is caught, which should never happen for a required charset name.
      See Also:
        `CharEncoding`, `String.getBytes(String)`

    - #### getBytesUsAscii

          public static byte[] getBytesUsAscii(java.lang.String string)

      Encodes the given string into a sequence of bytes using the US-ASCII charset, storing the result into a new byte array.
      Parameters:
        `string` - the String to encode, may be `null`
      Returns:
        encoded bytes, or `null` if the input string was `null`
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.US_ASCII` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException
      See Also:
        Standard charsets, `getBytesUnchecked(String, String)`

    - #### getBytesUtf16

          public static byte[] getBytesUtf16(java.lang.String string)

      Encodes the given string into a sequence of bytes using the UTF-16 charset, storing the result into a new byte array.
      Parameters:
        `string` - the String to encode, may be `null`
      Returns:
        encoded bytes, or `null` if the input string was `null`
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.UTF_16` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException
      See Also:
        Standard charsets, `getBytesUnchecked(String, String)`

    - #### getBytesUtf16Be

          public static byte[] getBytesUtf16Be(java.lang.String string)

      Encodes the given string into a sequence of bytes using the UTF-16BE charset, storing the result into a new byte array.
      Parameters:
        `string` - the String to encode, may be `null`
      Returns:
        encoded bytes, or `null` if the input string was `null`
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.UTF_16BE` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException
      See Also:
        Standard charsets, `getBytesUnchecked(String, String)`

    - #### getBytesUtf16Le

          public static byte[] getBytesUtf16Le(java.lang.String string)

      Encodes the given string into a sequence of bytes using the UTF-16LE charset, storing the result into a new byte array.
      Parameters:
        `string` - the String to encode, may be `null`
      Returns:
        encoded bytes, or `null` if the input string was `null`
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.UTF_16LE` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException
      See Also:
        Standard charsets, `getBytesUnchecked(String, String)`

    - #### getBytesUtf8

          public static byte[] getBytesUtf8(java.lang.String string)

      Encodes the given string into a sequence of bytes using the UTF-8 charset, storing the result into a new byte array.
      Parameters:
        `string` - the String to encode, may be `null`
      Returns:
        encoded bytes, or `null` if the input string was `null`
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.UTF_8` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException
      See Also:
        Standard charsets, `getBytesUnchecked(String, String)`

    - #### newIllegalStateException

          private static java.lang.IllegalStateException newIllegalStateException(java.lang.String charsetName,
                                                                 java.io.UnsupportedEncodingException e)

    - #### newString

          private static java.lang.String newString(byte[] bytes,
                                   java.nio.charset.Charset charset)

      Constructs a new `String` by decoding the specified array of bytes using the given charset.
      Parameters:
        `bytes` - The bytes to be decoded into characters
        `charset` - The `Charset` to encode the `String`
      Returns:
        A new `String` decoded from the specified array of bytes using the given charset, or `null` if the input byte array was `null`.
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.UTF_8` is not initialized, which should never happen since it is required by the Java platform specification.

    - #### newString

          public static java.lang.String newString(byte[] bytes,
                                   java.lang.String charsetName)

      Constructs a new `String` by decoding the specified array of bytes using the given charset.

      This method catches `UnsupportedEncodingException` and re-throws it as `IllegalStateException`, which should never happen for a required charset name. Use this method when the encoding is required to be in the JRE.

      Parameters:
        `bytes` - The bytes to be decoded into characters, may be `null`
        `charsetName` - The name of a required `Charset`
      Returns:
        A new `String` decoded from the specified array of bytes using the given charset, or `null` if the input byte array was `null`.
      Throws:
        `java.lang.IllegalStateException` - Thrown when a `UnsupportedEncodingException` is caught, which should never happen for a required charset name.
      See Also:
        `CharEncoding`, `String.String(byte[], String)`

    - #### newStringIso8859_1

          public static java.lang.String newStringIso8859_1(byte[] bytes)

      Constructs a new `String` by decoding the specified array of bytes using the ISO-8859-1 charset.
      Parameters:
        `bytes` - The bytes to be decoded into characters, may be `null`
      Returns:
        A new `String` decoded from the specified array of bytes using the ISO-8859-1 charset, or `null` if the input byte array was `null`.
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.ISO_8859_1` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException

    - #### newStringUsAscii

          public static java.lang.String newStringUsAscii(byte[] bytes)

      Constructs a new `String` by decoding the specified array of bytes using the US-ASCII charset.
      Parameters:
        `bytes` - The bytes to be decoded into characters
      Returns:
        A new `String` decoded from the specified array of bytes using the US-ASCII charset, or `null` if the input byte array was `null`.
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.US_ASCII` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException

    - #### newStringUtf16

          public static java.lang.String newStringUtf16(byte[] bytes)

      Constructs a new `String` by decoding the specified array of bytes using the UTF-16 charset.
      Parameters:
        `bytes` - The bytes to be decoded into characters
      Returns:
        A new `String` decoded from the specified array of bytes using the UTF-16 charset or `null` if the input byte array was `null`.
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.UTF_16` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException

    - #### newStringUtf16Be

          public static java.lang.String newStringUtf16Be(byte[] bytes)

      Constructs a new `String` by decoding the specified array of bytes using the UTF-16BE charset.
      Parameters:
        `bytes` - The bytes to be decoded into characters
      Returns:
        A new `String` decoded from the specified array of bytes using the UTF-16BE charset, or `null` if the input byte array was `null`.
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.UTF_16BE` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException

    - #### newStringUtf16Le

          public static java.lang.String newStringUtf16Le(byte[] bytes)

      Constructs a new `String` by decoding the specified array of bytes using the UTF-16LE charset.
      Parameters:
        `bytes` - The bytes to be decoded into characters
      Returns:
        A new `String` decoded from the specified array of bytes using the UTF-16LE charset, or `null` if the input byte array was `null`.
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.UTF_16LE` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException

    - #### newStringUtf8

          public static java.lang.String newStringUtf8(byte[] bytes)

      Constructs a new `String` by decoding the specified array of bytes using the UTF-8 charset.
      Parameters:
        `bytes` - The bytes to be decoded into characters
      Returns:
        A new `String` decoded from the specified array of bytes using the UTF-8 charset, or `null` if the input byte array was `null`.
      Throws:
        `java.lang.NullPointerException` - Thrown if `Charsets.UTF_8` is not initialized, which should never happen since it is required by the Java platform specification.
      Since:
        As of 1.7, throws `NullPointerException` instead of UnsupportedEncodingException

commons-codec version 1.10 - Copyright © 2002-2018 - Apache Software Foundation