Java : HexFormat - API使用例

HexFormat (Java SE 18 & JDK 18) の使用例まとめです。
だいたいのメソッドを網羅済みです。
API仕様のおともにどうぞ。

概要

HexFormatは、バイトと文字、および16進エンコード文字列間で変換します。これには、プレフィクス、サフィクス、デリミタなどの追加形式のマークアップを含めることができます。

クラス構成

HexFormat クラスには、16進数に特化した、文字列と数値の変換用メソッドがそろっています。

final var hex = HexFormat.of();

final byte value1 = 127;
final var ret1 = hex.toHexDigits(value1);
System.out.println(ret1); // 7f

final short value2 = 0x1ab;
final var ret2 = hex.toHexDigits(value2);
System.out.println(ret2); // 01ab

final int value3 = -1;
final var ret3 = hex.toHexDigits(value3);
System.out.println(ret3); // ffffffff

final byte[] bytes = {10, 11, 12, 13, 14, 15, 16};

final var hex = HexFormat.ofDelimiter(", ");
final var ret1 = hex.formatHex(bytes);
System.out.println(ret1); // 0a, 0b, 0c, 0d, 0e, 0f, 10

final var prefixHex = hex.withPrefix("0x");
final var ret2 = prefixHex.formatHex(bytes);
System.out.println(ret2); // 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10

関連記事：文字列と数値の変換

メソッド

String delimiter ()

書式設定された16進数の文字列間のデリミタを返します。

final byte[] bytes = {1, 2, 3, 10, 11, 12};

final var hex1 = HexFormat.of();
System.out.println(hex1.delimiter().isEmpty()); // true
System.out.println(hex1.formatHex(bytes)); // 0102030a0b0c

final var hex2 = HexFormat.ofDelimiter("-");
System.out.println(hex2.delimiter()); // -
System.out.println(hex2.formatHex(bytes)); // 01-02-03-0a-0b-0c

boolean equals (Object o)

他のオブジェクトが同じパラメータを持つHexFormatである場合、trueを返します。

final var hex1 = HexFormat.of();
final var hex2 = HexFormat.ofDelimiter("-");

System.out.println(hex1.equals(hex2)); // false

final var hex3 = hex1.withDelimiter("-");

System.out.println(hex1.equals(hex3)); // false
System.out.println(hex2.equals(hex3)); // true

String formatHex (byte[] bytes)

バイト配列からフォーマットされた16進文字列を返します。

final byte[] bytes = {10, 11, 12, 13, 14, 15, 16};

final var hex = HexFormat.ofDelimiter(", ");
final var ret = hex.formatHex(bytes);
System.out.println(ret); // 0a, 0b, 0c, 0d, 0e, 0f, 10

final var prefixHex = hex.withPrefix("0x");
final var ret2 = prefixHex.formatHex(bytes);
System.out.println(ret2); // 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10

String formatHex (byte[] bytes, int fromIndex, int toIndex)

バイト配列範囲からフォーマットされた16進文字列を返します。

formatHex(byte[] bytes) の使用例もご参照ください。

final byte[] bytes = {1, 2, 3, 4};
final var hex = HexFormat.ofDelimiter(", ").withPrefix("0x");

System.out.println(hex.formatHex(bytes, 0, 0).isEmpty()); // true
System.out.println(hex.formatHex(bytes, 0, 1)); // 0x01
System.out.println(hex.formatHex(bytes, 0, 2)); // 0x01, 0x02
System.out.println(hex.formatHex(bytes, 0, 3)); // 0x01, 0x02, 0x03

System.out.println(hex.formatHex(bytes, 0, 3)); // 0x01, 0x02, 0x03
System.out.println(hex.formatHex(bytes, 1, 3)); // 0x02, 0x03
System.out.println(hex.formatHex(bytes, 2, 3)); // 0x03
System.out.println(hex.formatHex(bytes, 3, 3).isEmpty()); // true

<A extends Appendable> A formatHex (A out, byte[] bytes)

バイト配列からAppendableに書式設定された16進文字列を追加します。

final var hex = HexFormat.ofDelimiter(", ");
final var sb = new StringBuilder();

