Package org.apache.commons.codec.binary

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

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static boolean equals​(java.lang.CharSequence cs1, java.lang.CharSequence cs2)
      Compares two CharSequences, returning true if they represent equal sequences of characters.
      static java.nio.ByteBuffer getByteBufferUtf8​(java.lang.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​(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.
      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

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • StringUtils

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

    • 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.

        nulls 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 java.nio.ByteBuffer getByteBufferUtf8​(java.lang.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:
        java.lang.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​(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 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​(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 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​(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 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​(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 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​(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 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​(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 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 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(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 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 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 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 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 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 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 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 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 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 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 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