Creation of int and long array as well as object byte arrays

Author: patrickfav

CHANGELOG

@@ -3,7 +3,7 @@
 ## v0.3.1
 
 * better validation and more creation possibilities
-* create from bigInteger
+* create from bigInteger, int[], long[] and Byte[]
 
 ## v0.3.0
 

README.md

@@ -22,7 +22,7 @@ There are 3 basic constructors:
  * `from()` which always creates a new internal array reference (i.e. a copy of the passed reference)
  * `parse()` which parses from binary-text-encoded strings (see other section)
 
-Here is a simple example to show the difference
+Here is a simple example to show the difference:
 
 ```java
 byte[] myArray = ...
@@ -50,11 +50,12 @@ Bytes.from(array1, array2, array3);
 Bytes.from((byte) 0x01, (byte) 0x02, (byte) 0x03);
 ```
 
-Creating byte arrays from **primitive integer** types:
+Creating byte arrays from **primitive integer** types and arrays:
 
 ```java
 Bytes.from(8);  //00000000 00000000 00000000 00001000
 Bytes.from(1897621543227L);
+Bytes.from(1634, 88903, 77263);
 ```
 
 Initializing **empty arrays** of arbitrary length:
@@ -93,7 +94,8 @@ For parsing binary-text-encoded strings, see below.
 ### Transformers
 
 Transformer transform the internal byte array. It is possible to create
-a custom transformer if a specific use case is required (see `BytesTransformer`).
+custom transformers if a specific feature is not provided by the default
+ implementation (see `BytesTransformer`).
 
 ```java
 Bytes result = Bytes.wrap(array1).transform(myCustomTransformer);
@@ -102,8 +104,8 @@ Bytes result = Bytes.wrap(array1).transform(myCustomTransformer);
 #### Built-In Transformers
 
 For **appending** byte arrays or primitive integer types to current instances.
-Note however, that this will create new copies of byte arrays every time.
-For dynamic growing byte arrays see `ByteArrayOutputStream`
+*Note:* this will create a new copy of the internal byte array; for dynamically
+ growing byte arrays see `ByteArrayOutputStream`.
 
 ```java
 Bytes result = Bytes.wrap(array1).append(array2);
@@ -146,7 +148,7 @@ Bytes result = Bytes.wrap(array).reverse();
 
 ### Parser and Encoder for Binary-Text-Encodings
 
-This library can parse and encode a variety of encodings: binary, decimal, ocatal,
+This library can parse and encode a variety of encodings: binary, decimal, octal,
 hex, base36 and base64. Additionally custom parsers are supported by providing your own
 implementation:
 
@@ -155,7 +157,7 @@ Bytes.parse("8sK;S*j=r", base85Decoder);
 Bytes.encode(base85Encoder);
  ```
 
-**Hex** can be upper and lowercase and also supports `0x` prefix for parsing
+**Hex** can be upper and lowercase and also supports `0x` prefix for parsing:
 
 ```java
 Bytes.parseHex("a0e13eaa1a")

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

@@ -114,6 +114,9 @@ public byte[] decode(String hexString) {
         }
     }
 
