StringUtils (Apache Commons Codec 1.22.0 API)
Description: declaration: package: org.apache.commons.codec.binary, class: StringUtils

Package org.apache.commons.codec.binary

# Class StringUtils

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

public class StringUtils extends Object
Converts String to and from bytes using the encodings required by the Java specification. These encodings are specified in standard `Charset`.

This class is immutable and thread-safe.

Since:
  1.4
See Also:
  - `CharEncoding`
  - `Charset`
  - `StandardCharsets`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `StringUtils()`
  Deprecated.
  TODO Make private in 2.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `equals(CharSequence cs1, CharSequence cs2)`
  Compares two CharSequences, returning `true` if they represent equal sequences of characters.
  `static ByteBuffer`
  `getByteBufferUtf8(String string)`
  Encodes the given string into a byte buffer using the UTF-8 charset, storing the result into a new byte array.
  `static byte[]`
  `getBytesIso8859_1(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(String string, 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(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(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(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(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(String string)`
  Encodes the given string into a sequence of bytes using the UTF-8 charset, storing the result into a new byte array.
  `static String`
  `newString(byte[] bytes, String charsetName)`
  Constructs a new `String` by decoding the specified array of bytes using the given charset.
  `static String`
  `newStringIso8859_1(byte[] bytes)`
  Constructs a new `String` by decoding the specified array of bytes using the ISO-8859-1 charset.
  `static String`
  `newStringUsAscii(byte[] bytes)`
  Constructs a new `String` by decoding the specified array of bytes using the US-ASCII charset.
  `static String`
  `newStringUtf16(byte[] bytes)`
  Constructs a new `String` by decoding the specified array of bytes using the UTF-16 charset.
  `static String`
  `newStringUtf16Be(byte[] bytes)`
  Constructs a new `String` by decoding the specified array of bytes using the UTF-16BE charset.
  `static String`
  `newStringUtf16Le(byte[] bytes)`
  Constructs a new `String` by decoding the specified array of bytes using the UTF-16LE charset.
  `static 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 Details

  - ### StringUtils

    @Deprecated public StringUtils()
    Deprecated.
    TODO Make private in 2.0.
    TODO Make private in 2.0.

- ## Method Details

  - ### equals

    public static boolean equals(CharSequence cs1, 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)`

  - ### getByteBufferUtf8

    public static ByteBuffer getByteBufferUtf8(String string)
    Encodes the given string into a byte buffer 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:
      `NullPointerException` - Thrown if `StandardCharsets.UTF_8` is not initialized, which should never happen since it is required by the Java platform specification.
    Since:
      1.11
    See Also:
      - `Charset`
      - `getBytesUnchecked(String, String)`

  - ### getBytesIso8859_1

    public static byte[] getBytesIso8859_1(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:
      `NullPointerException` - Thrown if `StandardCharsets.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:
      - `Charset`
      - `getBytesUnchecked(String, String)`

  - ### getBytesUnchecked

    public static byte[] getBytesUnchecked(String string, 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:
      `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(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:
      `NullPointerException` - Thrown if `StandardCharsets.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:
      - `Charset`
      - `getBytesUnchecked(String, String)`

  - ### getBytesUtf16

    public static byte[] getBytesUtf16(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:
      `NullPointerException` - Thrown if `StandardCharsets.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:
      - `Charset`
      - `getBytesUnchecked(String, String)`

  - ### getBytesUtf16Be

    public static byte[] getBytesUtf16Be(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:
      `NullPointerException` - Thrown if `StandardCharsets.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:
      - `Charset`
      - `getBytesUnchecked(String, String)`

  - ### getBytesUtf16Le

    public static byte[] getBytesUtf16Le(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:
      `NullPointerException` - Thrown if `StandardCharsets.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:
      - `Charset`
      - `getBytesUnchecked(String, String)`

  - ### getBytesUtf8

    public static byte[] getBytesUtf8(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:
      `NullPointerException` - Thrown if `StandardCharsets.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:
      - `Charset`
      - `getBytesUnchecked(String, String)`

  - ### newString

    public static String newString(byte[] bytes, 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:
      `IllegalStateException` - Thrown when a `UnsupportedEncodingException` is caught, which should never happen for a required charset name.
    See Also:
      - `CharEncoding`
      - `String(byte[], String)`

  - ### newStringIso8859_1

    public static 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:
      `NullPointerException` - Thrown if `StandardCharsets.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 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:
      `NullPointerException` - Thrown if `StandardCharsets.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 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:
      `NullPointerException` - Thrown if `StandardCharsets.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 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:
      `NullPointerException` - Thrown if `StandardCharsets.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 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:
      `NullPointerException` - Thrown if `StandardCharsets.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 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:
      `NullPointerException` - Thrown if `StandardCharsets.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.