Add HexUtil class with HEX helper functions

Author: Artem Labazin

CHANGELOG.md

@@ -12,6 +12,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Add more tests.
 - Add `JavaDoc`.
 
+## [1.16.0](https://github.com/appulse-projects/utils-java/releases/tag/1.16.0) - 2019-04-24
+
+### Added
+
+- `HexUtil` class with HEX helper functions.
+
 ## [1.15.1](https://github.com/appulse-projects/utils-java/releases/tag/1.15.1) - 2019-04-23
 
 ### Added

pom.xml

@@ -24,7 +24,7 @@ limitations under the License.
 
   <groupId>io.appulse</groupId>
   <artifactId>utils-java</artifactId>
-  <version>1.15.1</version>
+  <version>1.16.0</version>
   <packaging>jar</packaging>
 
   <properties>
@@ -66,7 +66,7 @@ limitations under the License.
     <url>https://github.com/appulse-projects/utils-java</url>
     <connection>scm:git:https://github.com/appulse-projects/utils-java.git</connection>
     <developerConnection>scm:git:https://github.com/appulse-projects/utils-java.git</developerConnection>
-    <tag>1.15.1</tag>
+    <tag>1.16.0</tag>
   </scm>
 
   <distributionManagement>

src/main/java/io/appulse/utils/HexUtil.java

@@ -0,0 +1,156 @@
+/*
+ * Copyright 2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appulse.utils;
+
+import static java.util.Locale.ENGLISH;
+
+import java.util.Formatter;
+import java.util.FormatterClosedException;
+import java.util.IllegalFormatException;
+
+import lombok.NonNull;
+import lombok.val;
+
+/**
+ * The set of different HEX helper funtions.
+ *
+ * @author Artem Labazin
+ * @since 1.16.0
+ */
+public final class HexUtil {
+
+  private static final String NEW_LINE;
+
+  static {
+    String newLine;
+    try (Formatter formatter = new Formatter()) {
+      newLine = formatter.format("%n").toString();
+    } catch (IllegalFormatException | FormatterClosedException ex) {
+      newLine = "\n"; // Whaaaaaat?
+    }
+    NEW_LINE = newLine;
+  }
+
+  /**
+   * Converts an integer value into two-chars string with leading 0.
+   *
+   * @param value the value to convert
+   *
+   * @return the result string
+   */
+  public static String byteToHex (int value) {
+    return String.format(ENGLISH, "%02x", value);
+  }
+
+  /**
+   * Converts an integer value into char.
+   *
+   * @param value the value to convert
+   *
+   * @return the value's {@code char} representation
+   */
+  public static char byteToChar (int value) {
+    return value <= 0x1F || value >= 0x7F
+           ? '.'
+           : (char) value;
+  }
+
+  /**
+   * Returns a multi-line hexadecimal dump of the specified byte array that is easy to read by humans.
+   *
+   * @param bytes the byte array to dump
+   *
+   * @return the human-readable multi-line hexadecimal dump
+   */
+  public static String prettyHexDump (@NonNull byte[] bytes) {
+    val buffer = Bytes.wrap(bytes);
+    return prettyHexDump(buffer);
+  }
+
+  /**
+   * Returns a multi-line hexadecimal dump of the specified {@link Bytes} that is easy to read by humans.
+   *
+   * @param buffer the byte array buffer to dump
+   *
+   * @return the human-readable multi-line hexadecimal dump
+   */
+  public static String prettyHexDump (@NonNull Bytes buffer) {
+    return prettyHexDump(buffer, buffer.readerIndex(), buffer.readableBytes());
+  }
+
+  /**
+   * Returns a multi-line hexadecimal dump of the specified {@link Bytes} that is easy to read by humans,
+   * starting at the given {@code offset} using the given {@code length}.
+   *
+   * @param buffer the byte array buffer to dump
+   *
+   * @param offset the buffer's offset
+   *
+   * @param length the dump's length
+   *
+   * @return the human-readable multi-line hexadecimal dump
+   */
+  @SuppressWarnings("PMD.AvoidInstantiatingObjectsInLoops")
+  public static String prettyHexDump (@NonNull Bytes buffer, int offset, int length) {
+    if (offset < 0 || length < 0 || offset + length > buffer.capacity()) {
+      val msg = String.format(ENGLISH,
+          "expected: 0 <= offset(%d) <= offset+length(%d) <= buffer.capacity(%d)",
+          offset, length, buffer.capacity()
+      );
+      throw new IndexOutOfBoundsException(msg);
+    }
+    if (length == 0) {
+      return "";
+    }
+
+    val result = new StringBuilder()
+        .append("         +-------------------------------------------------+").append(NEW_LINE)
+        .append("         |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |").append(NEW_LINE)
+        .append("+--------+-------------------------------------------------+----------------+");
+
+    val elementsInRow = 16;
+    val rows = (int) Math.ceil(length / (double) elementsInRow);
+    for (int row = 0; row < rows; row++) {
+      val hexDump = new StringBuilder("                                                 ");
+      val asciiDump = new StringBuilder("                ");
+
+      val rowStartIndex = row * elementsInRow + offset;
+      val limit = Math.min(buffer.capacity() - rowStartIndex, elementsInRow);
+      for (int index = 0; index < limit; index++) {
+        val value = buffer.getUnsignedByte(rowStartIndex + index);
+
+        val hex = byteToHex(value);
+        val hexIndex = 1 + 3 * index;
+        hexDump.setCharAt(hexIndex, hex.charAt(0));
+        hexDump.setCharAt(hexIndex + 1, hex.charAt(1));
+
+        asciiDump.setCharAt(index, byteToChar(value));
+      }
+
+      result.append(NEW_LINE)
+          .append('|').append(String.format(ENGLISH, "%07x0", row)).append('|').append(hexDump).append('|').append(asciiDump).append('|');
+    }
+
+    return result.append(NEW_LINE)
+        .append("+--------+-------------------------------------------------+----------------+")
+        .toString();
+  }
+
+  private HexUtil () {
+    throw new UnsupportedOperationException();
+  }
+}

src/test/java/io/appulse/utils/HexUtilTests.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appulse.utils;
+
+import io.netty.util.internal.ThreadLocalRandom;
+import lombok.val;
+import org.junit.jupiter.api.Test;
+
+class HexUtilTests {
+
+  @Test
+  void test1 () {
+    val bytes = new byte[512];
+    ThreadLocalRandom.current().nextBytes(bytes);
+
+    val prettyPrint = HexUtil.prettyHexDump(bytes);
+    System.out.println(prettyPrint);
+  }
+
+  @Test
+  void test2 () {
+    val bytes = new byte[60];
+    ThreadLocalRandom.current().nextBytes(bytes);
+
+    val prettyPrint = HexUtil.prettyHexDump(bytes);
+    System.out.println(prettyPrint);
+  }
+}