+    /**
+     * Simple Base64 encoder
+     */
     class Base64Encoding implements Encoder, Decoder {
         @Override
         public String encode(byte[] array, ByteOrder byteOrder) {
@@ -126,6 +129,9 @@ public byte[] decode(String encoded) {
         }
     }
 
+    /**
+     * Simple radix encoder which internally uses {@link BigInteger#toString(int)}
+     */
     class BaseRadix implements Encoder, Decoder {
         private final int radix;
 

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

@@ -129,6 +129,18 @@ public static Bytes wrap(byte[] array, ByteOrder byteOrder) {
         return new Bytes(array, byteOrder);
     }
 
+    /**
+     * Creates a new instance from given collections of single bytes.
+     * This will create a copy of given bytes and will not directly use given bytes or byte array.
+     *
+     * @param byteArrayToCopy must not be null and will not be used directly, but a copy
+     * @return new instance
+     */
+    public static Bytes from(byte[] byteArrayToCopy) {
+        Objects.requireNonNull(byteArrayToCopy, "must at least pass a single byte");
+        return wrap(Arrays.copyOf(byteArrayToCopy, byteArrayToCopy.length));
+    }
+
     /**
      * Creates a new instance from a slice of given array
      *
@@ -181,25 +193,23 @@ public static Bytes from(Collection<Byte> bytesCollection) {
     }
 
     /**
-     * Creates a new single array element array instance from given byte
+     * Creates a new instance from given object byte array. Will copy and unbox every element.
      *
-     * @param singleByte to create from
+     * @param objectArray to create from
      * @return new instance
      */
-    public static Bytes from(byte singleByte) {
-        return wrap(new byte[]{singleByte});
+    public static Bytes from(Byte[] objectArray) {
+        return wrap(Util.toPrimitiveArray(objectArray));
     }
 
     /**
-     * Creates a new instance from given collections of single bytes.
-     * This will create a copy of given bytes and will not directly use given bytes or byte array.
+     * Creates a new single array element array instance from given byte
      *
-     * @param byteArrayToCopy must not be null and will not be used directly, but a copy
+     * @param singleByte to create from
      * @return new instance
      */
-    public static Bytes from(byte[] byteArrayToCopy) {
-        Objects.requireNonNull(byteArrayToCopy, "must at least pass a single byte");
-        return wrap(Arrays.copyOf(byteArrayToCopy, byteArrayToCopy.length));
+    public static Bytes from(byte singleByte) {
+        return wrap(new byte[]{singleByte});
     }
 
     /**
@@ -244,6 +254,17 @@ public static Bytes from(int integer4byte) {
         return wrap(ByteBuffer.allocate(4).putInt(integer4byte).array());
     }
 
+    /**
+     * Creates a new instance from given 4 byte integer array.
+     *
+     * @param intArray to create from
+     * @return new instance
+     */
+    public static Bytes from(int... intArray) {
+        Objects.requireNonNull(intArray, "must provide at least a single int");
+        return wrap(Util.toByteArray(intArray));
+    }
+
     /**
      * Creates a new instance from given 8 byte long.
      *
@@ -254,6 +275,17 @@ public static Bytes from(long long8byte) {
         return wrap(ByteBuffer.allocate(8).putLong(long8byte).array());
     }
 
+    /**
+     * Creates a new instance from given 8 byte long array.
+     *
+     * @param longArray to create from
+     * @return new instance
+     */
+    public static Bytes from(long... longArray) {
+        Objects.requireNonNull(longArray, "must provide at least a single long");
+        return wrap(Util.toByteArray(longArray));
+    }
+
     /**
      * Creates a new instance from given ByteBuffer.
      * Will use the same backing byte array and honour the buffer's byte order.
@@ -677,7 +709,7 @@ public Bytes copy(int offset, int length) {
     }
 
     /**
-     * Reverses the internal byte array.
+     * Reverses the internal bytes in the array (not bits in each byte)
      * <p>
      * See the considerations about possible in-place operation in {@link #transform(BytesTransformer)}.
      *
@@ -1359,6 +1391,9 @@ public String toString() {
         return length() + " bytes " + preview;
     }
 
+    /**
+     * Internal factory for {@link Bytes} instances
+     */
     private static class Factory implements BytesFactory {
         @Override
         public Bytes wrap(byte[] array, ByteOrder byteOrder) {

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

@@ -23,6 +23,17 @@
 
 import java.nio.ByteOrder;
 
+/**
+ * Simple factory for creating {@link Bytes} instances
+ */
 public interface BytesFactory {
+
+    /**
+     * Create an instance with given array and order
+     *
+     * @param array     to directly us
+     * @param byteOrder the array is in
+     * @return a new instance
+     */
     Bytes wrap(byte[] array, ByteOrder byteOrder);
 }

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

@@ -27,7 +27,7 @@
 import java.util.Objects;
 
 /**
- * Mutable version of {@link Bytes}. If possible, all transformations are done in place, without creating a copy.
+ * Mutable version of {@link Bytes} created by calling {@link #mutable()}. If possible, all transformations are done in place, without creating a copy.
  * <p>
  * Adds additional mutator, which may change the internal array in-place, like {@link #wipe()}
  */

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

@@ -24,6 +24,13 @@
 import java.nio.ByteOrder;
 import java.nio.ReadOnlyBufferException;
 
+/**
+ * The read-only version of {@link Bytes} created by calling {@link #readOnly()}.
+ * <p>
+ * Read-only Bytes does not have access to the internal byte array ({@link #array()}
+ * will throw an exception). Transformers will always create a copy and keep the
+ * read-only status.
+ */
 public final class ReadOnlyBytes extends Bytes {
 
     /**

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

@@ -25,6 +25,7 @@
 import java.io.File;
 import java.io.IOException;
 import java.io.InputStream;
+import java.nio.ByteBuffer;
 import java.nio.file.Files;
 import java.util.*;
 
@@ -164,8 +165,8 @@ static List<Byte> toList(byte[] array) {
     }
 
     /**
-     * Converts this primitive array to an boxed object array. Will create a new array
-     * and not reuse the array reference.
+     * Converts this primitive array to an boxed object array.
+     * Will create a new array and not reuse the array reference.
      *
      * @param array to convert
      * @return new array
@@ -178,6 +179,57 @@ static Byte[] toObjectArray(byte[] array) {
         return objectArray;
     }
 
+    /**
+     * Converts this object array to an primitives type array.
+     * Will create a new array and not reuse the array reference.
+     *
+     * @param objectArray to convert
+     * @return new array
+     */
+    static byte[] toPrimitiveArray(Byte[] objectArray) {
+        byte[] primitivesArray = new byte[objectArray.length];
+        for (int i = 0; i < objectArray.length; i++) {
+            primitivesArray[i] = objectArray[i];
+        }
+        return primitivesArray;
+    }
+
+    /**
+     * Creates a byte array from given int array.
+     * The resulting byte array will have length intArray * 4.
+     *
+     * @param intArray to convert
+     * @return resulting byte array
+     */
+    static byte[] toByteArray(int[] intArray) {
+        byte[] primitivesArray = new byte[intArray.length * 4];
+        for (int i = 0; i < intArray.length; i++) {
+            byte[] intBytes = ByteBuffer.allocate(4).putInt(intArray[i]).array();
+            for (int j = 0; j < intBytes.length; j++) {
+                primitivesArray[(i * 4) + j] = intBytes[j];
+            }
+        }
+        return primitivesArray;
+    }
+
+    /**
+     * Creates a byte array from given long array.
+     * The resulting byte array will have length longArray * 8
+     *
+     * @param longArray to convert
+     * @return resulting byte array
+     */
+    static byte[] toByteArray(long[] longArray) {
+        byte[] primitivesArray = new byte[longArray.length * 8];
+        for (int i = 0; i < longArray.length; i++) {
+            byte[] longBytes = ByteBuffer.allocate(8).putLong(longArray[i]).array();
+            for (int j = 0; j < longBytes.length; j++) {
+                primitivesArray[(i * 8) + j] = longBytes[j];
+            }
+        }
+        return primitivesArray;
+    }
+
     /**
      * Simple Durstenfeld shuffle
      * <p>
@@ -251,7 +303,6 @@ static byte[] readFromFile(File file) {
         } catch (IOException e) {
             throw new IllegalStateException("could not read from file", e);
         }
-
     }
 
     /*

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

@@ -145,6 +145,14 @@ public void fromInt() throws Exception {
         assertEquals(test, Bytes.from(test).toInt());
     }
 
+    @Test
+    public void fromIntArray() throws Exception {
+        assertArrayEquals(new byte[]{0, 0, 0, 1, 0, 0, 0, 2}, Bytes.from(1, 2).array());
+        assertArrayEquals(Bytes.from(Bytes.from(871193), Bytes.from(6761), Bytes.from(-917656)).array(), Bytes.from(871193, 6761, -917656).array());
+        assertArrayEquals(Bytes.from(Bytes.from(1678), Bytes.from(-223), Bytes.from(11114)).array(), Bytes.from(1678, -223, 11114).array());
+        assertArrayEquals(new byte[]{0, 11, 30, 55, 0, 0, 35, 53, 0, 0, 0, 0, 0, 0, 56, -70}, Bytes.from(728631, 9013, 0, 14522).array());
+    }
+
     @Test
     public void fromLong() throws Exception {
         long test = 172283719283L;
@@ -154,6 +162,14 @@ public void fromLong() throws Exception {
         assertEquals(test, Bytes.from(test).toLong());
     }
 
+    @Test
+    public void fromLongArray() throws Exception {
+        assertArrayEquals(new byte[]{0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 2}, Bytes.from(new long[]{1, 2}).array());
+        assertArrayEquals(Bytes.from(Bytes.from(871193L), Bytes.from(6761L), Bytes.from(-917656L)).array(), Bytes.from(new long[]{871193, 6761, -917656}).array());
+        assertArrayEquals(Bytes.from(Bytes.from(1678L), Bytes.from(-223L), Bytes.from(11114L)).array(), Bytes.from(1678L, -223L, 11114L).array());
+        assertArrayEquals(Bytes.from(Bytes.from(1273612831678L), Bytes.from(-72639123786223L)).array(), Bytes.from(1273612831678L, -72639123786223L).array());
+    }
+
     @Test
     public void fromByteBuffer() throws Exception {
         checkByteBuffer(example_bytes_empty);
@@ -273,4 +289,11 @@ public void fromFile() throws Exception {
 
         assertArrayEquals(randomBytes.array(), Bytes.from(tempFile).array());
     }
+
+    @Test
+    public void fromObjectArray() throws Exception {
+        Byte[] objectArray = new Byte[]{0x01, 0x02, 0x03, 0x04};
+        Bytes b = Bytes.from(objectArray);
+        assertArrayEquals(new byte[]{0x01, 0x02, 0x03, 0x04}, b.array());
+    }
 }