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 and Description
    `StringUtils()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and 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 Detail

    - #### StringUtils

          public StringUtils()

  - ### Method Detail

    - #### 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

Copyright © 2002–2023 The Apache Software Foundation. All rights reserved.