Add toIntArray converter

Supports little and big endian order.

fixes #28

Author: patrickfav

CHANGELOG

@@ -5,6 +5,7 @@
 * add `append()` method supporting multiple byte arrays #26
 * add `toCharArray()` method which decodes internal byte array to char[] #27
 * add `encodeBase64()` supporting padding-less encoding
+* add `toIntArray()` converter #28
 
 ### Breaking
 

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

@@ -1625,7 +1625,7 @@ public String encodeBase36() {
 
     /**
      * Base64 representation with padding. This is *NOT* the url safe variation. This encoding has a space efficiency of 75%.
-     *
+     * <p>
      * This encoding is <a href="https://tools.ietf.org/html/rfc4648">RFC 4648</a> compatible.
      * <p>
      * Example: <code>SpT9/x6v7Q==</code>
@@ -1640,7 +1640,7 @@ public String encodeBase64() {
     /**
      * Base64 representation with padding. This is the url safe variation substitution '+' and '/' with '-' and '_'
      * respectively. This encoding has a space efficiency of 75%.
-     *
+     * <p>
      * This encoding is <a href="https://tools.ietf.org/html/rfc4648">RFC 4648</a> compatible.
      * <p>
      * Example: <code>SpT9_x6v7Q==</code>
@@ -1736,7 +1736,7 @@ public List<Byte> toList() {
     /**
      * Returns a copy of the internal byte-array as boxed primitive array.
      * This requires a time and space complexity of O(n).
-     *
+     * <p>
      * Note: this method was previously called <code>toObjectArray()</code>
      *
      * @return copy of internal array as object array
@@ -1861,6 +1861,25 @@ public int toInt() {
         return intAt(0);
     }
 
+    /**
+     * Converts the internal byte array to an int array, that is, every 4 bytes will be packed into a single int.
+     * <p>
+     * E.g. 4 bytes will be packed to a length 1 int array:
+     * <pre>
+     *  [b1, b2, b3, b4] = [int1]
+     * </pre>
+     * <p>
+     * This conversion respects the internal byte order. Will only work if all bytes can be directly mapped to int,
+     * which means the byte array length must be dividable by 4 without rest.
+     *
+     * @return new int[] instance representing this byte array
+     * @throws IllegalArgumentException if internal byte length mod 4 != 0
+     */
+    public int[] toIntArray() {
+        Util.checkModLength(length(), 4, "creating an int array");
+        return Util.toIntArray(internalArray(), byteOrder);
+    }
+
     /**
      * If the underlying byte array is exactly 8 byte / 64 bit long, return signed two-complement
      * representation for a Java signed long integer value. The output is dependent on the set {@link #byteOrder()}.

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

@@ -25,6 +25,7 @@
 import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
 import java.nio.CharBuffer;
+import java.nio.IntBuffer;
 import java.nio.charset.CharacterCodingException;
 import java.nio.charset.Charset;
 import java.nio.file.Files;
@@ -456,6 +457,28 @@ static char[] byteToCharArray(byte[] bytes, Charset charset) {
         }
     }
 
+    /**
+     * Converts the byte array to an int array. This will spread 4 bytes into a single int:
+     *
+     * <pre>
+     *     [b1, b2, b3, b4] = int1
+     * </pre>
+     *
+     * @param bytes     to convert to int array
+     * @param byteOrder of the byte array
+     * @return int array
+     */
+    static int[] toIntArray(byte[] bytes, ByteOrder byteOrder) {
+        IntBuffer buffer = ByteBuffer.wrap(bytes).order(byteOrder).asIntBuffer();
+        if (buffer.hasArray()) {
+            return buffer.array();
+        } else {
+            int[] array = new int[buffer.remaining()];
+            buffer.get(array);
+            return array;
+        }
+    }
+
     /**
      * Shows the length and a preview of max 8 bytes of the given byte
      *
@@ -590,6 +613,21 @@ static int hashCode(byte[] byteArray, ByteOrder byteOrder) {
         return result;
     }
 
+    /**
+     * Checks if given length is divisable by mod factor (with zero rest).
+     * This can be used to check of a byte array can be convertet to an e.g. int array which is
+     * multiples of 4.
+     *
+     * @param length       of the byte array
+     * @param modFactor    to divide the length
+     * @param errorSubject human readable message of the exact error subject
+     */
+    static void checkModLength(int length, int modFactor, String errorSubject) {
+        if (length % modFactor != 0) {
+            throw new IllegalArgumentException("Illegal length for " + errorSubject + ". Byte array length must be multiple of " + modFactor + ", length was " + length);
+        }
+    }
+
     /*
     =================================================================================================
      Copyright 2011 Twitter, Inc.

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

@@ -23,6 +23,7 @@
 
 import org.junit.Test;
 
+import java.nio.ByteOrder;
 import java.util.List;
 
 import static org.junit.Assert.*;
@@ -235,4 +236,44 @@ public void testToUUIDToShort() {
     public void testToUUIDEmpty() {
         Bytes.allocate(0).toUUID();
     }
+
+    @Test
+    public void testToIntArray() {
+        assertArrayEquals(new int[]{1}, Bytes.wrap(new byte[]{0, 0, 0, 1}).toIntArray());
+        assertArrayEquals(new int[]{257}, Bytes.wrap(new byte[]{0, 0, 1, 1}).toIntArray());
+        assertArrayEquals(new int[]{65_793}, Bytes.wrap(new byte[]{0, 1, 1, 1}).toIntArray());
+        assertArrayEquals(new int[]{16_843_009}, Bytes.wrap(new byte[]{1, 1, 1, 1}).toIntArray());
+        assertArrayEquals(new int[]{571_211_845}, Bytes.wrap(new byte[]{34, 12, 0, 69}).toIntArray());
+        assertArrayEquals(new int[]{1_290_429_439}, Bytes.wrap(new byte[]{76, (byte) 234, 99, (byte) 255}).toIntArray());
+
+        assertArrayEquals(new int[]{1, 1}, Bytes.wrap(new byte[]{0, 0, 0, 1, 0, 0, 0, 1}).toIntArray());
+        assertArrayEquals(new int[]{257, 1}, Bytes.wrap(new byte[]{0, 0, 1, 1, 0, 0, 0, 1}).toIntArray());
+        assertArrayEquals(new int[]{257, 65_793, 1}, Bytes.wrap(new byte[]{0, 0, 1, 1, 0, 1, 1, 1, 0, 0, 0, 1}).toIntArray());
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testToIntArrayNotMod4Was5Byte() {
+        Bytes.wrap(new byte[]{1, 0, 0, 0, 1}).toIntArray();
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testToIntArrayNotMod4Only3Byte() {
+        Bytes.wrap(new byte[]{0, 0, 1}).toIntArray();
+    }
+
+    @Test
+    public void testToIntEmptyArray() {
+        assertArrayEquals(new int[0], Bytes.empty().toIntArray());
+    }
+
+    @Test
+    public void testToIntArrayLittleEndian() {
+        assertArrayEquals(new int[]{1}, Bytes.wrap(new byte[]{1, 0, 0, 0}, ByteOrder.LITTLE_ENDIAN).toIntArray());
+        assertArrayEquals(new int[]{257}, Bytes.wrap(new byte[]{1, 1, 0, 0}, ByteOrder.LITTLE_ENDIAN).toIntArray());
+        assertArrayEquals(new int[]{1_290_429_439}, Bytes.wrap(new byte[]{(byte) 255, 99, (byte) 234, 76}, ByteOrder.LITTLE_ENDIAN).toIntArray());
+
+        assertArrayEquals(new int[]{1, 1}, Bytes.wrap(new byte[]{1, 0, 0, 0, 1, 0, 0, 0}, ByteOrder.LITTLE_ENDIAN).toIntArray());
+        assertArrayEquals(new int[]{257, 1}, Bytes.wrap(new byte[]{1, 1, 0, 0, 1, 0, 0, 0}, ByteOrder.LITTLE_ENDIAN).toIntArray());
+        assertArrayEquals(new int[]{257, 65_793, 1}, Bytes.wrap(new byte[]{1, 1, 0, 0, 1, 1, 1, 0, 1, 0, 0, 0}, ByteOrder.LITTLE_ENDIAN).toIntArray());
+    }
 }