final byte[] bytes1 = {1, 2, 3};
final var ret1 = hex.formatHex(sb, bytes1);
System.out.println(ret1); // 01, 02, 03

sb.append(" - ");

final byte[] bytes2 = {10, 11, 12};
final var ret2 = hex.formatHex(sb, bytes2);
System.out.println(ret2); // 01, 02, 03 - 0a, 0b, 0c

System.out.println(sb); // 01, 02, 03 - 0a, 0b, 0c

<A extends Appendable> A formatHex (A out, byte[] bytes, int fromIndex, int toIndex)

バイト配列範囲からAppendableに書式設定された16進文字列を追加します。

formatHex(A out, byte[] bytes) の使用例もご参照ください。

final byte[] bytes = {1, 2, 3, 4};
final var hex = HexFormat.ofDelimiter(", ").withPrefix("0x");

System.out.println(hex.formatHex(new StringBuilder(), bytes, 0, 0).isEmpty()); // true
System.out.println(hex.formatHex(new StringBuilder(), bytes, 0, 1)); // 0x01
System.out.println(hex.formatHex(new StringBuilder(), bytes, 0, 2)); // 0x01, 0x02
System.out.println(hex.formatHex(new StringBuilder(), bytes, 0, 3)); // 0x01, 0x02, 0x03

System.out.println(hex.formatHex(new StringBuilder(), bytes, 0, 3)); // 0x01, 0x02, 0x03
System.out.println(hex.formatHex(new StringBuilder(), bytes, 1, 3)); // 0x02, 0x03
System.out.println(hex.formatHex(new StringBuilder(), bytes, 2, 3)); // 0x03
System.out.println(hex.formatHex(new StringBuilder(), bytes, 3, 3).isEmpty()); // true

static int fromHexDigit (int ch)

16進文字またはコード・ポイントの値を返します。

final var ret1 = HexFormat.fromHexDigit('0');
System.out.println(ret1); // 0

final var ret2 = HexFormat.fromHexDigit('A');
System.out.println(ret2); // 10

final var ret3 = HexFormat.fromHexDigit('f');
System.out.println(ret3); // 15

try {
    final var ret4 = HexFormat.fromHexDigit('G');
} catch (NumberFormatException e) {
    System.out.println(e);

    // 結果
    // ↓
    //java.lang.NumberFormatException: not a hexadecimal digit: "G" = 71
}

static int fromHexDigits (CharSequence string)

最大8個の16進数の文字列から解析されたint値を返します。

final var ret1 = HexFormat.fromHexDigits("10");
System.out.println(ret1); // 16

final var ret2 = HexFormat.fromHexDigits("ffff");
System.out.println(ret2); // 65535

final var ret3 = HexFormat.fromHexDigits("123ABC");
System.out.println(ret3); // 1194684

final var ret4 = HexFormat.fromHexDigits("ffffffff");
System.out.println(ret4); // -1

try {
    final var ret5 = HexFormat.fromHexDigits("123456789");
} catch (IllegalArgumentException e) {
    System.out.println(e);

    // 結果
    // ↓
    //java.lang.IllegalArgumentException: string length greater than 8: 9
}

static int fromHexDigits (CharSequence string, int fromIndex, int toIndex)

最大8個の16進数の文字列範囲から解析されたint値を返します。

fromHexDigits(CharSequence string) の使用例もご参照ください。

final var str = "1234ffff";

System.out.println(str.substring(0, 2)); // 12
System.out.println(HexFormat.fromHexDigits(str, 0, 2)); // 18

System.out.println(str.substring(0, 4)); // 1234
System.out.println(HexFormat.fromHexDigits(str, 0, 4)); // 4660

System.out.println(str.substring(4, 6)); // ff
System.out.println(HexFormat.fromHexDigits(str, 4, 6)); // 255

System.out.println(str.substring(4, 8)); // ffff
System.out.println(HexFormat.fromHexDigits(str, 4, 8)); // 65535

static long fromHexDigitsToLong (CharSequence string)

最大16進数の文字列から解析された長い値を返します。

型が違うこと以外は、fromHexDigits(CharSequence string) と使い方は同じです。
API使用例はそちらをご参照ください。

