Back to index...

	/*
	* Copyright (c) 2020, 2021, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package java.util;

	import jdk.internal.access.JavaLangAccess;
	import jdk.internal.access.SharedSecrets;

	import java.io.IOException;
	import java.io.UncheckedIOException;
	import java.nio.CharBuffer;
	import java.nio.charset.CharacterCodingException;
	import java.nio.charset.StandardCharsets;

	/**
	* {@code HexFormat} converts between bytes and chars and hex-encoded strings which may include
	* additional formatting markup such as prefixes, suffixes, and delimiters.
	* <p>
	* There are two factories of {@code HexFormat} with preset parameters {@link #of()} and
	* {@link #ofDelimiter(String) ofDelimiter(delimiter)}. For other parameter combinations
	* the {@code withXXX} methods return copies of {@code HexFormat} modified
	* {@link #withPrefix(String)}, {@link #withSuffix(String)}, {@link #withDelimiter(String)}
	* or choice of {@link #withUpperCase()} or {@link #withLowerCase()} parameters.
	* <p>
	* For primitive to hexadecimal string conversions the {@code toHexDigits}
	* methods include {@link #toHexDigits(byte)}, {@link #toHexDigits(int)}, and
	* {@link #toHexDigits(long)}, etc. The default is to use lowercase characters {@code "0-9","a-f"}.
	* For conversions producing uppercase hexadecimal the characters are {@code "0-9","A-F"}.
	* Only the {@link HexFormat#isUpperCase() HexFormat.isUpperCase()} parameter is
	* considered; the delimiter, prefix and suffix are not used.
	*
	* <p>
	* For hexadecimal string to primitive conversions the {@code fromHexDigits}
	* methods include {@link #fromHexDigits(CharSequence) fromHexDigits(string)},
	* {@link #fromHexDigitsToLong(CharSequence) fromHexDigitsToLong(string)}, and
	* {@link #fromHexDigit(int) fromHexDigit(int)} converts a single character or codepoint.
	* For conversions from hexadecimal characters the digits and uppercase and lowercase
	* characters in {@code "0-9", "a-f", and "A-F"} are converted to corresponding values
	* {@code 0-15}. The delimiter, prefix, suffix, and uppercase parameters are not used.
	*
	* <p>
	* For byte array to formatted hexadecimal string conversions
	* the {@code formatHex} methods include {@link #formatHex(byte[]) formatHex(byte[])}
	* and {@link #formatHex(Appendable, byte[]) formatHex(Appendable, byte[])}.
	* The formatted output is a string or is appended to an {@link Appendable} such as
	* {@link StringBuilder} or {@link 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 {@link #withUpperCase()}.
	*
	* <p>
	* For formatted hexadecimal string to byte array conversions the
	* {@code parseHex} methods include {@link #parseHex(CharSequence) parseHex(CharSequence)} and
	* {@link #parseHex(char[], int, int) 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.
	*
	* @apiNote
	* For example, an individual byte is converted to a string of hexadecimal digits using
	* {@link HexFormat#toHexDigits(int) toHexDigits(int)} and converted from a string to a
	* primitive value using {@link HexFormat#fromHexDigits(CharSequence) fromHexDigits(string)}.
	* <pre>{@code
	* HexFormat hex = HexFormat.of();
	* byte b = 127;
	* String byteStr = hex.toHexDigits(b);
	*
	* byte byteVal = (byte)hex.fromHexDigits(byteStr);
	* assert(byteStr.equals("7f"));
	* assert(b == byteVal);
	*
	* // The hexadecimal digits are: "7f"
	* }</pre>
	* <p>
	* For a comma ({@code ", "}) separated format with a prefix ({@code "#"})
	* using lowercase hex digits the {@code HexFormat} is:
	* <pre>{@code
	* HexFormat commaFormat = HexFormat.ofDelimiter(", ").withPrefix("#");
	* byte[] bytes = {0, 1, 2, 3, 124, 125, 126, 127};
	* String str = commaFormat.formatHex(bytes);
	*
	* byte[] parsed = commaFormat.parseHex(str);
	* assert(Arrays.equals(bytes, parsed));
	*
	* // The formatted string is: "#00, #01, #02, #03, #7c, #7d, #7e, #7f"
	* }</pre>
	* <p>
	* For a fingerprint of byte values that uses the delimiter colon ({@code ":"})
	* and uppercase characters the {@code HexFormat} is:
	* <pre>{@code
	* HexFormat formatFingerprint = HexFormat.ofDelimiter(":").withUpperCase();
	* byte[] bytes = {0, 1, 2, 3, 124, 125, 126, 127};
	* String str = formatFingerprint.formatHex(bytes);
	* byte[] parsed = formatFingerprint.parseHex(str);
	* assert(Arrays.equals(bytes, parsed));
	*
	* // The formatted string is: "00:01:02:03:7C:7D:7E:7F"
	* }</pre>
	*
	* <p>
	* This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
	* class; use of identity-sensitive operations (including reference equality
	* ({@code ==}), identity hash code, or synchronization) on instances of
	* {@code HexFormat} may have unpredictable results and should be avoided.
	* The {@code equals} method should be used for comparisons.
	* <p>
	* This class is immutable and thread-safe.
	* <p>
	* Unless otherwise noted, passing a null argument to any method will cause a
	* {@link java.lang.NullPointerException NullPointerException} to be thrown.
	*
	* @since 17
	*/


	public final class HexFormat {

	// Access to create strings from a byte array.
	private static final JavaLangAccess jla = SharedSecrets.getJavaLangAccess();

	private static final byte[] UPPERCASE_DIGITS = {
	'0', '1', '2', '3', '4', '5', '6', '7',
	'8', '9', 'A', 'B', 'C', 'D', 'E', 'F',
	};
	private static final byte[] LOWERCASE_DIGITS = {
	'0', '1', '2', '3', '4', '5', '6', '7',
	'8', '9', 'a', 'b', 'c', 'd', 'e', 'f',
	};
	// Analysis has shown that generating the whole array allows the JIT to generate
	// better code compared to a slimmed down array, such as one cutting off after 'f'
	private static final byte[] DIGITS = {
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	0, 1, 2, 3, 4, 5, 6, 7, 8, 9, -1, -1, -1, -1, -1, -1,
	-1, 10, 11, 12, 13, 14, 15, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, 10, 11, 12, 13, 14, 15, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
	};
	/**
	* Format each byte of an array as a pair of hexadecimal digits.
	* The hexadecimal characters are from lowercase alpha digits.
	*/
	private static final HexFormat HEX_FORMAT =
	new HexFormat("", "", "", LOWERCASE_DIGITS);

	private static final byte[] EMPTY_BYTES = {};

	private final String delimiter;
	private final String prefix;
	private final String suffix;
	private final byte[] digits;

	/**
	* Returns a HexFormat with a delimiter, prefix, suffix, and array of digits.
	*
	* @param delimiter a delimiter, non-null
	* @param prefix a prefix, non-null
	* @param suffix a suffix, non-null
	* @param digits byte array of digits indexed by low nibble, non-null
	* @throws NullPointerException if any argument is null
	*/
	private HexFormat(String delimiter, String prefix, String suffix, byte[] digits) {
	this.delimiter = Objects.requireNonNull(delimiter, "delimiter");
	this.prefix = Objects.requireNonNull(prefix, "prefix");
	this.suffix = Objects.requireNonNull(suffix, "suffix");
	this.digits = digits;
	}

	/**
	* Returns a hexadecimal formatter with no delimiter and lowercase characters.
	* The delimiter, prefix, and suffix are empty.
	* The methods {@link #withDelimiter(String) withDelimiter},
	* {@link #withUpperCase() withUpperCase}, {@link #withLowerCase() withLowerCase},
	* {@link #withPrefix(String) withPrefix}, and {@link #withSuffix(String) withSuffix}
	* return copies of formatters with new parameters.
	*
	* @return a hexadecimal formatter with no delimiter and lowercase characters
	*/
	public static HexFormat of() {
	return HEX_FORMAT;
	}

	/**
	* Returns a hexadecimal formatter with the delimiter and lowercase characters.
	* The prefix and suffix are empty.
	* The methods {@link #withDelimiter(String) withDelimiter},
	* {@link #withUpperCase() withUpperCase}, {@link #withLowerCase() withLowerCase},
	* {@link #withPrefix(String) withPrefix}, and {@link #withSuffix(String) withSuffix}
	* return copies of formatters with new parameters.
	*
	* @param delimiter a delimiter, non-null, may be empty
	* @return a {@link HexFormat} with the delimiter and lowercase characters
	*/
	public static HexFormat ofDelimiter(String delimiter) {
	return new HexFormat(delimiter, "", "", LOWERCASE_DIGITS);
	}

	/**
	* Returns a copy of this {@code HexFormat} with the delimiter.
	* @param delimiter the delimiter, non-null, may be empty
	* @return a copy of this {@code HexFormat} with the delimiter
	*/
	public HexFormat withDelimiter(String delimiter) {
	return new HexFormat(delimiter, this.prefix, this.suffix, this.digits);
	}

	/**
	* Returns a copy of this {@code HexFormat} with the prefix.
	*
	* @param prefix a prefix, non-null, may be empty
	* @return a copy of this {@code HexFormat} with the prefix
	*/
	public HexFormat withPrefix(String prefix) {
	return new HexFormat(this.delimiter, prefix, this.suffix, this.digits);
	}

	/**
	* Returns a copy of this {@code HexFormat} with the suffix.
	*
	* @param suffix a suffix, non-null, may be empty
	* @return a copy of this {@code HexFormat} with the suffix
	*/
	public HexFormat withSuffix(String suffix) {
	return new HexFormat(this.delimiter, this.prefix, suffix, this.digits);
	}

	/**
	* Returns a copy of this {@code HexFormat} to use uppercase hexadecimal characters.
	* The uppercase hexadecimal characters are {@code "0-9", "A-F"}.
	*
	* @return a copy of this {@code HexFormat} with uppercase hexadecimal characters
	*/
	public HexFormat withUpperCase() {
	return new HexFormat(this.delimiter, this.prefix, this.suffix, UPPERCASE_DIGITS);
	}

	/**
	* Returns a copy of this {@code HexFormat} to use lowercase hexadecimal characters.
	* The lowercase hexadecimal characters are {@code "0-9", "a-f"}.
	*
	* @return a copy of this {@code HexFormat} with lowercase hexadecimal characters
	*/
	public HexFormat withLowerCase() {
	return new HexFormat(this.delimiter, this.prefix, this.suffix, LOWERCASE_DIGITS);
	}

	/**
	* Returns the delimiter between hexadecimal values in formatted hexadecimal strings.
	*
	* @return the delimiter, non-null, may be empty {@code ""}
	*/
	public String delimiter() {
	return delimiter;
	}

	/**
	* Returns the prefix used for each hexadecimal value in formatted hexadecimal strings.
	*
	* @return the prefix, non-null, may be empty {@code ""}
	*/
	public String prefix() {
	return prefix;
	}

	/**
	* Returns the suffix used for each hexadecimal value in formatted hexadecimal strings.
	*
	* @return the suffix, non-null, may be empty {@code ""}
	*/
	public String suffix() {
	return suffix;
	}

	/**
	* Returns {@code true} if the hexadecimal digits are uppercase,
	* otherwise {@code false}.
	*
	* @return {@code true} if the hexadecimal digits are uppercase,
	* otherwise {@code false}
	*/
	public boolean isUpperCase() {
	return Arrays.equals(digits, UPPERCASE_DIGITS);
	}

	/**
	* Returns a hexadecimal string formatted from a byte array.
	* Each byte value is formatted as the prefix, two hexadecimal characters
	* {@linkplain #isUpperCase selected from} uppercase or lowercase digits, and the suffix.
	* A delimiter follows each formatted value, except the last.
	*
	* The behavior is equivalent to
	* {@link #formatHex(byte[], int, int) formatHex(bytes, 0, bytes.length))}.
	*
	* @param bytes a non-null array of bytes
	* @return a string hexadecimal formatting of the byte array
	*/
	public String formatHex(byte[] bytes) {
	return formatHex(bytes, 0, bytes.length);
	}

	/**
	* Returns a hexadecimal string formatted from a byte array range.
	* Each byte value is formatted as the prefix, two hexadecimal characters
	* {@linkplain #isUpperCase selected from} uppercase or lowercase digits, and the suffix.
	* A delimiter follows each formatted value, except the last.
	*
	* @param bytes a non-null array of bytes
	* @param fromIndex the initial index of the range, inclusive
	* @param toIndex the final index of the range, exclusive
	* @return a string hexadecimal formatting each byte of the array range
	* @throws IndexOutOfBoundsException if the array range is out of bounds
	*/
	public String formatHex(byte[] bytes, int fromIndex, int toIndex) {
	Objects.requireNonNull(bytes,"bytes");
	Objects.checkFromToIndex(fromIndex, toIndex, bytes.length);
	if (toIndex - fromIndex == 0) {
	return "";
	}
	// Format efficiently if possible
	String s = formatOptDelimiter(bytes, fromIndex, toIndex);
	if (s == null) {
	long stride = prefix.length() + 2L + suffix.length() + delimiter.length();
	int capacity = checkMaxArraySize((toIndex - fromIndex) * stride - delimiter.length());
	StringBuilder sb = new StringBuilder(capacity);
	formatHex(sb, bytes, fromIndex, toIndex);
	s = sb.toString();
	}
	return s;
	}

	/**
	* Appends formatted hexadecimal strings from a byte array to the {@link Appendable}.
	* Each byte value is formatted as the prefix, two hexadecimal characters
	* {@linkplain #isUpperCase 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 {@link Appendable} methods.
	*
	* @param <A> The type of {@code Appendable}
	* @param out an {@code Appendable}, non-null
	* @param bytes a byte array
	* @return the {@code Appendable}
	* @throws UncheckedIOException if an I/O exception occurs appending to the output
	*/
	public <A extends Appendable> A formatHex(A out, byte[] bytes) {
	return formatHex(out, bytes, 0, bytes.length);
	}

	/**
	* Appends formatted hexadecimal strings from a byte array range to the {@link Appendable}.
	* Each byte value is formatted as the prefix, two hexadecimal characters
	* {@linkplain #isUpperCase 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 {@link Appendable} methods.
	*
	* @param <A> The type of {@code Appendable}
	* @param out an {@code Appendable}, non-null
	* @param bytes a byte array, non-null
	* @param fromIndex the initial index of the range, inclusive
	* @param toIndex the final index of the range, exclusive.
	* @return the {@code Appendable}
	* @throws IndexOutOfBoundsException if the array range is out of bounds
	* @throws UncheckedIOException if an I/O exception occurs appending to the output
	*/
	public <A extends Appendable> A formatHex(A out, byte[] bytes, int fromIndex, int toIndex) {
	Objects.requireNonNull(out, "out");
	Objects.requireNonNull(bytes, "bytes");
	Objects.checkFromToIndex(fromIndex, toIndex, bytes.length);

	int length = toIndex - fromIndex;
	if (length > 0) {
	try {
	String between = suffix + delimiter + prefix;
	out.append(prefix);
	toHexDigits(out, bytes[fromIndex]);
	if (between.isEmpty()) {
	for (int i = 1; i < length; i++) {
	toHexDigits(out, bytes[fromIndex + i]);
	}
	} else {
	for (int i = 1; i < length; i++) {
	out.append(between);
	toHexDigits(out, bytes[fromIndex + i]);
	}
	}
	out.append(suffix);
	} catch (IOException ioe) {
	throw new UncheckedIOException(ioe.getMessage(), ioe);
	}
	}
	return out;
	}

	/**
	* Returns a string formatting of the range of bytes optimized
	* for a single allocation.
	* Prefix and suffix must be empty and the delimiter
	* must be empty or a single byte character, otherwise null is returned.
	*
	* @param bytes the bytes, non-null
	* @param fromIndex the initial index of the range, inclusive
	* @param toIndex the final index of the range, exclusive.
	* @return a String formatted or null for non-single byte delimiter
	* or non-empty prefix or suffix
	*/
	private String formatOptDelimiter(byte[] bytes, int fromIndex, int toIndex) {
	byte[] rep;
	if (!prefix.isEmpty() \|\| !suffix.isEmpty()) {
	return null;
	}
	int length = toIndex - fromIndex;
	if (delimiter.isEmpty()) {
	// Allocate the byte array and fill in the hex pairs for each byte
	rep = new byte[checkMaxArraySize(length * 2L)];
	for (int i = 0; i < length; i++) {
	rep[i * 2] = (byte)toHighHexDigit(bytes[fromIndex + i]);
	rep[i * 2 + 1] = (byte)toLowHexDigit(bytes[fromIndex + i]);
	}
	} else if (delimiter.length() == 1 && delimiter.charAt(0) < 256) {
	// Allocate the byte array and fill in the characters for the first byte
	// Then insert the delimiter and hexadecimal characters for each of the remaining bytes
	char sep = delimiter.charAt(0);
	rep = new byte[checkMaxArraySize(length * 3L - 1L)];
	rep[0] = (byte) toHighHexDigit(bytes[fromIndex]);
	rep[1] = (byte) toLowHexDigit(bytes[fromIndex]);
	for (int i = 1; i < length; i++) {
	rep[i * 3 - 1] = (byte) sep;
	rep[i * 3 ] = (byte) toHighHexDigit(bytes[fromIndex + i]);
	rep[i * 3 + 1] = (byte) toLowHexDigit(bytes[fromIndex + i]);
	}
	} else {
	// Delimiter formatting not to a single byte
	return null;
	}
	try {
	// Return a new string using the bytes without making a copy
	return jla.newStringNoRepl(rep, StandardCharsets.ISO_8859_1);
	} catch (CharacterCodingException cce) {
	throw new AssertionError(cce);
	}
	}

	/**
	* Checked that the requested size for the result string is
	* less than or equal to the max array size.
	*
	* @param length the requested size of a byte array.
	* @return the length
	* @throws OutOfMemoryError if the size is larger than Integer.MAX_VALUE
	*/
	private static int checkMaxArraySize(long length) {
	if (length > Integer.MAX_VALUE)
	throw new OutOfMemoryError("String size " + length +
	" exceeds maximum " + Integer.MAX_VALUE);
	return (int)length;
	}

	/**
	* 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.
	*
	* @param string a string containing the byte values with prefix, hexadecimal digits, suffix,
	* and delimiters
	* @return a byte array with the values parsed from the string
	* @throws 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
	*/
	public byte[] parseHex(CharSequence string) {
	return parseHex(string, 0, string.length());
	}

	/**
	* 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.
	*
	* @param string a string range containing hexadecimal digits,
	* delimiters, prefix, and suffix.
	* @param fromIndex the initial index of the range, inclusive
	* @param toIndex the final index of the range, exclusive.
	* @return a byte array with the values parsed from the string range
	* @throws 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
	* @throws IndexOutOfBoundsException if the string range is out of bounds
	*/
	public byte[] parseHex(CharSequence string, int fromIndex, int toIndex) {
	Objects.requireNonNull(string, "string");
	Objects.checkFromToIndex(fromIndex, toIndex, string.length());

	if (fromIndex != 0 \|\| toIndex != string.length()) {
	string = string.subSequence(fromIndex, toIndex);
	}

	if (string.isEmpty())
	return EMPTY_BYTES;
	if (delimiter.isEmpty() && prefix.isEmpty() && suffix.isEmpty())
	return parseNoDelimiter(string);

	// avoid overflow for max length prefix or suffix
	long valueChars = prefix.length() + 2L + suffix.length();
	long stride = valueChars + delimiter.length();
	if ((string.length() - valueChars) % stride != 0)
	throw new IllegalArgumentException("extra or missing delimiters " +
	"or values consisting of prefix, two hexadecimal digits, and suffix");

	checkLiteral(string, 0, prefix);
	checkLiteral(string, string.length() - suffix.length(), suffix);
	String between = suffix + delimiter + prefix;
	final int len = (int)((string.length() - valueChars) / stride + 1L);
	byte[] bytes = new byte[len];
	int i, offset;
	for (i = 0, offset = prefix.length(); i < len - 1; i++, offset += 2 + between.length()) {
	bytes[i] = (byte) fromHexDigits(string, offset);
	checkLiteral(string, offset + 2, between);
	}
	bytes[i] = (byte) fromHexDigits(string, offset);

	return bytes;
	}

	/**
	* 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.
	*
	* @param chars a character array range containing an even number of hexadecimal digits,
	* delimiters, prefix, and suffix.
	* @param fromIndex the initial index of the range, inclusive
	* @param toIndex the final index of the range, exclusive.
	* @return a byte array with the values parsed from the character array range
	* @throws 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
	* @throws IndexOutOfBoundsException if the character array range is out of bounds
	*/
	public byte[] parseHex(char[] chars, int fromIndex, int toIndex) {
	Objects.requireNonNull(chars, "chars");
	Objects.checkFromToIndex(fromIndex, toIndex, chars.length);
	CharBuffer cb = CharBuffer.wrap(chars, fromIndex, toIndex - fromIndex);
	return parseHex(cb);
	}

	/**
	* Compare the literal and throw an exception if it does not match.
	* Pre-condition: {@code index + literal.length() <= string.length()}.
	*
	* @param string a CharSequence
	* @param index the index of the literal in the CharSequence
	* @param literal the expected literal
	* @throws IllegalArgumentException if the literal is not present
	*/
	private static void checkLiteral(CharSequence string, int index, String literal) {
	assert index <= string.length() - literal.length() : "pre-checked invariant error";
	if (literal.isEmpty() \|\|
	(literal.length() == 1 && literal.charAt(0) == string.charAt(index))) {
	return;
	}
	for (int i = 0; i < literal.length(); i++) {
	if (string.charAt(index + i) != literal.charAt(i)) {
	throw new IllegalArgumentException(escapeNL("found: \"" +
	string.subSequence(index, index + literal.length()) +
	"\", expected: \"" + literal + "\", index: " + index +
	" ch: " + (int)string.charAt(index + i)));
	}
	}
	}

	/**
	* Expands new line characters to escaped newlines for display.
	*
	* @param string a string
	* @return a string with newline characters escaped
	*/
	private static String escapeNL(String string) {
	return string.replace("\n", "\\n")
	.replace("\r", "\\r");
	}

	/**
	* Returns the hexadecimal character for the low 4 bits of the value considering it to be a byte.
	* If the parameter {@link #isUpperCase()} is {@code true} the
	* character returned for values {@code 10-15} is uppercase {@code "A-F"},
	* otherwise the character returned is lowercase {@code "a-f"}.
	* The values in the range {@code 0-9} are returned as {@code "0-9"}.
	*
	* @param value a value, only the low 4 bits {@code 0-3} of the value are used
	* @return the hexadecimal character for the low 4 bits {@code 0-3} of the value
	*/
	public char toLowHexDigit(int value) {
	return (char)digits[value & 0xf];
	}

	/**
	* Returns the hexadecimal character for the high 4 bits of the value considering it to be a byte.
	* If the parameter {@link #isUpperCase()} is {@code true} the
	* character returned for values {@code 10-15} is uppercase {@code "A-F"},
	* otherwise the character returned is lowercase {@code "a-f"}.
	* The values in the range {@code 0-9} are returned as {@code "0-9"}.
	*
	* @param value a value, only bits {@code 4-7} of the value are used
	* @return the hexadecimal character for the bits {@code 4-7} of the value
	*/
	public char toHighHexDigit(int value) {
	return (char)digits[(value >> 4) & 0xf];
	}

	/**
	* Appends two hexadecimal characters for the byte value to the {@link Appendable}.
	* Each nibble (4 bits) from most significant to least significant of the value
	* is formatted as if by {@link #toLowHexDigit(int) toLowHexDigit(nibble)}.
	* The hexadecimal characters are appended in one or more calls to the
	* {@link Appendable} methods. The delimiter, prefix and suffix are not used.
	*
	* @param <A> The type of {@code Appendable}
	* @param out an {@code Appendable}, non-null
	* @param value a byte value
	* @return the {@code Appendable}
	* @throws UncheckedIOException if an I/O exception occurs appending to the output
	*/
	public <A extends Appendable> A toHexDigits(A out, byte value) {
	Objects.requireNonNull(out, "out");
	try {
	out.append(toHighHexDigit(value));
	out.append(toLowHexDigit(value));
	return out;
	} catch (IOException ioe) {
	throw new UncheckedIOException(ioe.getMessage(), ioe);
	}
	}

	/**
	* Returns the two hexadecimal characters for the {@code byte} value.
	* Each nibble (4 bits) from most significant to least significant of the value
	* is formatted as if by {@link #toLowHexDigit(int) toLowHexDigit(nibble)}.
	* The delimiter, prefix and suffix are not used.
	*
	* @param value a byte value
	* @return the two hexadecimal characters for the byte value
	*/
	public String toHexDigits(byte value) {
	byte[] rep = new byte[2];
	rep[0] = (byte)toHighHexDigit(value);
	rep[1] = (byte)toLowHexDigit(value);
	try {
	return jla.newStringNoRepl(rep, StandardCharsets.ISO_8859_1);
	} catch (CharacterCodingException cce) {
	throw new AssertionError(cce);
	}
	}

	/**
	* Returns the four hexadecimal characters for the {@code char} value.
	* Each nibble (4 bits) from most significant to least significant of the value
	* is formatted as if by {@link #toLowHexDigit(int) toLowHexDigit(nibble)}.
	* The delimiter, prefix and suffix are not used.
	*
	* @param value a {@code char} value
	* @return the four hexadecimal characters for the {@code char} value
	*/
	public String toHexDigits(char value) {
	return toHexDigits((short)value);
	}

	/**
	* Returns the four hexadecimal characters for the {@code short} value.
	* Each nibble (4 bits) from most significant to least significant of the value
	* is formatted as if by {@link #toLowHexDigit(int) toLowHexDigit(nibble)}.
	* The delimiter, prefix and suffix are not used.
	*
	* @param value a {@code short} value
	* @return the four hexadecimal characters for the {@code short} value
	*/
	public String toHexDigits(short value) {
	byte[] rep = new byte[4];
	rep[0] = (byte)toHighHexDigit((byte)(value >> 8));
	rep[1] = (byte)toLowHexDigit((byte)(value >> 8));
	rep[2] = (byte)toHighHexDigit((byte)value);
	rep[3] = (byte)toLowHexDigit((byte)value);

	try {
	return jla.newStringNoRepl(rep, StandardCharsets.ISO_8859_1);
	} catch (CharacterCodingException cce) {
	throw new AssertionError(cce);
	}
	}

	/**
	* Returns the eight hexadecimal characters for the {@code int} value.
	* Each nibble (4 bits) from most significant to least significant of the value
	* is formatted as if by {@link #toLowHexDigit(int) toLowHexDigit(nibble)}.
	* The delimiter, prefix and suffix are not used.
	*
	* @param value an {@code int} value
	* @return the eight hexadecimal characters for the {@code int} value
	* @see Integer#toHexString
	*/
	public String toHexDigits(int value) {
	byte[] rep = new byte[8];
	rep[0] = (byte)toHighHexDigit((byte)(value >> 24));
	rep[1] = (byte)toLowHexDigit((byte)(value >> 24));
	rep[2] = (byte)toHighHexDigit((byte)(value >> 16));
	rep[3] = (byte)toLowHexDigit((byte)(value >> 16));
	rep[4] = (byte)toHighHexDigit((byte)(value >> 8));
	rep[5] = (byte)toLowHexDigit((byte)(value >> 8));
	rep[6] = (byte)toHighHexDigit((byte)value);
	rep[7] = (byte)toLowHexDigit((byte)value);

	try {
	return jla.newStringNoRepl(rep, StandardCharsets.ISO_8859_1);
	} catch (CharacterCodingException cce) {
	throw new AssertionError(cce);
	}
	}

	/**
	* Returns the sixteen hexadecimal characters for the {@code long} value.
	* Each nibble (4 bits) from most significant to least significant of the value
	* is formatted as if by {@link #toLowHexDigit(int) toLowHexDigit(nibble)}.
	* The delimiter, prefix and suffix are not used.
	*
	* @param value a {@code long} value
	* @return the sixteen hexadecimal characters for the {@code long} value
	* @see Long#toHexString
	*/
	public String toHexDigits(long value) {
	byte[] rep = new byte[16];
	rep[0] = (byte)toHighHexDigit((byte)(value >>> 56));
	rep[1] = (byte)toLowHexDigit((byte)(value >>> 56));
	rep[2] = (byte)toHighHexDigit((byte)(value >>> 48));
	rep[3] = (byte)toLowHexDigit((byte)(value >>> 48));
	rep[4] = (byte)toHighHexDigit((byte)(value >>> 40));
	rep[5] = (byte)toLowHexDigit((byte)(value >>> 40));
	rep[6] = (byte)toHighHexDigit((byte)(value >>> 32));
	rep[7] = (byte)toLowHexDigit((byte)(value >>> 32));
	rep[8] = (byte)toHighHexDigit((byte)(value >>> 24));
	rep[9] = (byte)toLowHexDigit((byte)(value >>> 24));
	rep[10] = (byte)toHighHexDigit((byte)(value >>> 16));
	rep[11] = (byte)toLowHexDigit((byte)(value >>> 16));
	rep[12] = (byte)toHighHexDigit((byte)(value >>> 8));
	rep[13] = (byte)toLowHexDigit((byte)(value >>> 8));
	rep[14] = (byte)toHighHexDigit((byte)value);
	rep[15] = (byte)toLowHexDigit((byte)value);

	try {
	return jla.newStringNoRepl(rep, StandardCharsets.ISO_8859_1);
	} catch (CharacterCodingException cce) {
	throw new AssertionError(cce);
	}
	}

	/**
	* Returns up to sixteen hexadecimal characters for the {@code long} value.
	* Each nibble (4 bits) from most significant to least significant of the value
	* is formatted as if by {@link #toLowHexDigit(int) toLowHexDigit(nibble)}.
	* The delimiter, prefix and suffix are not used.
	*
	* @param value a {@code long} value
	* @param digits the number of hexadecimal digits to return, 0 to 16
	* @return the hexadecimal characters for the {@code long} value
	* @throws IllegalArgumentException if {@code digits} is negative or greater than 16
	*/
	public String toHexDigits(long value, int digits) {
	if (digits < 0 \|\| digits > 16)
	throw new IllegalArgumentException("number of digits: " + digits);
	if (digits == 0)
	return "";
	byte[] rep = new byte[digits];
	for (int i = rep.length - 1; i >= 0; i--) {
	rep[i] = (byte)toLowHexDigit((byte)(value));
	value = value >>> 4;
	}
	try {
	return jla.newStringNoRepl(rep, StandardCharsets.ISO_8859_1);
	} catch (CharacterCodingException cce) {
	throw new AssertionError(cce);
	}
	}

	/**
	* Returns a byte array containing the parsed hex digits.
	* A valid string consists only of an even number of hex digits.
	*
	* @param string a string containing an even number of only hex digits
	* @return a byte array
	* @throws IllegalArgumentException if the string length is not valid or
	* the string contains non-hexadecimal characters
	*/
	private static byte[] parseNoDelimiter(CharSequence string) {
	if ((string.length() & 1) != 0)
	throw new IllegalArgumentException("string length not even: " +
	string.length());

	byte[] bytes = new byte[string.length() / 2];
	for (int i = 0; i < bytes.length; i++) {
	bytes[i] = (byte) fromHexDigits(string, i * 2);
	}

	return bytes;
	}

	/**
	* Check the number of requested digits against a limit.
	*
	* @param fromIndex the initial index of the range, inclusive
	* @param toIndex the final index of the range, exclusive.
	* @param limit the maximum allowed
	* @return the length of the range
	*/
	private static int checkDigitCount(int fromIndex, int toIndex, int limit) {
	int length = toIndex - fromIndex;
	if (length > limit)
	throw new IllegalArgumentException("string length greater than " +
	limit + ": " + length);
	return length;
	}

	/**
	* Returns {@code true} if the character is a valid hexadecimal character or codepoint.
	* The valid hexadecimal characters are:
	* <ul>
	* <li>{@code '0' ('\u005Cu0030')} through {@code '9' ('\u005Cu0039')} inclusive,
	* <li>{@code 'A' ('\u005Cu0041')} through {@code 'F' ('\u005Cu0046')} inclusive, and
	* <li>{@code 'a' ('\u005Cu0061')} through {@code 'f' ('\u005Cu0066')} inclusive.
	* </ul>
	* @param ch a codepoint
	* @return {@code true} if the character is valid a hexadecimal character,
	* otherwise {@code false}
	*/
	public static boolean isHexDigit(int ch) {
	return ((ch >>> 8) == 0 && DIGITS[ch] >= 0);
	}

	/**
	* Returns the value for the hexadecimal character or codepoint.
	* The value is:
	* <ul>
	* <li>{@code (ch - '0')} for {@code '0'} through {@code '9'} inclusive,
	* <li>{@code (ch - 'A' + 10)} for {@code 'A'} through {@code 'F'} inclusive, and
	* <li>{@code (ch - 'a' + 10)} for {@code 'a'} through {@code 'f'} inclusive.
	* </ul>
	*
	* @param ch a character or codepoint
	* @return the value {@code 0-15}
	* @throws NumberFormatException if the codepoint is not a hexadecimal character
	*/
	public static int fromHexDigit(int ch) {
	int value;
	if ((ch >>> 8) == 0 && (value = DIGITS[ch]) >= 0) {
	return value;
	}
	throw new NumberFormatException("not a hexadecimal digit: \"" + (char) ch + "\" = " + ch);
	}

	/**
	* Returns a value parsed from two hexadecimal characters in a string.
	* The characters in the range from {@code index} to {@code index + 1},
	* inclusive, must be valid hex digits according to {@link #fromHexDigit(int)}.
	*
	* @param string a CharSequence containing the characters
	* @param index the index of the first character of the range
	* @return the value parsed from the string range
	* @throws NumberFormatException if any of the characters in the range
	* is not a hexadecimal character
	* @throws IndexOutOfBoundsException if the range is out of bounds
	* for the {@code CharSequence}
	*/
	private static int fromHexDigits(CharSequence string, int index) {
	int high = fromHexDigit(string.charAt(index));
	int low = fromHexDigit(string.charAt(index + 1));
	return (high << 4) \| low;
	}

	/**
	* Returns the {@code int} value parsed from a string of up to eight hexadecimal characters.
	* The hexadecimal characters are parsed from most significant to least significant
	* using {@link #fromHexDigit(int)} to form an unsigned value.
	* The value is zero extended to 32 bits and is returned as an {@code int}.
	*
	* @apiNote
	* {@link Integer#parseInt(String, int) Integer.parseInt(s, 16)} and
	* {@link Integer#parseUnsignedInt(String, int) Integer.parseUnsignedInt(s, 16)}
	* are similar but allow all Unicode hexadecimal digits defined by
	* {@link Character#digit(char, int) Character.digit(ch, 16)}.
	* {@code HexFormat} uses only hexadecimal characters
	* {@code "0-9"}, {@code "A-F"} and {@code "a-f"}.
	* Signed hexadecimal strings can be parsed with {@link Integer#parseInt(String, int)}.
	*
	* @param string a CharSequence containing up to eight hexadecimal characters
	* @return the value parsed from the string
	* @throws IllegalArgumentException if the string length is greater than eight (8) or
	* if any of the characters is not a hexadecimal character
	*/
	public static int fromHexDigits(CharSequence string) {
	return fromHexDigits(string, 0, string.length());
	}

	/**
	* Returns the {@code int} value parsed from a string range of up to eight hexadecimal
	* characters.
	* The characters in the range {@code fromIndex} to {@code toIndex}, exclusive,
	* are parsed from most significant to least significant
	* using {@link #fromHexDigit(int)} to form an unsigned value.
	* The value is zero extended to 32 bits and is returned as an {@code int}.
	*
	* @apiNote
	* {@link Integer#parseInt(String, int) Integer.parseInt(s, 16)} and
	* {@link Integer#parseUnsignedInt(String, int) Integer.parseUnsignedInt(s, 16)}
	* are similar but allow all Unicode hexadecimal digits defined by
	* {@link Character#digit(char, int) Character.digit(ch, 16)}.
	* {@code HexFormat} uses only hexadecimal characters
	* {@code "0-9"}, {@code "A-F"} and {@code "a-f"}.
	* Signed hexadecimal strings can be parsed with {@link Integer#parseInt(String, int)}.
	*
	* @param string a CharSequence containing the characters
	* @param fromIndex the initial index of the range, inclusive
	* @param toIndex the final index of the range, exclusive.
	* @return the value parsed from the string range
	* @throws IndexOutOfBoundsException if the range is out of bounds
	* for the {@code CharSequence}
	* @throws IllegalArgumentException if length of the range is greater than eight (8) or
	* if any of the characters is not a hexadecimal character
	*/
	public static int fromHexDigits(CharSequence string, int fromIndex, int toIndex) {
	Objects.requireNonNull(string, "string");
	Objects.checkFromToIndex(fromIndex, toIndex, string.length());
	int length = checkDigitCount(fromIndex, toIndex, 8);
	int value = 0;
	for (int i = 0; i < length; i++) {
	value = (value << 4) + fromHexDigit(string.charAt(fromIndex + i));
	}
	return value;
	}

	/**
	* 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 {@link #fromHexDigit(int)} to form an unsigned value.
	* The value is zero extended to 64 bits and is returned as a {@code long}.
	*
	* @apiNote
	* {@link Long#parseLong(String, int) Long.parseLong(s, 16)} and
	* {@link Long#parseUnsignedLong(String, int) Long.parseUnsignedLong(s, 16)}
	* are similar but allow all Unicode hexadecimal digits defined by
	* {@link Character#digit(char, int) Character.digit(ch, 16)}.
	* {@code HexFormat} uses only hexadecimal characters
	* {@code "0-9"}, {@code "A-F"} and {@code "a-f"}.
	* Signed hexadecimal strings can be parsed with {@link Long#parseLong(String, int)}.
	*
	* @param string a CharSequence containing up to sixteen hexadecimal characters
	* @return the value parsed from the string
	* @throws IllegalArgumentException if the string length is greater than sixteen (16) or
	* if any of the characters is not a hexadecimal character
	*/
	public static long fromHexDigitsToLong(CharSequence string) {
	return fromHexDigitsToLong(string, 0, string.length());
	}

	/**
	* Returns the long value parsed from a string range of up to sixteen hexadecimal
	* characters.
	* The characters in the range {@code fromIndex} to {@code toIndex}, exclusive,
	* are parsed from most significant to least significant
	* using {@link #fromHexDigit(int)} to form an unsigned value.
	* The value is zero extended to 64 bits and is returned as a {@code long}.
	*
	* @apiNote
	* {@link Long#parseLong(String, int) Long.parseLong(s, 16)} and
	* {@link Long#parseUnsignedLong(String, int) Long.parseUnsignedLong(s, 16)}
	* are similar but allow all Unicode hexadecimal digits defined by
	* {@link Character#digit(char, int) Character.digit(ch, 16)}.
	* {@code HexFormat} uses only hexadecimal characters
	* {@code "0-9"}, {@code "A-F"} and {@code "a-f"}.
	* Signed hexadecimal strings can be parsed with {@link Long#parseLong(String, int)}.
	*
	* @param string a CharSequence containing the characters
	* @param fromIndex the initial index of the range, inclusive
	* @param toIndex the final index of the range, exclusive.
	* @return the value parsed from the string range
	* @throws IndexOutOfBoundsException if the range is out of bounds
	* for the {@code CharSequence}
	* @throws IllegalArgumentException if the length of the range is greater than sixteen (16) or
	* if any of the characters is not a hexadecimal character
	*/
	public static long fromHexDigitsToLong(CharSequence string, int fromIndex, int toIndex) {
	Objects.requireNonNull(string, "string");
	Objects.checkFromToIndex(fromIndex, toIndex, string.length());
	int length = checkDigitCount(fromIndex, toIndex, 16);
	long value = 0L;
	for (int i = 0; i < length; i++) {
	value = (value << 4) + fromHexDigit(string.charAt(fromIndex + i));
	}
	return value;
	}

	/**
	* Returns {@code true} if the other object is a {@code HexFormat}
	* with the same parameters.
	*
	* @param o an object, may be null
	* @return {@code true} if the other object is a {@code HexFormat} and the parameters
	* uppercase, delimiter, prefix, and suffix are equal;
	* otherwise {@code false}
	*/
	@Override
	public boolean equals(Object o) {
	if (this == o)
	return true;
	if (o == null \|\| getClass() != o.getClass())
	return false;
	HexFormat otherHex = (HexFormat) o;
	return Arrays.equals(digits, otherHex.digits) &&
	delimiter.equals(otherHex.delimiter) &&
	prefix.equals(otherHex.prefix) &&
	suffix.equals(otherHex.suffix);
	}

	/**
	* Returns a hashcode for this {@code HexFormat}.
	*
	* @return a hashcode for this {@code HexFormat}
	*/
	@Override
	public int hashCode() {
	int result = Objects.hash(delimiter, prefix, suffix);
	result = 31 * result + Boolean.hashCode(Arrays.equals(digits, UPPERCASE_DIGITS));
	return result;
	}

	/**
	* Returns a description of the formatter parameters for uppercase,
	* delimiter, prefix, and suffix.
	*
	* @return a description of this {@code HexFormat}
	*/
	@Override
	public String toString() {
	return escapeNL("uppercase: " + Arrays.equals(digits, UPPERCASE_DIGITS) +
	", delimiter: \"" + delimiter +
	"\", prefix: \"" + prefix +
	"\", suffix: \"" + suffix + "\"");
	}
	}

Back to index...