Added in API level 34

HexFormat

class HexFormat
kotlin.Any
   ↳ java.util.HexFormat

HexFormat converts between bytes and chars and hex-encoded strings which may include additional formatting markup such as prefixes, suffixes, and delimiters.

There are two factories of HexFormat with preset parameters of() and ofDelimiter(delimiter). For other parameter combinations the withXXX methods return copies of HexFormat modified withPrefix(java.lang.String), withSuffix(java.lang.String), withDelimiter(java.lang.String) or choice of withUpperCase() or withLowerCase() parameters.

For primitive to hexadecimal string conversions the toHexDigits methods include toHexDigits(byte), toHexDigits(int), and toHexDigits(long), etc. The default is to use lowercase characters "0-9","a-f". For conversions producing uppercase hexadecimal the characters are "0-9","A-F". Only the HexFormat.isUpperCase() parameter is considered; the delimiter, prefix and suffix are not used.

For hexadecimal string to primitive conversions the fromHexDigits methods include fromHexDigits(string), fromHexDigitsToLong(string), and fromHexDigit(int) converts a single character or codepoint. For conversions from hexadecimal characters the digits and uppercase and lowercase characters in "0-9", "a-f", and "A-F" are converted to corresponding values 0-15. The delimiter, prefix, suffix, and uppercase parameters are not used.

For byte array to formatted hexadecimal string conversions the formatHex methods include formatHex(byte[]) and formatHex(Appendable, byte[]). The formatted output is a string or is appended to an Appendable such as StringBuilder or java.io.PrintStream. Each byte value is formatted as the prefix, two hexadecimal characters from the uppercase or lowercase digits, and the suffix. A delimiter follows each formatted value, except the last. For conversions producing uppercase hexadecimal strings use withUpperCase().

For formatted hexadecimal string to byte array conversions the parseHex methods include parseHex(CharSequence) and parseHex(char[], offset, length). Each byte value is parsed from the prefix, two case insensitive hexadecimal characters, and the suffix. A delimiter follows each formatted value, except the last.

Summary

Public methods
String!

Returns the delimiter between hexadecimal values in formatted hexadecimal strings.

Boolean
equals(other: Any?)

Returns true if the other object is a HexFormat with the same parameters.

String!

Returns a hexadecimal string formatted from a byte array.

String!
formatHex(bytes: ByteArray!, fromIndex: Int, toIndex: Int)

Returns a hexadecimal string formatted from a byte array range.

A
formatHex(out: A, bytes: ByteArray!)

Appends formatted hexadecimal strings from a byte array to the Appendable.

A
formatHex(out: A, bytes: ByteArray!, fromIndex: Int, toIndex: Int)

Appends formatted hexadecimal strings from a byte array range to the Appendable.

static Int

Returns the value for the hexadecimal character or codepoint.

static Int

Returns the int value parsed from a string of up to eight hexadecimal characters.

static Int
fromHexDigits(string: CharSequence!, fromIndex: Int, toIndex: Int)

Returns the int value parsed from a string range of up to eight hexadecimal characters.

static Long

Returns the long value parsed from a string of up to sixteen hexadecimal characters.

static Long
fromHexDigitsToLong(string: CharSequence!, fromIndex: Int, toIndex: Int)

Returns the long value parsed from a string range of up to sixteen hexadecimal characters.

Int

Returns a hashcode for this HexFormat.

static Boolean

Returns true if the character is a valid hexadecimal character or codepoint.

Boolean

Returns true if the hexadecimal digits are uppercase, otherwise false.

static HexFormat!
of()

Returns a hexadecimal formatter with no delimiter and lowercase characters.

static HexFormat!
ofDelimiter(delimiter: String!)

Returns a hexadecimal formatter with the delimiter and lowercase characters.

ByteArray!

Returns a byte array containing hexadecimal values parsed from the string.

ByteArray!
parseHex(string: CharSequence!, fromIndex: Int, toIndex: Int)

Returns a byte array containing hexadecimal values parsed from a range of the string.

ByteArray!
parseHex(chars: CharArray!, fromIndex: Int, toIndex: Int)

Returns a byte array containing hexadecimal values parsed from a range of the character array.

String!

Returns the prefix used for each hexadecimal value in formatted hexadecimal strings.

String!

Returns the suffix used for each hexadecimal value in formatted hexadecimal strings.

A
toHexDigits(out: A, value: Byte)

Appends two hexadecimal characters for the byte value to the Appendable.

String!
toHexDigits(value: Byte)

Returns the two hexadecimal characters for the byte value.

String!
toHexDigits(value: Char)

