Package org.apache.commons.codec.binary

# Class Hex

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

All Implemented Interfaces:
  `BinaryDecoder`, `BinaryEncoder`, `Decoder`, `Encoder`

public class Hex extends Object implements BinaryEncoder, BinaryDecoder
Converts hexadecimal Strings. The Charset used for certain operation can be set, the default is set in `DEFAULT_CHARSET_NAME` This class is thread-safe.

Since:
  1.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Charset`
  `DEFAULT_CHARSET`
  Default charset is `StandardCharsets.UTF_8`.
  `static final String`
  `DEFAULT_CHARSET_NAME`
  Default charset name is `CharEncoding.UTF_8`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Hex()`
  Creates a new codec with the default charset name `DEFAULT_CHARSET`
  `Hex(String charsetName)`
  Creates a new codec with the given charset name.
  `Hex(Charset charset)`
  Creates a new codec with the given Charset.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `byte[]`
  `decode(byte[] array)`
  Converts an array of character bytes representing hexadecimal values into an array of bytes of those same values.
  `Object`
  `decode(Object object)`
  Converts a String or an array of character bytes representing hexadecimal values into an array of bytes of those same values.
  `byte[]`
  `decode(ByteBuffer buffer)`
  Converts a buffer of character bytes representing hexadecimal values into an array of bytes of those same values.
  `static byte[]`
  `decodeHex(char[] data)`
  Converts an array of characters representing hexadecimal values into an array of bytes of those same values.
  `static int`
  `decodeHex(char[] data, byte[] out, int outOffset)`
  Converts an array of characters representing hexadecimal values into an array of bytes of those same values.
  `static byte[]`
  `decodeHex(String data)`
  Converts a String representing hexadecimal values into an array of bytes of those same values.
  `byte[]`
  `encode(byte[] array)`
  Converts an array of bytes into an array of bytes for the characters representing the hexadecimal values of each byte in order.
  `Object`
  `encode(Object object)`
  Converts a String or an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
  `byte[]`
  `encode(ByteBuffer array)`
  Converts byte buffer into an array of bytes for the characters representing the hexadecimal values of each byte in order.
  `static char[]`
  `encodeHex(byte[] data)`
  Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
  `static char[]`
  `encodeHex(byte[] data, boolean toLowerCase)`
  Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
  `protected static char[]`
  `encodeHex(byte[] data, char[] toDigits)`
  Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
  `static char[]`
  `encodeHex(byte[] data, int dataOffset, int dataLen, boolean toLowerCase)`
  Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
  `static void`
  `encodeHex(byte[] data, int dataOffset, int dataLen, boolean toLowerCase, char[] out, int outOffset)`
  Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
  `static char[]`
  `encodeHex(ByteBuffer data)`
  Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order.
  `static char[]`
  `encodeHex(ByteBuffer data, boolean toLowerCase)`
  Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order.
  `protected static char[]`
  `encodeHex(ByteBuffer byteBuffer, char[] toDigits)`
  Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order.
  `static String`
  `encodeHexString(byte[] data)`
  Converts an array of bytes into a String representing the hexadecimal values of each byte in order.
  `static String`
  `encodeHexString(byte[] data, boolean toLowerCase)`
  Converts an array of bytes into a String representing the hexadecimal values of each byte in order.
  `static String`
  `encodeHexString(ByteBuffer data)`
  Converts a byte buffer into a String representing the hexadecimal values of each byte in order.
  `static String`
  `encodeHexString(ByteBuffer data, boolean toLowerCase)`
  Converts a byte buffer into a String representing the hexadecimal values of each byte in order.
  `Charset`
  `getCharset()`
  Gets the charset.
  `String`
  `getCharsetName()`
  Gets the charset name.
  `protected static int`
  `toDigit(char ch, int index)`
  Converts a hexadecimal character to an integer.
  `String`
  `toString()`
  Returns a string representation of the object, which includes the charset name.

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

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

- ## Field Details

  - ### DEFAULT_CHARSET

    public static final Charset DEFAULT_CHARSET
    Default charset is `StandardCharsets.UTF_8`.
    Since:
      1.7

  - ### DEFAULT_CHARSET_NAME

    public static final String DEFAULT_CHARSET_NAME
    Default charset name is `CharEncoding.UTF_8`.
    Since:
      1.4

