Package com.saperion.common.lang.conversion

Class Conversion

  • public final class Conversion
extends java.lang.Object
    Utility class for conversion.

    Supports the following conversions typically in both directions:

    • hex-char <-> byte
    • char[] of hex-char <-> byte[] (with optional header and spacing)
    • base64-char <-> byte
    • char[] of base64-char <-> byte[]
    • InputStream -> byte[] (only one way; to implement the inverse direction simply construct a ByteArrayInputStream)
    • Serializable <-> byte[]
    • Collection<String> <-> String (with separator and correct escaping)

    All these methods are optimized for speed! Do not change them without controlling their performance behavior!

    Many methods return a char[] instead of a String as some might expect. This is done out of performance considerations too. If one really needs a String it can be constructed by String.valueOf(char[]). But in many cases the converted result will not be used directly, but instead will be copied into a StringBuilder/StringBuffer or some kind of Writer. In such cases one should use the char[] directly and avoid an intermediate String.

    Author:
    agz

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static byte convertBase64CharacterToByte​(char base64Character)
      Converts the specified a base64 character to a byte value.
      static byte[] convertBase64ToByteArray​(char[] arBase64Chars)
      Parses the specified char[] assuming that it consists of base64 encoded quadruples of characters and converts it to a byte[].
      static byte[] convertBase64ToByteArray​(char[] arBase64Chars, int beginIndex, int endIndex)
      Parses the specified char[] section from the specified begin index to the specified end index - 1 assuming that it consists of base64 encoded quadruples of characters and converts it to a byte[].
      static byte[] convertBase64ToByteArray​(java.lang.String base64String)
      Parses the specified String assuming that it consists of base64 encoded quadruples of characters and converts it to a byte[].
      static byte[] convertBase64ToByteArray​(java.lang.String base64String, int beginIndex, int endIndex)
      Parses the specified String section from the specified begin index to the specified end index - 1 assuming that it consists of base64 encoded quadruples of characters and converts it to a byte[].
      static char[] convertByteArrayToBase64​(byte[] arBytes)
      Returns a char[] containing a base64 encoding that represents the bytes of the specified byte[].
      static char[] convertByteArrayToBase64​(byte[] arBytes, int beginIndex, int endIndex)
      Returns a char[] containing a base64 encoding that represents the bytes of the specified byte[] section from the specified begin index to the specified end index - 1.
      static char[] convertByteArrayToHexDigits​(byte[] arBytes)
      Returns a char[] containing pairwise hexadecimal digits that represent the bytes of the specified byte[].
      static char[] convertByteArrayToHexDigits​(byte[] arBytes, char blockSeparator, int blockSize)
      Returns a char[] containing pairwise hexadecimal digits that represent the bytes of the specified byte[] optionally separated at the specified interval of bytes by the specified separator character.
      static char[] convertByteArrayToHexDigits​(byte[] arBytes, int beginIndex, int endIndex)
      Returns a char[] containing pairwise hexadecimal digits that represent the bytes of the specified byte[] section from the specified begin index to the specified end index - 1.
      static char[] convertByteArrayToHexDigits​(byte[] arBytes, int beginIndex, int endIndex, char blockSeparator, int blockSize)
      Returns a char[] containing pairwise hexadecimal digits that represent the bytes of the specified byte[] section from the specified begin index to the specified end index - 1 optionally separated at the specified interval of bytes by the specified separator character.
      static char[] convertByteArrayToHexDigits​(byte[] arBytes, int beginIndex, int endIndex, java.lang.String header)
      Returns a char[] containing pairwise hexadecimal digits that represent the bytes of the specified byte[] section from the specified begin index to the specified end index - 1 optionally preceded by the specified header string.
      static char[] convertByteArrayToHexDigits​(byte[] arBytes, int beginIndex, int endIndex, java.lang.String header, char blockSeparator, int blockSize)
      Returns a char[] containing pairwise hexadecimal digits that represent the bytes of the specified byte[] section from the specified begin index to the specified end index - 1 optionally separated at the specified interval of bytes by the specified separator character and optionally preceded by the specified header string.
      static char[] convertByteArrayToHexDigits​(byte[] arBytes, java.lang.String header)
      Returns a char[] containing pairwise hexadecimal digits that represent the bytes of the specified byte[] optionally preceded by the specified header string.
      static char[] convertByteArrayToHexDigits​(byte[] arBytes, java.lang.String header, char blockSeparator, int blockSize)
      Returns a char[] containing pairwise hexadecimal digits that represent the bytes of the specified byte[] optionally separated at the specified interval of bytes by the specified separator character and optionally preceded by the specified header string.
      static java.io.Serializable convertByteArrayToSerializable​(byte[] arBytes)
      Converts the specified byte[] into a Serializable using standard deserialization.
      static byte[] convertHexDigitsToByteArray​(char[] arHexChars)
      Parses the specified char[] assuming that it consists of pairs of hexadecimal digits optionally separated by other characters.
      static byte[] convertHexDigitsToByteArray​(char[] arHexChars, int beginIndex)
      Parses the specified char[] section from the specified begin index to its end assuming that it consists of pairs of hexadecimal digits optionally separated by other characters.
      static byte[] convertHexDigitsToByteArray​(char[] arHexChars, int beginIndex, int endIndex)
      Parses the specified char[] section from the specified begin index to the specified end index - 1 assuming that it consists of pairs of hexadecimal digits optionally separated by other characters.
      static byte[] convertHexDigitsToByteArray​(java.lang.String hexString)
      Parses the specified String assuming that it consists of pairs of hexadecimal digits optionally separated by other characters.
      static byte[] convertHexDigitsToByteArray​(java.lang.String hexString, int beginIndex)
      Parses the specified String section from the specified begin index to its end assuming that it consists of pairs of hexadecimal digits optionally separated by other characters.
      static byte[] convertHexDigitsToByteArray​(java.lang.String hexString, int beginIndex, int endIndex)
      Parses the specified String section from the specified begin index to the specified end index - 1 assuming that it consists of pairs of hexadecimal digits optionally separated by other characters.
      static byte convertHexDigitToByte​(char digit)
      Converts the specified a hexadecimal digit character to a byte value.
      static byte[] convertInputStreamToByteArray​(java.io.InputStream inputStream)
      Deprecated.
      use Streams.convertInputStreamToByteArray(java.io.InputStream) instead
      static char convertIntToBase64Character​(int i)
      Converts the specified integer value to a base64 character.
      static char convertIntToHexDigit​(int i)
      Converts the specified integer value to a hexadecimal digit character.
      static byte[] convertSerializableToByteArray​(java.io.Serializable serializable, int sizeGuess)
      Converts the specified Serializable into a byte[] using standard serialization.
      static java.lang.String convertStringCollectionToString​(java.util.Collection<java.lang.String> colStrings, char separator, char escape, java.lang.String nullString)
      Converts the specified collection of strings to a string using the specified separator, escape character and string for null-elements.
      static java.util.List<java.lang.String> convertStringToStringList​(java.lang.String string, char separator, char escape, java.lang.String nullString)
      Converts the specified string to a list of strings using the specified separator, escape character and string for null-elements.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • convertIntToHexDigit

        public static char convertIntToHexDigit​(int i)
        Converts the specified integer value to a hexadecimal digit character. Letters are in upper case always.

        Returns 0xffff if the specified integer value is less than 0 or greater than 15.

        Returns char '0'-'9' (0x0030-0x0039) if the specified integer is in the range 0-9.

        Returns char 'A'-'F' (0x0061-0x0066) if the specified integer is in the range 10-15.

        Parameters:
        i - integer value to convert
        Returns:
        hexadecimal digit character for the specified integer value or 0xffff
        See Also:
        convertHexDigitToByte(char)

      • convertHexDigitToByte

        public static byte convertHexDigitToByte​(char digit)
        Converts the specified a hexadecimal digit character to a byte value. Letters may be upper or lower case.

        Returns -1 if the specified character is not a hexadecimal digit.

        Returns 0-9 if the specified character is char '0'-'9' ( 0x0030-0x0039).

        Returns 10-15 if the specified character is char 'A'-'F' ( 0x0061-0x0066).

        Returns 10-15 if the specified character is char 'a'-'f' ( 0x0041-0x0046).

        Parameters:
        digit - hexadecimal digit character to convert
        Returns:
        byte value of the specified hexadecimal digit character or -1
        See Also:
        convertIntToHexDigit(int)

      • convertByteArrayToHexDigits

        public static char[] convertByteArrayToHexDigits​(byte[] arBytes,
                                                 int beginIndex,
                                                 int endIndex,
                                                 java.lang.String header,
                                                 char blockSeparator,
                                                 int blockSize)
        Returns a char[] containing pairwise hexadecimal digits that represent the bytes of the specified byte[] section from the specified begin index to the specified end index - 1 optionally separated at the specified interval of bytes by the specified separator character and optionally preceded by the specified header string. The resulting char[] has exactly the necessary size.

        The specified byte[] must not be null.

        Throws an IndexOutOfBoundsException if the specified begin or end index is not inside the specified byte[] or equal to its length.

        The specified begin index must not be greater than the specified end index.

        The specified header is optional (may be null, may be an empty string).

        The specified block size must not be less than 0. If a value of 0 is specified no separation is done.

        Parameters:
        arBytes - byte[] to convert to pairwise hexadecimal digits
        beginIndex - begin index of the section of the specified byte[] to convert
        endIndex - end index of the section of the specified byte[] to convert
        header - string to copy at the start of the resulting char[] or null
        blockSeparator - separator character to add every 'blockSize' bytes to the resulting char[]
        blockSize - interval (in bytes) to add the specified separator character to the resulting char[] or 0 if no separation should be done.
        Returns:
        new char[] containing pairwise hexadecimal digits that represent the bytes of the specified byte[] section optionally separated at the specified interval of bytes by the specified separator character and optionally preceded by the specified header string
        See Also:
        convertByteArrayToHexDigits(byte[], int, int, String), convertByteArrayToHexDigits(byte[], int, int, char, int), convertByteArrayToHexDigits(byte[], int, int), convertByteArrayToHexDigits(byte[], String, char, int), convertByteArrayToHexDigits(byte[], String), convertByteArrayToHexDigits(byte[], char, int), convertByteArrayToHexDigits(byte[]), convertHexDigitsToByteArray(String, int, int), convertHexDigitsToByteArray(char[], int, int)

      • convertHexDigitsToByteArray

        public static byte[] convertHexDigitsToByteArray​(java.lang.String hexString,
                                                 int beginIndex,
                                                 int endIndex)
        Parses the specified String section from the specified begin index to the specified end index - 1 assuming that it consists of pairs of hexadecimal digits optionally separated by other characters. Converts these pairs of hexadecimal digits to bytes and returns a new byte[] containing these bytes. The resulting byte[] has exactly the necessary size.

        Returns null if the specified string is null.

        Returns an empty byte[] if the specified string is empty.

        Throws an IndexOutOfBoundsException if the specified begin or end index is not inside the specified string or its String.length().

        The specified begin index must not be greater than the specified end index.

        The specified string section must not contain an impair block of hexadecimal digits.

        Parameters:
        hexString - string containing pairwise hexadecimal digits to convert
        beginIndex - begin index of the section of the specified string to convert
        endIndex - end index of the section of the specified string to convert
        Returns:
        new byte[] containing the parsed content of the specified string section
        See Also:
        convertHexDigitsToByteArray(String, int), convertHexDigitsToByteArray(String), convertHexDigitsToByteArray(char[], int, int), convertByteArrayToHexDigits(byte[], int, int, String, char, int)

      • convertHexDigitsToByteArray

        public static byte[] convertHexDigitsToByteArray​(java.lang.String hexString,
                                                 int beginIndex)
        Parses the specified String section from the specified begin index to its end assuming that it consists of pairs of hexadecimal digits optionally separated by other characters. Converts these pairs of hexadecimal digits to bytes and returns a new byte[] containing these bytes. The resulting byte[] has exactly the necessary size.

        Returns null if the specified string is null.

        Returns an empty byte[] if the specified string is empty.

        Throws an IndexOutOfBoundsException if the specified begin index is not inside the specified string.

        The specified string section must not contain an impair block of hexadecimal digits.

        Parameters:
        hexString - string containing pairwise hexadecimal digits to convert
        beginIndex - begin index of the section of the specified string to convert
        Returns:
        new byte[] containing the parsed content of the specified string section
        See Also:
        convertHexDigitsToByteArray(String, int, int), convertHexDigitsToByteArray(String), convertHexDigitsToByteArray(char[], int, int), convertByteArrayToHexDigits(byte[], int, int, String, char, int)

      • convertHexDigitsToByteArray

        public static byte[] convertHexDigitsToByteArray​(char[] arHexChars,
                                                 int beginIndex,
                                                 int endIndex)
        Parses the specified char[] section from the specified begin index to the specified end index - 1 assuming that it consists of pairs of hexadecimal digits optionally separated by other characters. Converts these pairs of hexadecimal digits to bytes and returns a new byte[] containing these bytes. The resulting byte[] has exactly the necessary size.

        Returns null if the specified char[] is null.

        Returns an empty byte[] if the specified char[] is empty.

        Throws an IndexOutOfBoundsException if the specified begin or end index is not inside the specified char[] or equal to its length.

        The specified begin index must not be greater than the specified end index.

        The specified char[] section must not contain an impair block of hexadecimal digits.

        Parameters:
        arHexChars - char[] containing pairwise hexadecimal digits to convert
        beginIndex - begin index of the section of the specified char[] to convert
        endIndex - end index of the section of the specified char[] to convert
        Returns:
        new byte[] containing the parsed content of the specified char[] section
        See Also:
        convertHexDigitsToByteArray(char[], int), convertHexDigitsToByteArray(char[]), convertHexDigitsToByteArray(String, int, int), convertByteArrayToHexDigits(byte[], int, int, String, char, int)

      • convertHexDigitsToByteArray

        public static byte[] convertHexDigitsToByteArray​(char[] arHexChars,
                                                 int beginIndex)
        Parses the specified char[] section from the specified begin index to its end assuming that it consists of pairs of hexadecimal digits optionally separated by other characters. Converts these pairs of hexadecimal digits to bytes and returns a new byte[] containing these bytes. The resulting byte[] has exactly the necessary size.

        Returns null if the specified char[] is null.

        Returns an empty byte[] if the specified char[] is empty.

        Throws an IndexOutOfBoundsException if the specified begin index is not inside the specified char[].

        The specified char[] section must not contain an impair block of hexadecimal digits.

        Parameters:
        arHexChars - char[] containing pairwise hexadecimal digits to convert
        beginIndex - begin index of the section of the specified char[] to convert
        Returns:
        new byte[] containing the parsed content of the specified char[] section
        See Also:
        convertHexDigitsToByteArray(char[], int, int), convertHexDigitsToByteArray(char[]), convertHexDigitsToByteArray(String, int, int), convertByteArrayToHexDigits(byte[], int, int, String, char, int)

      • convertIntToBase64Character

        public static char convertIntToBase64Character​(int i)
        Converts the specified integer value to a base64 character.

        Returns 0xffff if the specified integer value is less than 0 or greater than 63.

        Parameters:
        i - integer value to convert
        Returns:
        base64 character for the specified integer value or 0xffff
        See Also:
        convertBase64CharacterToByte(char)

      • convertBase64CharacterToByte

        public static byte convertBase64CharacterToByte​(char base64Character)
        Converts the specified a base64 character to a byte value.

        Returns -1 if the specified character is not a base64 character.

        Parameters:
        base64Character - base64 character to convert
        Returns:
        byte value of the specified base64 character or -1
        See Also:
        convertIntToBase64Character(int)

      • convertByteArrayToBase64

        public static char[] convertByteArrayToBase64​(byte[] arBytes,
                                              int beginIndex,
                                              int endIndex)
        Returns a char[] containing a base64 encoding that represents the bytes of the specified byte[] section from the specified begin index to the specified end index - 1. The resulting char[] has exactly the necessary size.

        The specified byte[] must not be null.

        Throws an IndexOutOfBoundsException if the specified begin or end index is not inside the specified byte[] or equal to its length.

        The specified begin index must not be greater than the specified end index.

        Parameters:
        arBytes - byte[] to convert to base64 encoded characters
        beginIndex - begin index of the section of the specified byte[] to convert
        endIndex - end index of the section of the specified byte[] to convert
        Returns:
        new char[] containing a base64 encoding that represent the bytes of the specified byte[] section
        See Also:
        convertByteArrayToBase64(byte[])

      • convertByteArrayToBase64

        public static char[] convertByteArrayToBase64​(byte[] arBytes)
        Returns a char[] containing a base64 encoding that represents the bytes of the specified byte[]. The resulting char[] has exactly the necessary size.

        The specified byte[] must not be null.

        Parameters:
        arBytes - byte[] to convert to base64 encoded characters
        Returns:
        new char[] containing a base64 encoding that represent the bytes of the specified byte[]
        See Also:
        convertByteArrayToBase64(byte[], int, int)

      • convertBase64ToByteArray

        public static byte[] convertBase64ToByteArray​(java.lang.String base64String,
                                              int beginIndex,
                                              int endIndex)
        Parses the specified String section from the specified begin index to the specified end index - 1 assuming that it consists of base64 encoded quadruples of characters and converts it to a byte[]. The resulting byte[] has exactly the necessary size.

        Returns null if the specified string is null.

        Returns an empty byte[] if the specified string section is empty.

        Throws an IndexOutOfBoundsException if the specified begin or end index is not inside the specified string or its String.length().

        The specified begin index must not be greater than the specified end index.

        The specified string sections size must be a multiple of 4.

        Parameters:
        base64String - string containing base64 encoded quadruples of characters to convert
        beginIndex - begin index of the section of the specified string to convert
        endIndex - end index of the section of the specified string to convert
        Returns:
        new byte[] containing the parsed content of the specified string section
        See Also:
        convertBase64ToByteArray(String), convertBase64ToByteArray(char[], int, int), convertByteArrayToBase64(byte[], int, int)

      • convertBase64ToByteArray

        public static byte[] convertBase64ToByteArray​(java.lang.String base64String)
        Parses the specified String assuming that it consists of base64 encoded quadruples of characters and converts it to a byte[]. The resulting byte[] has exactly the necessary size.

        Returns null if the specified string is null.

        Returns an empty byte[] if the specified string is empty.

        The specified string size must be a multiple of 4.

        Parameters:
        base64String - string containing base64 encoded quadruples of characters to convert
        Returns:
        new byte[] containing the parsed content of the specified string
        See Also:
        convertBase64ToByteArray(String, int, int), convertBase64ToByteArray(char[]), convertByteArrayToBase64(byte[], int, int)

      • convertBase64ToByteArray

        public static byte[] convertBase64ToByteArray​(char[] arBase64Chars,
                                              int beginIndex,
                                              int endIndex)
        Parses the specified char[] section from the specified begin index to the specified end index - 1 assuming that it consists of base64 encoded quadruples of characters and converts it to a byte[]. The resulting byte[] has exactly the necessary size.

        Returns null if the specified char[] is null.

        Returns an empty byte[] if the specified char[] is empty.

        Throws an IndexOutOfBoundsException if the specified begin or end index is not inside the specified char[] or equal to its length.

        The specified begin index must not be greater than the specified end index.

        The specified char[] sections size must be a multiple of 4.

        Parameters:
        arBase64Chars - char[] containing base64 encoded quadruples of characters to convert
        beginIndex - begin index of the section of the specified char[] to convert
        endIndex - end index of the section of the specified char[] to convert
        Returns:
        new byte[] containing the parsed content of the specified char[] section
        See Also:
        convertBase64ToByteArray(char[]), convertBase64ToByteArray(String, int, int), convertByteArrayToBase64(byte[], int, int)

      • convertBase64ToByteArray

        public static byte[] convertBase64ToByteArray​(char[] arBase64Chars)
        Parses the specified char[] assuming that it consists of base64 encoded quadruples of characters and converts it to a byte[]. The resulting byte[] has exactly the necessary size.

        Returns null if the specified char[] is null.

        Returns an empty byte[] if the specified char[] is empty.

        The specified char[] size must be a multiple of 4.

        Parameters:
        arBase64Chars - char[] containing base64 encoded quadruples of characters to convert
        Returns:
        new byte[] containing the parsed content of the specified char[]
        See Also:
        convertBase64ToByteArray(char[], int, int), convertBase64ToByteArray(String, int, int), convertByteArrayToBase64(byte[], int, int)

      • convertInputStreamToByteArray

        @Deprecated