Returns the four hexadecimal characters for the char value.

String!

Returns the four hexadecimal characters for the short value.

String!
toHexDigits(value: Int)

Returns the eight hexadecimal characters for the int value.

String!
toHexDigits(value: Long)

Returns the sixteen hexadecimal characters for the long value.

String!
toHexDigits(value: Long, digits: Int)

Returns up to sixteen hexadecimal characters for the long value.

Char

Returns the hexadecimal character for the high 4 bits of the value considering it to be a byte.

Char

Returns the hexadecimal character for the low 4 bits of the value considering it to be a byte.

String

Returns a description of the formatter parameters for uppercase, delimiter, prefix, and suffix.

HexFormat!
withDelimiter(delimiter: String!)

Returns a copy of this HexFormat with the delimiter.

HexFormat!

Returns a copy of this HexFormat to use lowercase hexadecimal characters.

HexFormat!
withPrefix(prefix: String!)

Returns a copy of this HexFormat with the prefix.

HexFormat!
withSuffix(suffix: String!)

Returns a copy of this HexFormat with the suffix.

HexFormat!

Returns a copy of this HexFormat to use uppercase hexadecimal characters.

Public methods

delimiter

Added in API level 34
fun delimiter(): String!

Returns the delimiter between hexadecimal values in formatted hexadecimal strings.

Return
String! the delimiter, non-null, may be empty ""

equals

Added in API level 34
fun equals(other: Any?): Boolean

Returns true if the other object is a HexFormat with the same parameters.

Parameters
obj the reference object with which to compare.
o an object, may be null
Return
Boolean true if the other object is a HexFormat and the parameters uppercase, delimiter, prefix, and suffix are equal; otherwise false

formatHex

Added in API level 34
fun formatHex(bytes: ByteArray!): String!

Returns a hexadecimal string formatted from a byte array. Each byte value is formatted as the prefix, two hexadecimal characters selected from uppercase or lowercase digits, and the suffix. A delimiter follows each formatted value, except the last. The behavior is equivalent to formatHex(bytes, 0, bytes.length)).

Parameters
bytes ByteArray!: a non-null array of bytes
Return
String! a string hexadecimal formatting of the byte array

formatHex

Added in API level 34
fun formatHex(
    bytes: ByteArray!,
    fromIndex: Int,
    toIndex: Int
): String!

Returns a hexadecimal string formatted from a byte array range. Each byte value is formatted as the prefix, two hexadecimal characters selected from uppercase or lowercase digits, and the suffix. A delimiter follows each formatted value, except the last.

Parameters
bytes ByteArray!: a non-null array of bytes
fromIndex Int: the initial index of the range, inclusive
toIndex Int: the final index of the range, exclusive
Return
String! a string hexadecimal formatting each byte of the array range
Exceptions
java.lang.IndexOutOfBoundsException if the array range is out of bounds

formatHex

Added in API level 34
fun <A : Appendable!> formatHex(
    out: A,
    bytes: ByteArray!
): A

Appends formatted hexadecimal strings from a byte array to the Appendable. Each byte value is formatted as the prefix, two hexadecimal characters selected from uppercase or lowercase digits, and the suffix. A delimiter follows each formatted value, except the last. The formatted hexadecimal strings are appended in zero or more calls to the Appendable methods.

Parameters
<A> The type of Appendable
out A: an Appendable, non-null
bytes ByteArray!: a byte array
Return
A the Appendable
Exceptions
java.io.UncheckedIOException if an I/O exception occurs appending to the output

formatHex

Added in API level 34
fun <A : Appendable!> formatHex(
    out: A,
    bytes: ByteArray!,
    fromIndex: Int,
    toIndex: Int
): A

Appends formatted hexadecimal strings from a byte array range to the Appendable. Each byte value is formatted as the prefix, two hexadecimal characters selected from uppercase or lowercase digits, and the suffix. A delimiter follows each formatted value, except the last. The formatted hexadecimal strings are appended in zero or more calls to the Appendable methods.

Parameters
<A> The type of Appendable
out A: an Appendable, non-null
bytes ByteArray!: a byte array, non-null
fromIndex Int: the initial index of the range, inclusive
toIndex Int: the final index of the range, exclusive.
Return
A the Appendable
Exceptions
java.lang.IndexOutOfBoundsException if the array range is out of bounds
java.io.UncheckedIOException if an I/O exception occurs appending to the output

fromHexDigit

Added in API level 34
static fun fromHexDigit(ch: Int): Int

