[CODEC-203] Add convenience method decodeHex(String).

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/codec/trunk@1701126 13f79535-47bb-0310-9956-ffa450edef68

Author: garydgregory

src/changes/changes.xml

@@ -49,7 +49,8 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add" issue="CODEC-195" due-to="Gary Gregory">Support SHA-224 in DigestUtils on Java 8</action>         
       <action dev="ggregory" type="add" issue="CODEC-194" due-to="Gary Gregory">Support java.nio.ByteBuffer in org.apache.commons.codec.binary.Hex</action>         
       <action dev="ggregory" type="add" issue="CODEC-193" due-to="Michael Donaghy">Support java.nio.ByteBuffer in DigestUtils</action>         
-      <action dev="ggregory" type="add" issue="CODEC-202" due-to="Oleg Kalnichevski">Add BaseNCodec.encode(byte[], int, int) input with offset and length parameters for Base64 and Base32.</action>         
+      <action dev="ggregory" type="add" issue="CODEC-202" due-to="Oleg Kalnichevski">Add BaseNCodec.encode(byte[], int, int) input with offset and length parameters for Base64 and Base32.</action>
+      <action dev="ggregory" type="add" issue="CODEC-203" due-to="Gary Gregory">Add convenience method decodeHex(String).</action>
     </release>   
     <release version="1.10" date="5 November 2014" description="Feature and fix release.">
       <action dev="ggregory" type="add" issue="CODEC-192" due-to="Thomas Neidhart">Add Daitch-Mokotoff Soundex</action>   

src/main/java/org/apache/commons/codec/binary/Hex.java

@@ -64,6 +64,22 @@ public class Hex implements BinaryEncoder, BinaryDecoder {
     private static final char[] DIGITS_UPPER =
         {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F'};
 
+    /**
+     * Converts a String representing hexadecimal values into an array of bytes of those same values. The
+     * returned array will be half the length of the passed String, as it takes two characters to represent any given
+     * byte. An exception is thrown if the passed String has an odd number of elements.
+     *
+     * @param data
+     *            A String containing hexadecimal digits
+     * @return A byte array containing binary data decoded from the supplied char array.
+     * @throws DecoderException
+     *             Thrown if an odd number or illegal of characters is supplied
+     * @since 1.11
+     */
+    public static byte[] decodeHex(String data) throws DecoderException {
+        return decodeHex(data.toCharArray());
+    }
+
     /**
      * Converts an array of characters representing hexadecimal values into an array of bytes of those same values. The
      * returned array will be half the length of the passed array, as it takes two characters to represent any given

src/test/java/org/apache/commons/codec/binary/Base64Test.java

@@ -1154,17 +1154,17 @@ public void testUUID() throws DecoderException {
 		final byte[][] ids = new byte[4][];
 
 		// ids[0] was chosen so that it encodes with at least one +.
-		ids[0] = Hex.decodeHex("94ed8d0319e4493399560fb67404d370".toCharArray());
+		ids[0] = Hex.decodeHex("94ed8d0319e4493399560fb67404d370");
 
 		// ids[1] was chosen so that it encodes with both / and +.
-		ids[1] = Hex.decodeHex("2bf7cc2701fe4397b49ebeed5acc7090".toCharArray());
+		ids[1] = Hex.decodeHex("2bf7cc2701fe4397b49ebeed5acc7090");
 
 		// ids[2] was chosen so that it encodes with at least one /.
-		ids[2] = Hex.decodeHex("64be154b6ffa40258d1a01288e7c31ca".toCharArray());
+		ids[2] = Hex.decodeHex("64be154b6ffa40258d1a01288e7c31ca");
 
 		// ids[3] was chosen so that it encodes with both / and +, with /
 		// right at the beginning.
-		ids[3] = Hex.decodeHex("ff7f8fc01cdb471a8c8b5a9306183fe8".toCharArray());
+		ids[3] = Hex.decodeHex("ff7f8fc01cdb471a8c8b5a9306183fe8");
 
 		final byte[][] standard = new byte[4][];
 		standard[0] = StringUtils.getBytesUtf8("lO2NAxnkSTOZVg+2dATTcA==");

src/test/java/org/apache/commons/codec/binary/HexTest.java

@@ -96,9 +96,6 @@ private boolean charsetSanityCheck(final String name) {
         }
     }
 
-    /**
-     * @param data
-     */
     private void checkDecodeHexCharArrayOddCharacters(final char[] data) {
         try {
             Hex.decodeHex(data);
@@ -108,6 +105,15 @@ private void checkDecodeHexCharArrayOddCharacters(final char[] data) {
         }
     }
 
+    private void checkDecodeHexCharArrayOddCharacters(String data) {
+        try {
+            Hex.decodeHex(data);
+            fail("An exception wasn't thrown when trying to decode an odd number of characters");
+        } catch (final DecoderException e) {
+            // Expected exception
+        }
+    }
+
     private void log(final String s) {
         if (LOG) {
             System.out.println(s);
@@ -243,10 +249,15 @@ public void testDecodeByteBufferOddCharacters() {
     }
 
     @Test
-    public void testDecodeCharArrayEmpty() throws DecoderException {
+    public void testDecodeHexCharArrayEmpty() throws DecoderException {
         assertTrue(Arrays.equals(new byte[0], Hex.decodeHex(new char[0])));
     }
 
+    @Test
+    public void testDecodeHexStringEmpty() throws DecoderException {
+        assertTrue(Arrays.equals(new byte[0], Hex.decodeHex("")));
+    }
+
     @Test
     public void testDecodeClassCastException() {
         try {
@@ -262,6 +273,11 @@ public void testDecodeHexCharArrayOddCharacters1() {
         checkDecodeHexCharArrayOddCharacters(new char[] { 'A' });
     }
 
+    @Test
+    public void testDecodeHexStringOddCharacters1() {
+        checkDecodeHexCharArrayOddCharacters("A");
+    }
+
     @Test
     public void testDecodeHexCharArrayOddCharacters3() {
         checkDecodeHexCharArrayOddCharacters(new char[] { 'A', 'B', 'C' });
@@ -318,7 +334,7 @@ public void testEncodeClassCastException() {
     }
 
     @Test
-    public void testEncodeDecodeRandom() throws DecoderException, EncoderException {
+    public void testEncodeDecodeHexCharArrayRandom() throws DecoderException, EncoderException {
         final Random random = new Random();
 
         final Hex hex = new Hex();