static long fromHexDigitsToLong (CharSequence string, int fromIndex, int toIndex)

最大16進数の文字列範囲から解析された長い値を返します。

型が違うこと以外は、fromHexDigits(CharSequence string, int fromIndex, int toIndex) と使い方は同じです。
API使用例はそちらをご参照ください。

int hashCode ()

このHexFormatのハッシュ・コードを返します。

final var ret1 = HexFormat.of().hashCode();
System.out.println(ret1); // 924758

final var ret2 = HexFormat.ofDelimiter(",").hashCode();
System.out.println(ret2); // 2235562

final var ret3 = HexFormat.of().withPrefix("abc").hashCode();
System.out.println(ret3); // 93520952

static boolean isHexDigit (int ch)

文字が有効な16進文字またはコード・ポイントである場合、trueを返します。

System.out.println(HexFormat.isHexDigit('0')); // true
System.out.println(HexFormat.isHexDigit('1')); // true
System.out.println(HexFormat.isHexDigit('2')); // true

System.out.println(HexFormat.isHexDigit('a')); // true
System.out.println(HexFormat.isHexDigit('b')); // true
System.out.println(HexFormat.isHexDigit('c')); // true

System.out.println(HexFormat.isHexDigit('D')); // true
System.out.println(HexFormat.isHexDigit('E')); // true
System.out.println(HexFormat.isHexDigit('F')); // true

System.out.println(HexFormat.isHexDigit('g')); // false
System.out.println(HexFormat.isHexDigit('+')); // false
System.out.println(HexFormat.isHexDigit('-')); // false

boolean isUpperCase ()

16進数が大文字の場合はtrue、それ以外の場合はfalseを返します。

final var hex = HexFormat.of();

System.out.println(hex.isUpperCase()); // false
System.out.println(hex.toHexDigits(0x123abcd)); // 0123abcd

final var upperCaseHex = hex.withUpperCase();

System.out.println(upperCaseHex.isUpperCase()); // true
System.out.println(upperCaseHex.toHexDigits(0x123abcd)); // 0123ABCD

static HexFormat of ()

デリミタと小文字を含まない16進数のフォーマッタを返します。

final var hex = HexFormat.of();

// uppercase: false, delimiter: "", prefix: "", suffix: ""
System.out.println(hex);

final int value = 0x123abcd;
System.out.println(hex.toHexDigits(value)); // 0123abcd

final byte[] bytes = {1, 2, 3, 4, 5};
System.out.println(hex.formatHex(bytes)); // 0102030405

static HexFormat ofDelimiter (String delimiter)

デリミタと小文字を含む16進数のフォーマッタを返します。

final var hex = HexFormat.ofDelimiter("-");

// uppercase: false, delimiter: "-", prefix: "", suffix: ""
System.out.println(hex);

final int value = 0x123abcd;
System.out.println(hex.toHexDigits(value)); // 0123abcd

final byte[] bytes = {1, 2, 3, 4, 5};
System.out.println(hex.formatHex(bytes)); // 01-02-03-04-05

byte[] parseHex (char[] chars, int fromIndex, int toIndex)

文字配列の範囲から解析された16進数値を含むバイト配列を返します。

parseHex(CharSequence string) の使用例もご参照ください。

final var hex = HexFormat.of();
final char[] chars = {'0', '1', '0', '2', '0', '3'};

final var ret1 = hex.parseHex(chars, 0, 2);
System.out.println(Arrays.toString(ret1)); // [1]

final var ret2 = hex.parseHex(chars, 0, 4);
System.out.println(Arrays.toString(ret2)); // [1, 2]

final var ret3 = hex.parseHex(chars, 0, 6);
System.out.println(Arrays.toString(ret3)); // [1, 2, 3]

final var ret4 = hex.parseHex(chars, 2, 6);
System.out.println(Arrays.toString(ret4)); // [2, 3]

final var ret5 = hex.parseHex(chars, 4, 6);
System.out.println(Arrays.toString(ret5)); // [3]

byte[] parseHex (CharSequence string)

文字列から解析された16進数値を含むバイト配列を返します。