Returns the value for the hexadecimal character or codepoint. The value is:

  • (ch - '0') for '0' through '9' inclusive,
  • (ch - 'A' + 10) for 'A' through 'F' inclusive, and
  • (ch - 'a' + 10) for 'a' through 'f' inclusive.

Parameters
ch Int: a character or codepoint
Return
Int the value 0-15
Exceptions
java.lang.NumberFormatException if the codepoint is not a hexadecimal character

fromHexDigits

Added in API level 34
static fun fromHexDigits(string: CharSequence!): Int

Returns the int value parsed from a string of up to eight hexadecimal characters. The hexadecimal characters are parsed from most significant to least significant using fromHexDigit(int) to form an unsigned value. The value is zero extended to 32 bits and is returned as an int.

Parameters
string CharSequence!: a CharSequence containing up to eight hexadecimal characters
Return
Int the value parsed from the string
Exceptions
java.lang.IllegalArgumentException if the string length is greater than eight (8) or if any of the characters is not a hexadecimal character

fromHexDigits

Added in API level 34
static fun fromHexDigits(
    string: CharSequence!,
    fromIndex: Int,
    toIndex: Int
): Int

Returns the int value parsed from a string range of up to eight hexadecimal characters. The characters in the range fromIndex to toIndex, exclusive, are parsed from most significant to least significant using fromHexDigit(int) to form an unsigned value. The value is zero extended to 32 bits and is returned as an int.

Parameters
string CharSequence!: a CharSequence containing the characters
fromIndex Int: the initial index of the range, inclusive
toIndex Int: the final index of the range, exclusive.
Return
Int the value parsed from the string range
Exceptions
java.lang.IndexOutOfBoundsException if the range is out of bounds for the CharSequence
java.lang.IllegalArgumentException if length of the range is greater than eight (8) or if any of the characters is not a hexadecimal character

fromHexDigitsToLong

Added in API level 34
static fun fromHexDigitsToLong(string: CharSequence!): Long

Returns the long value parsed from a string of up to sixteen hexadecimal characters. The hexadecimal characters are parsed from most significant to least significant using fromHexDigit(int) to form an unsigned value. The value is zero extended to 64 bits and is returned as a long.

Parameters
string CharSequence!: a CharSequence containing up to sixteen hexadecimal characters
Return
Long the value parsed from the string
Exceptions
java.lang.IllegalArgumentException if the string length is greater than sixteen (16) or if any of the characters is not a hexadecimal character

fromHexDigitsToLong

Added in API level 34
static fun fromHexDigitsToLong(
    string: CharSequence!,
    fromIndex: Int,
    toIndex: Int
): Long

Returns the long value parsed from a string range of up to sixteen hexadecimal characters. The characters in the range fromIndex to toIndex, exclusive, are parsed from most significant to least significant using fromHexDigit(int) to form an unsigned value. The value is zero extended to 64 bits and is returned as a long.

Parameters
string CharSequence!: a CharSequence containing the characters
fromIndex Int: the initial index of the range, inclusive
toIndex Int: the final index of the range, exclusive.
Return
Long the value parsed from the string range
Exceptions
java.lang.IndexOutOfBoundsException if the range is out of bounds for the CharSequence
java.lang.IllegalArgumentException if the length of the range is greater than sixteen (16) or if any of the characters is not a hexadecimal character

hashCode

Added in API level 34
fun hashCode(): Int

Returns a hashcode for this HexFormat.

Return
Int a hashcode for this HexFormat

isHexDigit

Added in API level 34
static fun isHexDigit(ch: Int): Boolean

Returns true if the character is a valid hexadecimal character or codepoint. The valid hexadecimal characters are:

  • '0' ('\u005Cu0030') through '9' ('\u005Cu0039') inclusive,
  • 'A' ('\u005Cu0041') through 'F' ('\u005Cu0046') inclusive, and
  • 'a' ('\u005Cu0061') through 'f' ('\u005Cu0066') inclusive.

Parameters
ch Int: a codepoint
Return
Boolean true if the character is valid a hexadecimal character, otherwise false

isUpperCase

Added in API level 34
fun isUpperCase(): Boolean

Returns true if the hexadecimal digits are uppercase, otherwise false.

Return
Boolean true if the hexadecimal digits are uppercase, otherwise false

of

Added in API level 34
static fun of(): HexFormat!

Returns a hexadecimal formatter with no delimiter and lowercase characters. The delimiter, prefix, and suffix are empty. The methods withDelimiter, withUpperCase, withLowerCase, withPrefix, and withSuffix return copies of formatters with new parameters.

Return
HexFormat! a hexadecimal formatter with no delimiter and lowercase characters