public static byte[] convertInputStreamToByteArray​(java.io.InputStream inputStream)
                                            throws java.io.IOException
        Deprecated.
        use Streams.convertInputStreamToByteArray(java.io.InputStream) instead
        Returns the content of the specified InputStream as a byte[], which has exactly the size of the content.

        The specified InputStream must not be null.

        Parameters:
        inputStream - InputStream to convert into a byte[]
        Returns:
        byte[] with the content of the specified InputStream
        Throws:
        java.io.IOException - on errors reading the inputStream

      • convertSerializableToByteArray

        public static byte[] convertSerializableToByteArray​(java.io.Serializable serializable,
                                                    int sizeGuess)
                                             throws java.io.IOException
        Converts the specified Serializable into a byte[] using standard serialization.

        The specified size guess need not be exact, i.e. in can be too small or too large. The returned byte[] has always exactly the necessary size. The parameter is for optimization of memory allocation only and a good guess should be provided by the caller.

        The specified size guess must be greater than 0.

        Parameters:
        serializable - the Serializable to convert
        sizeGuess - size guess
        Returns:
        a byte[] containing the converted Serializable
        Throws:
        java.io.IOException - on errors during serialization

      • convertByteArrayToSerializable

        public static java.io.Serializable convertByteArrayToSerializable​(byte[] arBytes)
                                                           throws java.io.IOException,
                                                                  java.lang.ClassNotFoundException
        Converts the specified byte[] into a Serializable using standard deserialization.

        The specified byte[] must not be null.

        Parameters:
        arBytes - byte[] to convert
        Returns:
        the converted Serializable
        Throws:
        java.io.IOException - on errors during deserialization
        java.lang.ClassNotFoundException - on errors during deserialization

      • convertStringCollectionToString

        public static java.lang.String convertStringCollectionToString​(java.util.Collection<java.lang.String> colStrings,
                                                               char separator,
                                                               char escape,
                                                               java.lang.String nullString)
        Converts the specified collection of strings to a string using the specified separator, escape character and string for null-elements. All strings created with this method can be converted back with convertStringToStringList(String, char, char, String), so that the resulting list will contain equal strings to the original collection.

        This method is intended for data conversion and therefore needs to use escape sequences to create a bijective format. For a non-escaping method see Strings.format(Collection, String, String), f.e. to create a human-readable simple output.

        If the specified collection is null, then null will be returned. If the specified collection is empty, an empty string will be returned.

        The specified separator and escape characters must be different.

        The specified string for null-elements must not be null or empty and must not start with the specified escape character.

        Parameters:
        colStrings - collection of strings to convert
        separator - separator character, a usual value is ';'
        escape - escape character, a usual value is '/'
        nullString - string for null-elements, a usual value is "<null>"
        Returns:
        string
        See Also:
        convertStringToStringList(String, char, char, String), Strings.format(Collection, String, String)

      • convertStringToStringList

        public static java.util.List<java.lang.String> convertStringToStringList​(java.lang.String string,
                                                                         char separator,
                                                                         char escape,
                                                                         java.lang.String nullString)
        Converts the specified string to a list of strings using the specified separator, escape character and string for null-elements. All strings created with convertStringCollectionToString(Collection, char, char, String) can be converted back with this method, so that the resulting list will contain equal strings to the original collection.

        If the specified string is null, then null will be returned. If the specified string is empty, an empty list will be returned.

        The specified separator and escape characters must be different.

        The specified string for null-elements must not be null or empty and must not start with the specified escape character.

        Parameters:
        string - string to convert
        separator - separator character, a usual value is ';'
        escape - escape character, a usual value is '/'
        nullString - string for null-elements, a usual value is "<null>"
        Returns:
        list of strings
        Throws:
        java.lang.IllegalStateException - on format errors in the specified string
        See Also:
        convertStringCollectionToString(Collection, char, char, String)