final var hex = HexFormat.of();

final var ret1 = hex.parseHex("010203");
System.out.println(Arrays.toString(ret1)); // [1, 2, 3]

final var ret2 = hex.parseHex("0a0b0c");
System.out.println(Arrays.toString(ret2)); // [10, 11, 12]

final var ret3 = hex.parseHex("101112");
System.out.println(Arrays.toString(ret3)); // [16, 17, 18]

final var ret4 = hex.parseHex("fffefd");
System.out.println(Arrays.toString(ret4)); // [-1, -2, -3]

final var hex1 = HexFormat.ofDelimiter(",");

final var ret1 = hex1.parseHex("01,02,03");
System.out.println(Arrays.toString(ret1)); // [1, 2, 3]

final var hex2 = hex1.withPrefix("0x");

final var ret2 = hex2.parseHex("0x0a,0x0b,0x0c");
System.out.println(Arrays.toString(ret2)); // [10, 11, 12]

byte[] parseHex (CharSequence string, int fromIndex, int toIndex)

文字列の範囲から解析された16進数値を含むバイト配列を返します。

parseHex(CharSequence string) の使用例もご参照ください。

final var hex = HexFormat.of();
final var str = "010203";

final var ret1 = hex.parseHex(str, 0, 2);
System.out.println(Arrays.toString(ret1)); // [1]

final var ret2 = hex.parseHex(str, 0, 4);
System.out.println(Arrays.toString(ret2)); // [1, 2]

final var ret3 = hex.parseHex(str, 0, 6);
System.out.println(Arrays.toString(ret3)); // [1, 2, 3]

final var ret4 = hex.parseHex(str, 2, 6);
System.out.println(Arrays.toString(ret4)); // [2, 3]

final var ret5 = hex.parseHex(str, 4, 6);
System.out.println(Arrays.toString(ret5)); // [3]

String prefix ()

書式設定された16進数の文字列の各値に使用されるプレフィクスを返します。

final byte[] bytes = {1, 2, 3, 10, 11, 12};

final var hex = HexFormat.ofDelimiter(", ");
System.out.println(hex.prefix().isEmpty()); // true

System.out.println(hex.formatHex(bytes)); // 01, 02, 03, 0a, 0b, 0c

final var prefixHex = hex.withPrefix("0x");
System.out.println(prefixHex.prefix()); // 0x

System.out.println(prefixHex.formatHex(bytes)); // 0x01, 0x02, 0x03, 0x0a, 0x0b, 0x0c

String suffix ()

書式設定された16進数の文字列の各値に使用されるサフィクスを返します。

final byte[] bytes = {1, 2, 3, 10, 11, 12};

final var hex = HexFormat.ofDelimiter(", ");
System.out.println(hex.suffix().isEmpty()); // true

System.out.println(hex.formatHex(bytes)); // 01, 02, 03, 0a, 0b, 0c

final var suffixHex = hex.withSuffix("KB");
System.out.println(suffixHex.suffix()); // KB

System.out.println(suffixHex.formatHex(bytes)); // 01KB, 02KB, 03KB, 0aKB, 0bKB, 0cKB

String toHexDigits (byte value)

byte値の2つの16進文字を返します。

final var hex = HexFormat.of();

final byte value1 = 1;
System.out.println(hex.toHexDigits(value1)); // 01

final byte value2 = 10;
System.out.println(hex.toHexDigits(value2)); // 0a

final byte value3 = 16;
System.out.println(hex.toHexDigits(value3)); // 10

final byte value4 = 127;
System.out.println(hex.toHexDigits(value4)); // 7f

final byte value5 = -1;
System.out.println(hex.toHexDigits(value5)); // ff

String toHexDigits (char value)

char値の4つの16進文字を返します。

final var hex = HexFormat.of();

final char value1 = 1;
System.out.println(hex.toHexDigits(value1)); // 0001

final char value2 = 10;
System.out.println(hex.toHexDigits(value2)); // 000a

final char value3 = 16;
System.out.println(hex.toHexDigits(value3)); // 0010

final char value4 = 127;
System.out.println(hex.toHexDigits(value4)); // 007f