ofDelimiter

Added in API level 34
static fun ofDelimiter(delimiter: String!): HexFormat!

Returns a hexadecimal formatter with the delimiter and lowercase characters. The prefix and suffix are empty. The methods withDelimiter, withUpperCase, withLowerCase, withPrefix, and withSuffix return copies of formatters with new parameters.

Parameters
delimiter String!: a delimiter, non-null, may be empty
Return
HexFormat! a HexFormat with the delimiter and lowercase characters

parseHex

Added in API level 34
fun parseHex(string: CharSequence!): ByteArray!

Returns a byte array containing hexadecimal values parsed from the string. Each byte value is parsed from the prefix, two case insensitive hexadecimal characters, and the suffix. A delimiter follows each formatted value, except the last. The delimiters, prefixes, and suffixes strings must be present; they may be empty strings. A valid string consists only of the above format.

Parameters
string CharSequence!: a string containing the byte values with prefix, hexadecimal digits, suffix, and delimiters
Return
ByteArray! a byte array with the values parsed from the string
Exceptions
java.lang.IllegalArgumentException if the prefix or suffix is not present for each byte value, the byte values are not hexadecimal characters, or if the delimiter is not present after all but the last byte value

parseHex

Added in API level 34
fun parseHex(
    string: CharSequence!,
    fromIndex: Int,
    toIndex: Int
): ByteArray!

Returns a byte array containing hexadecimal values parsed from a range of the string. Each byte value is parsed from the prefix, two case insensitive hexadecimal characters, and the suffix. A delimiter follows each formatted value, except the last. The delimiters, prefixes, and suffixes strings must be present; they may be empty strings. A valid string consists only of the above format.

Parameters
string CharSequence!: a string range containing hexadecimal digits, delimiters, prefix, and suffix.
fromIndex Int: the initial index of the range, inclusive
toIndex Int: the final index of the range, exclusive.
Return
ByteArray! a byte array with the values parsed from the string range
Exceptions
java.lang.IllegalArgumentException if the prefix or suffix is not present for each byte value, the byte values are not hexadecimal characters, or if the delimiter is not present after all but the last byte value
java.lang.IndexOutOfBoundsException if the string range is out of bounds

parseHex

Added in API level 34
fun parseHex(
    chars: CharArray!,
    fromIndex: Int,
    toIndex: Int
): ByteArray!

Returns a byte array containing hexadecimal values parsed from a range of the character array. Each byte value is parsed from the prefix, two case insensitive hexadecimal characters, and the suffix. A delimiter follows each formatted value, except the last. The delimiters, prefixes, and suffixes strings must be present; they may be empty strings. A valid character array range consists only of the above format.

Parameters
chars CharArray!: a character array range containing an even number of hexadecimal digits, delimiters, prefix, and suffix.
fromIndex Int: the initial index of the range, inclusive
toIndex Int: the final index of the range, exclusive.
Return
ByteArray! a byte array with the values parsed from the character array range
Exceptions
java.lang.IllegalArgumentException if the prefix or suffix is not present for each byte value, the byte values are not hexadecimal characters, or if the delimiter is not present after all but the last byte value
java.lang.IndexOutOfBoundsException if the character array range is out of bounds

prefix

Added in API level 34
fun prefix(): String!

Returns the prefix used for each hexadecimal value in formatted hexadecimal strings.

Return
String! the prefix, non-null, may be empty ""

suffix

Added in API level 34
fun suffix(): String!

Returns the suffix used for each hexadecimal value in formatted hexadecimal strings.

Return
String! the suffix, non-null, may be empty ""

toHexDigits

Added in API level 34
fun <A : Appendable!> toHexDigits(
    out: A,
    value: Byte
): A

Appends two hexadecimal characters for the byte value to the Appendable. Each nibble (4 bits) from most significant to least significant of the value is formatted as if by toLowHexDigit(nibble). The hexadecimal characters are appended in one or more calls to the Appendable methods. The delimiter, prefix and suffix are not used.

Parameters
<A> The type of Appendable
out A: an Appendable, non-null
value Byte: a byte value
Return
A the Appendable
Exceptions
java.io.UncheckedIOException if an I/O exception occurs appending to the output

toHexDigits

Added in API level 34
fun toHexDigits(value: Byte): String!

Returns the two hexadecimal characters for the byte value. Each nibble (4 bits) from most significant to least significant of the value is formatted as if by toLowHexDigit(nibble). The delimiter, prefix and suffix are not used.

Parameters
value Byte: a byte value
Return
String! the two hexadecimal characters for the byte value