- ## Constructor Details

  - ### Hex

    public Hex()
    Creates a new codec with the default charset name `DEFAULT_CHARSET`

  - ### Hex

    public Hex(Charset charset)
    Creates a new codec with the given Charset.
    Parameters:
      `charset` - the charset.
    Since:
      1.7

  - ### Hex

    public Hex(String charsetName)
    Creates a new codec with the given charset name.
    Parameters:
      `charsetName` - the charset name.
    Throws:
      `UnsupportedCharsetException` - If the named charset is unavailable
    Since:
      1.4, 1.7 throws UnsupportedCharsetException if the named charset is unavailable

- ## Method Details

  - ### decodeHex

    public static byte[] decodeHex(char[] data) throws DecoderException
    Converts an array of characters representing hexadecimal values into an array of bytes of those same values. The returned array will be half the length of the passed array, as it takes two characters to represent any given byte. An exception is thrown if the passed char array has an odd number of elements.
    Parameters:
      `data` - An array of characters containing hexadecimal digits
    Returns:
      A byte array containing binary data decoded from the supplied char array.
    Throws:
      `DecoderException` - Thrown if an odd number of characters or illegal characters are supplied

  - ### decodeHex

    public static int decodeHex(char[] data, byte[] out, int outOffset) throws DecoderException
    Converts an array of characters representing hexadecimal values into an array of bytes of those same values. The returned array will be half the length of the passed array, as it takes two characters to represent any given byte. An exception is thrown if the passed char array has an odd number of elements.
    Parameters:
      `data` - An array of characters containing hexadecimal digits
      `out` - A byte array to contain the binary data decoded from the supplied char array.
      `outOffset` - The position within `out` to start writing the decoded bytes.
    Returns:
      the number of bytes written to `out`.
    Throws:
      `DecoderException` - Thrown if an odd number of characters or illegal characters are supplied
    Since:
      1.15

  - ### decodeHex

    public static byte[] decodeHex(String data) throws DecoderException
    Converts a String representing hexadecimal values into an array of bytes of those same values. The returned array will be half the length of the passed String, as it takes two characters to represent any given byte. An exception is thrown if the passed String has an odd number of elements.
    Parameters:
      `data` - A String containing hexadecimal digits
    Returns:
      A byte array containing binary data decoded from the supplied char array.
    Throws:
      `DecoderException` - Thrown if an odd number of characters or illegal characters are supplied
    Since:
      1.11

  - ### encodeHex

    public static char[] encodeHex(byte[] data)
    Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.
    Parameters:
      `data` - a byte[] to convert to hexadecimal characters
    Returns:
      A char[] containing lower-case hexadecimal characters

  - ### encodeHex

    public static char[] encodeHex(byte[] data, boolean toLowerCase)
    Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.
    Parameters:
      `data` - a byte[] to convert to Hex characters
      `toLowerCase` - `true` converts to lowercase, `false` to uppercase
    Returns:
      A char[] containing hexadecimal characters in the selected case
    Since:
      1.4

  - ### encodeHex

    protected static char[] encodeHex(byte[] data, char[] toDigits)
    Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.
    Parameters:
      `data` - a byte[] to convert to hexadecimal characters
      `toDigits` - the output alphabet (must contain at least 16 chars)
    Returns:
      A char[] containing the appropriate characters from the alphabet For best results, this should be either upper- or lower-case hex.
    Since:
      1.4

  - ### encodeHex

    public static char[] encodeHex(byte[] data, int dataOffset, int dataLen, boolean toLowerCase)
    Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
    Parameters:
      `data` - a byte[] to convert to hexadecimal characters
      `dataOffset` - the position in `data` to start encoding from
      `dataLen` - the number of bytes from `dataOffset` to encode
      `toLowerCase` - `true` converts to lowercase, `false` to uppercase
    Returns:
      A char[] containing the appropriate characters from the alphabet For best results, this should be either upper- or lower-case hex.
    Since:
      1.15

  - ### encodeHex

    public static void encodeHex(byte[] data, int dataOffset, int dataLen, boolean toLowerCase, char[] out, int outOffset)
    Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
    Parameters:
      `data` - a byte[] to convert to hexadecimal characters
      `dataOffset` - the position in `data` to start encoding from
      `dataLen` - the number of bytes from `dataOffset` to encode
      `toLowerCase` - `true` converts to lowercase, `false` to uppercase
      `out` - a char[] which will hold the resultant appropriate characters from the alphabet.
      `outOffset` - the position within `out` at which to start writing the encoded characters.
    Since:
      1.15

  - ### encodeHex

    public static char[] encodeHex(ByteBuffer data)
    Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

    All bytes identified by `Buffer.remaining()` will be used; after this method the value `remaining()` will be zero.

    Parameters:
      `data` - a byte buffer to convert to hexadecimal characters
    Returns:
      A char[] containing lower-case hexadecimal characters
    Since:
      1.11

  - ### encodeHex

    public static char[] encodeHex(ByteBuffer data, boolean toLowerCase)
    Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

    All bytes identified by `Buffer.remaining()` will be used; after this method the value `remaining()` will be zero.

    Parameters:
      `data` - a byte buffer to convert to hexadecimal characters
      `toLowerCase` - `true` converts to lowercase, `false` to uppercase
    Returns:
      A char[] containing hexadecimal characters in the selected case
    Since:
      1.11

  - ### encodeHex

    protected static char[] encodeHex(ByteBuffer byteBuffer, char[] toDigits)
    Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

    All bytes identified by `Buffer.remaining()` will be used; after this method the value `remaining()` will be zero.

    Parameters:
      `byteBuffer` - a byte buffer to convert to hexadecimal characters
      `toDigits` - the output alphabet (must be at least 16 characters)
    Returns:
      A char[] containing the appropriate characters from the alphabet For best results, this should be either upper- or lower-case hex.
    Since:
      1.11

  - ### encodeHexString

    public static String encodeHexString(byte[] data)
    Converts an array of bytes into a String representing the hexadecimal values of each byte in order. The returned String will be double the length of the passed array, as it takes two characters to represent any given byte.
    Parameters:
      `data` - a byte[] to convert to hexadecimal characters
    Returns:
      A String containing lower-case hexadecimal characters
    Since:
      1.4

  - ### encodeHexString

    public static String encodeHexString(byte[] data, boolean toLowerCase)
    Converts an array of bytes into a String representing the hexadecimal values of each byte in order. The returned String will be double the length of the passed array, as it takes two characters to represent any given byte.
    Parameters:
      `data` - a byte[] to convert to hexadecimal characters
      `toLowerCase` - `true` converts to lowercase, `false` to uppercase
    Returns:
      A String containing lower-case hexadecimal characters
    Since:
      1.11

  - ### encodeHexString

    public static String encodeHexString(ByteBuffer data)
    Converts a byte buffer into a String representing the hexadecimal values of each byte in order. The returned String will be double the length of the passed array, as it takes two characters to represent any given byte.

    All bytes identified by `Buffer.remaining()` will be used; after this method the value `remaining()` will be zero.

    Parameters:
      `data` - a byte buffer to convert to hexadecimal characters
    Returns:
      A String containing lower-case hexadecimal characters
    Since:
      1.11

  - ### encodeHexString

    public static String encodeHexString(ByteBuffer data, boolean toLowerCase)
    Converts a byte buffer into a String representing the hexadecimal values of each byte in order. The returned String will be double the length of the passed array, as it takes two characters to represent any given byte.

    All bytes identified by `Buffer.remaining()` will be used; after this method the value `remaining()` will be zero.

    Parameters:
      `data` - a byte buffer to convert to hexadecimal characters
      `toLowerCase` - `true` converts to lowercase, `false` to uppercase
    Returns:
      A String containing lower-case hexadecimal characters
    Since:
      1.11

  - ### toDigit

    protected static int toDigit(char ch, int index) throws DecoderException
    Converts a hexadecimal character to an integer.
    Parameters:
      `ch` - A character to convert to an integer digit
      `index` - The index of the character in the source
    Returns:
      An integer
    Throws:
      `DecoderException` - Thrown if ch is an illegal hexadecimal character

  - ### decode

    public byte[] decode(byte[] array) throws DecoderException
    Converts an array of character bytes representing hexadecimal values into an array of bytes of those same values. The returned array will be half the length of the passed array, as it takes two characters to represent any given byte. An exception is thrown if the passed char array has an odd number of elements.
    Specified by:
      `decode` in interface `BinaryDecoder`
    Parameters:
      `array` - An array of character bytes containing hexadecimal digits
    Returns:
      A byte array containing binary data decoded from the supplied byte array (representing characters).
    Throws:
      `DecoderException` - Thrown if an odd number of characters is supplied to this function
    See Also:
      - `decodeHex(char[])`

  - ### decode

    public byte[] decode(ByteBuffer buffer) throws DecoderException
    Converts a buffer of character bytes representing hexadecimal values into an array of bytes of those same values. The returned array will be half the length of the passed array, as it takes two characters to represent any given byte. An exception is thrown if the passed char array has an odd number of elements.

    All bytes identified by `Buffer.remaining()` will be used; after this method the value `remaining()` will be zero.

    Parameters:
      `buffer` - An array of character bytes containing hexadecimal digits
    Returns:
      A byte array containing binary data decoded from the supplied byte array (representing characters).
    Throws:
      `DecoderException` - Thrown if an odd number of characters is supplied to this function
    Since:
      1.11
    See Also:
      - `decodeHex(char[])`

  - ### decode

    public Object decode(Object object) throws DecoderException
    Converts a String or an array of character bytes representing hexadecimal values into an array of bytes of those same values. The returned array will be half the length of the passed String or array, as it takes two characters to represent any given byte. An exception is thrown if the passed char array has an odd number of elements.
    Specified by:
      `decode` in interface `Decoder`
    Parameters:
      `object` - A String, ByteBuffer, byte[], or an array of character bytes containing hexadecimal digits
    Returns:
      A byte array containing binary data decoded from the supplied byte array (representing characters).
    Throws:
      `DecoderException` - Thrown if an odd number of characters is supplied to this function or the object is not a String or char[]
    See Also:
      - `decodeHex(char[])`

  - ### encode

    public byte[] encode(byte[] array)
    Converts an array of bytes into an array of bytes for the characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

    The conversion from hexadecimal characters to the returned bytes is performed with the charset named by `getCharset()`.

    Specified by:
      `encode` in interface `BinaryEncoder`
    Parameters:
      `array` - a byte[] to convert to hexadecimal characters
    Returns:
      A byte[] containing the bytes of the lower-case hexadecimal characters
    Since:
      1.7 No longer throws IllegalStateException if the charsetName is invalid.
    See Also:
      - `encodeHex(byte[])`

  - ### encode

    public byte[] encode(ByteBuffer array)
    Converts byte buffer into an array of bytes for the characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

    The conversion from hexadecimal characters to the returned bytes is performed with the charset named by `getCharset()`.

    All bytes identified by `Buffer.remaining()` will be used; after this method the value `remaining()` will be zero.

    Parameters:
      `array` - a byte buffer to convert to hexadecimal characters
    Returns:
      A byte[] containing the bytes of the lower-case hexadecimal characters
    Since:
      1.11
    See Also:
      - `encodeHex(byte[])`

  - ### encode

    public Object encode(Object object) throws EncoderException
    Converts a String or an array of bytes into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed String or array, as it takes two characters to represent any given byte.

    The conversion from hexadecimal characters to bytes to be encoded to performed with the charset named by `getCharset()`.

    Specified by:
      `encode` in interface `Encoder`
    Parameters:
      `object` - a String, ByteBuffer, or byte[] to convert to hexadecimal characters
    Returns:
      A char[] containing lower-case hexadecimal characters
    Throws:
      `EncoderException` - Thrown if the given object is not a String or byte[]
    See Also:
      - `encodeHex(byte[])`

  - ### getCharset

    public Charset getCharset()
    Gets the charset.
    Returns:
      the charset.
    Since:
      1.7

  - ### getCharsetName

    public String getCharsetName()
    Gets the charset name.
    Returns:
      the charset name.
    Since:
      1.4

  - ### toString

    public String toString()
    Returns a string representation of the object, which includes the charset name.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of the object.