final char value5 = 0x12ab;
System.out.println(hex.toHexDigits(value5)); // 12ab

final char value6 = 0xffff;
System.out.println(hex.toHexDigits(value6)); // ffff

String toHexDigits (int value)

int値の8つの16進文字を返します。

final var hex = HexFormat.of();

final int value1 = 1;
System.out.println(hex.toHexDigits(value1)); // 00000001

final int value2 = 10;
System.out.println(hex.toHexDigits(value2)); // 0000000a

final int value3 = 16;
System.out.println(hex.toHexDigits(value3)); // 00000010

final int value4 = 127;
System.out.println(hex.toHexDigits(value4)); // 0000007f

final int value5 = 0x1234abcd;
System.out.println(hex.toHexDigits(value5)); // 1234abcd

final int value6 = -1;
System.out.println(hex.toHexDigits(value6)); // ffffffff

String toHexDigits (long value)

long値の16進数の文字を返します。

final var hex = HexFormat.of();

final long value1 = 1L;
System.out.println(hex.toHexDigits(value1)); // 0000000000000001

final long value2 = 10L;
System.out.println(hex.toHexDigits(value2)); // 000000000000000a

final long value3 = 16L;
System.out.println(hex.toHexDigits(value3)); // 0000000000000010

final long value4 = 127L;
System.out.println(hex.toHexDigits(value4)); // 000000000000007f

final long value5 = 0x1234567890abcdefL;
System.out.println(hex.toHexDigits(value5)); // 1234567890abcdef

final long value6 = -1L;
System.out.println(hex.toHexDigits(value6)); // ffffffffffffffff

String toHexDigits (long value, int digits)

long値の最大16進文字を返します。

toHexDigits(long value) の使用例もご参照ください。

final var hex = HexFormat.of();
final long value = 0x1234567890abcdefL;

System.out.println(hex.toHexDigits(value, 0).isEmpty()); // true
System.out.println(hex.toHexDigits(value, 1)); // f
System.out.println(hex.toHexDigits(value, 2)); // ef
System.out.println(hex.toHexDigits(value, 3)); // def

System.out.println(hex.toHexDigits(value, 7)); // 0abcdef
System.out.println(hex.toHexDigits(value, 8)); // 90abcdef
System.out.println(hex.toHexDigits(value, 9)); // 890abcdef

System.out.println(hex.toHexDigits(value, 14)); // 34567890abcdef
System.out.println(hex.toHexDigits(value, 15)); // 234567890abcdef
System.out.println(hex.toHexDigits(value, 16)); // 1234567890abcdef

String toHexDigits (short value)

short値の4つの16進文字を返します。

final var hex = HexFormat.of();

final short value1 = 1;
System.out.println(hex.toHexDigits(value1)); // 0001

final short value2 = 10;
System.out.println(hex.toHexDigits(value2)); // 000a

final short value3 = 16;
System.out.println(hex.toHexDigits(value3)); // 0010

final short value4 = 127;
System.out.println(hex.toHexDigits(value4)); // 007f

final short value5 = 0x12ab;
System.out.println(hex.toHexDigits(value5)); // 12ab

final short value6 = -1;
System.out.println(hex.toHexDigits(value6)); // ffff

<A extends Appendable> A toHexDigits (A out, byte value)

バイト値の2つの16進文字をAppendableに追加します。

final var hex = HexFormat.of();
final var out = new StringBuilder();

final byte value1 = 1;
final var ret1 = hex.toHexDigits(out, value1);
System.out.println(ret1); // 01

final byte value2 = 2;
final var ret2 = hex.toHexDigits(out, value2);
System.out.println(ret2); // 0102

final byte value3 = 10;
final var ret3 = hex.toHexDigits(out, value3);
System.out.println(ret3); // 01020a

final byte value4 = 11;
final var ret4 = hex.toHexDigits(out, value4);
System.out.println(ret4); // 01020a0b

System.out.println(out); // 01020a0b

char toHighHexDigit (int value)

値をバイトとみなす値の高い4ビットの16進文字を返します。

final var hex = HexFormat.of();