toHexDigits

Added in API level 34
fun toHexDigits(value: Char): String!

Returns the four hexadecimal characters for the char value. Each nibble (4 bits) from most significant to least significant of the value is formatted as if by toLowHexDigit(nibble). The delimiter, prefix and suffix are not used.

Parameters
value Char: a char value
Return
String! the four hexadecimal characters for the char value

toHexDigits

Added in API level 34
fun toHexDigits(value: Short): String!

Returns the four hexadecimal characters for the short value. Each nibble (4 bits) from most significant to least significant of the value is formatted as if by toLowHexDigit(nibble). The delimiter, prefix and suffix are not used.

Parameters
value Short: a short value
Return
String! the four hexadecimal characters for the short value

toHexDigits

Added in API level 34
fun toHexDigits(value: Int): String!

Returns the eight hexadecimal characters for the int value. Each nibble (4 bits) from most significant to least significant of the value is formatted as if by toLowHexDigit(nibble). The delimiter, prefix and suffix are not used.

Parameters
value Int: an int value
Return
String! the eight hexadecimal characters for the int value

toHexDigits

Added in API level 34
fun toHexDigits(value: Long): String!

Returns the sixteen hexadecimal characters for the long value. Each nibble (4 bits) from most significant to least significant of the value is formatted as if by toLowHexDigit(nibble). The delimiter, prefix and suffix are not used.

Parameters
value Long: a long value
Return
String! the sixteen hexadecimal characters for the long value

toHexDigits

Added in API level 34
fun toHexDigits(
    value: Long,
    digits: Int
): String!

Returns up to sixteen hexadecimal characters for the long value. Each nibble (4 bits) from most significant to least significant of the value is formatted as if by toLowHexDigit(nibble). The delimiter, prefix and suffix are not used.

Parameters
value Long: a long value
digits Int: the number of hexadecimal digits to return, 0 to 16
Return
String! the hexadecimal characters for the long value
Exceptions
java.lang.IllegalArgumentException if digits is negative or greater than 16

toHighHexDigit

Added in API level 34
fun toHighHexDigit(value: Int): Char

Returns the hexadecimal character for the high 4 bits of the value considering it to be a byte. If the parameter isUpperCase() is true the character returned for values 10-15 is uppercase "A-F", otherwise the character returned is lowercase "a-f". The values in the range 0-9 are returned as "0-9".

Parameters
value Int: a value, only bits 4-7 of the value are used
Return
Char the hexadecimal character for the bits 4-7 of the value

toLowHexDigit

Added in API level 34
fun toLowHexDigit(value: Int): Char

Returns the hexadecimal character for the low 4 bits of the value considering it to be a byte. If the parameter isUpperCase() is true the character returned for values 10-15 is uppercase "A-F", otherwise the character returned is lowercase "a-f". The values in the range 0-9 are returned as "0-9".

Parameters
value Int: a value, only the low 4 bits 0-3 of the value are used
Return
Char the hexadecimal character for the low 4 bits 0-3 of the value

toString

Added in API level 34
fun toString(): String

Returns a description of the formatter parameters for uppercase, delimiter, prefix, and suffix.

Return
String a description of this HexFormat

withDelimiter

Added in API level 34
fun withDelimiter(delimiter: String!): HexFormat!

Returns a copy of this HexFormat with the delimiter.

Parameters
delimiter String!: the delimiter, non-null, may be empty
Return
HexFormat! a copy of this HexFormat with the delimiter

withLowerCase

Added in API level 34
fun withLowerCase(): HexFormat!

Returns a copy of this HexFormat to use lowercase hexadecimal characters. The lowercase hexadecimal characters are "0-9", "a-f".

Return
HexFormat! a copy of this HexFormat with lowercase hexadecimal characters

withPrefix

Added in API level 34
fun withPrefix(prefix: String!): HexFormat!

Returns a copy of this HexFormat with the prefix.

Parameters
prefix String!: a prefix, non-null, may be empty
Return
HexFormat! a copy of this HexFormat with the prefix

withSuffix

Added in API level 34
fun withSuffix(suffix: String!): HexFormat!

Returns a copy of this HexFormat with the suffix.

Parameters
suffix String!: a suffix, non-null, may be empty
Return
HexFormat! a copy of this HexFormat with the suffix

withUpperCase

Added in API level 34
fun withUpperCase(): HexFormat!

Returns a copy of this HexFormat to use uppercase hexadecimal characters. The uppercase hexadecimal characters are "0-9", "A-F".

Return
HexFormat! a copy of this HexFormat with uppercase hexadecimal characters