Let hex decoder accept even and odd number of string length

With auto zero padding (ie. 'E3F' is same as '0E3F'). Also adds
more tests for error cases and improve javadoc

refs #37

Author: patrickfav

CHANGELOG

@@ -2,6 +2,8 @@
 
 ## v1.2.0
 
+* let hex decoder accept odd length string #37
+
 ## v1.1.0
 
 * add `unsecureRandom()` constructor which creates random for e.g. tests or deterministic randoms

src/main/java/at/favre/lib/bytes/BinaryToTextEncoding.java

@@ -104,27 +104,39 @@ public String encode(byte[] byteArray, ByteOrder byteOrder) {
 
         @Override
         public byte[] decode(CharSequence hexString) {
-            if (Objects.requireNonNull(hexString, "hex input must not be null").length() % 2 != 0)
-                throw new IllegalArgumentException("invalid hex string, must be mod 2 == 0");
 
             int start;
-            if (hexString.length() > 2 &&
+            if (Objects.requireNonNull(hexString).length() > 2 &&
                     hexString.charAt(0) == '0' && hexString.charAt(1) == 'x') {
                 start = 2;
             } else {
                 start = 0;
             }
 
+
             int len = hexString.length();
+            boolean isOddLength = len % 2 != 0;
+            if (isOddLength) {
+                start--;
+            }
+
             byte[] data = new byte[(len - start) / 2];
             int first4Bits;
             int second4Bits;
             for (int i = start; i < len; i += 2) {
-                first4Bits = Character.digit(hexString.charAt(i), 16);
+                if (i == start && isOddLength) {
+                    first4Bits = 0;
+                } else {
+                    first4Bits = Character.digit(hexString.charAt(i), 16);
+                }
                 second4Bits = Character.digit(hexString.charAt(i + 1), 16);
 
                 if (first4Bits == -1 || second4Bits == -1) {
-                    throw new IllegalArgumentException("'" + hexString.charAt(i) + hexString.charAt(i + 1) + "' at index " + i + " is not hex formatted");
+                    if (i == start && isOddLength) {
+                        throw new IllegalArgumentException("'" + hexString.charAt(i + 1) + "' at index " + (i + 1) + " is not hex formatted");
+                    } else {
+                        throw new IllegalArgumentException("'" + hexString.charAt(i) + hexString.charAt(i + 1) + "' at index " + i + " is not hex formatted");
+                    }
                 }
 
                 data[(i - start) / 2] = (byte) ((first4Bits << 4) + second4Bits);

src/main/java/at/favre/lib/bytes/Bytes.java

@@ -593,11 +593,17 @@ public static Bytes parseRadix(CharSequence radixNumberString, int radix) {
     }
 
     /**
-     * Parsing of base16/HEX encoded byte arrays. Will accept upper- and lowercase variant and ignores
-     * possible "0x" prefix.
+     * Parsing of base16/HEX encoded byte arrays. This is by design a very flexible decoder accepting the following cases:
+     *
+     * <ul>
+     *     <li>Upper- and lowercase <code>a-f</code> (also mixed case)</li>
+     *     <li>Prefix with <code>0x</code> which will be ignored</li>
+     *     <li>Even and odd number of string length with auto zero padding (ie. 'E3F' is same as '0E3F')</li>
+     * </ul>
      *
      * @param hexString the encoded string
      * @return decoded instance
+     * @throws IllegalArgumentException if string contains something else than [0-9a-fA-F]
      */
     public static Bytes parseHex(CharSequence hexString) {
         return parse(hexString, new BinaryToTextEncoding.Hex());

src/test/java/at/favre/lib/bytes/BytesParseAndEncodingTest.java

@@ -42,11 +42,37 @@ public void parseHex() {
         assertArrayEquals(defaultArray, Bytes.parseHex("A0E1").array());
         assertArrayEquals(defaultArray, Bytes.parseHex("a0e1").array());
         assertArrayEquals(defaultArray, Bytes.parseHex(Bytes.parseHex("A0E1").encodeHex()).array());
+        assertArrayEquals(defaultArray, Bytes.parseHex(Bytes.parseHex("a0E1").encodeHex()).array());
+    }
+
+    @Test
+    public void parseHexOddNumberStrings() {
+        assertArrayEquals(new byte[]{(byte) 0x00}, Bytes.parseHex("0").array());
+        assertArrayEquals(new byte[]{(byte) 0x0E}, Bytes.parseHex("E").array());
+        assertArrayEquals(new byte[]{(byte) 0x0A, (byte) 0x0E}, Bytes.parseHex("A0E").array());
+        assertArrayEquals(new byte[]{(byte) 0x03, (byte) 0xEA, (byte) 0x0E}, Bytes.parseHex("3EA0E").array());
+        assertArrayEquals(new byte[]{(byte) 0x00, (byte) 0xF3, (byte) 0xEA, (byte) 0x0E}, Bytes.parseHex("0F3EA0E").array());
+        assertArrayEquals(new byte[]{(byte) 0x0A, (byte) 0xD0, (byte) 0xF3, (byte) 0xEA, (byte) 0x0E}, Bytes.parseHex("AD0F3EA0E").array());
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void parseHexIllegalChars() {
+        Bytes.parseHex("AX");
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void parseHexIllegalChars2() {
+        Bytes.parseHex("XX");
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void parseHexIllegalChars3() {
+        Bytes.parseHex("Y");
     }
 
     @Test(expected = IllegalArgumentException.class)
-    public void parseHexInvalid() {
-        Bytes.parseHex("A0E");
+    public void parseHexIllegalChars4() {
+        Bytes.parseHex("F3El0E");
     }
 
     @Test