System.out.println(hex.toHighHexDigit(0x00)); // 0
System.out.println(hex.toHighHexDigit(0x10)); // 1
System.out.println(hex.toHighHexDigit(0x20)); // 2

System.out.println(hex.toHighHexDigit(0xa0)); // a
System.out.println(hex.toHighHexDigit(0xb0)); // b
System.out.println(hex.toHighHexDigit(0xc0)); // c

System.out.println(hex.toHighHexDigit(0x0f)); // 0
System.out.println(hex.toHighHexDigit(0x10)); // 1
System.out.println(hex.toHighHexDigit(0x11)); // 1
System.out.println(hex.toHighHexDigit(0xff)); // f

char toLowHexDigit (int value)

値をバイトとみなす値の低い4ビットの16進文字を返します。

final var hex = HexFormat.of();

System.out.println(hex.toLowHexDigit(0x00)); // 0
System.out.println(hex.toLowHexDigit(0x01)); // 1
System.out.println(hex.toLowHexDigit(0x02)); // 2

System.out.println(hex.toLowHexDigit(0x0a)); // a
System.out.println(hex.toLowHexDigit(0x0b)); // b
System.out.println(hex.toLowHexDigit(0x0c)); // c

System.out.println(hex.toLowHexDigit(0x0f)); // f
System.out.println(hex.toLowHexDigit(0x10)); // 0
System.out.println(hex.toLowHexDigit(0x11)); // 1
System.out.println(hex.toLowHexDigit(0xff)); // f

String toString ()

大文字、デリミタ、プレフィクスおよびサフィクスのフォーマッタ・パラメータの説明を返します。

final var ret1 = HexFormat.of().toString();
System.out.println(ret1); // uppercase: false, delimiter: "", prefix: "", suffix: ""

final var ret2 = HexFormat.ofDelimiter("-").toString();
System.out.println(ret2); // uppercase: false, delimiter: "-", prefix: "", suffix: ""

final var ret3 = HexFormat.of().withUpperCase().toString();
System.out.println(ret3); // uppercase: true, delimiter: "", prefix: "", suffix: ""

final var ret4 = HexFormat.of().withPrefix("abc").withSuffix("XYZ").toString();
System.out.println(ret4); // uppercase: false, delimiter: "", prefix: "abc", suffix: "XYZ"

HexFormat withDelimiter (String delimiter)

このHexFormatのコピーをデリミタとともに返します。

final byte[] bytes = {1, 2, 3, 10, 11, 12};

final var hex1 = HexFormat.of();
final var ret1 = hex1.formatHex(bytes);
System.out.println(ret1); // 0102030a0b0c

final var hex2 = hex1.withDelimiter(", ");
final var ret2 = hex2.formatHex(bytes);
System.out.println(ret2); // 01, 02, 03, 0a, 0b, 0c

final var hex3 = hex1.withDelimiter("-");
final var ret3 = hex3.formatHex(bytes);
System.out.println(ret3); // 01-02-03-0a-0b-0c

HexFormat withLowerCase ()

小文字16進文字を使用するために、このHexFormatのコピーを返します。

final var hex = HexFormat.of();

System.out.println(hex.isUpperCase()); // false
System.out.println(hex.toHexDigits(0x123abcd)); // 0123abcd

final var upperCaseHex = hex.withUpperCase();

System.out.println(upperCaseHex.isUpperCase()); // true
System.out.println(upperCaseHex.toHexDigits(0x123abcd)); // 0123ABCD

final var lowerCaseHex = upperCaseHex.withLowerCase();
System.out.println(lowerCaseHex.isUpperCase()); // false
System.out.println(lowerCaseHex.toHexDigits(0x123abcd)); // 0123abcd

HexFormat withPrefix (String prefix)

このHexFormatのコピーをプレフィクスとともに返します。

このメソッドの使用例は、prefix() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

HexFormat withSuffix (String suffix)

このHexFormatのコピーをサフィクスとともに返します。

このメソッドの使用例は、suffix() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

HexFormat withUpperCase ()

このHexFormatのコピーを返し、大文字の16進文字を使用します。

このメソッドの使用例は、isUpperCase() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

文字列と数値の変換

API 使用例