Add readme and bigInteger constructor method

patrickfav · patrickfav · commit a5f5e16c3797 · 2017-11-04T02:38:37.000+01:00
diff --git a/CHANGELOG b/CHANGELOG
@@ -3,6 +3,7 @@
 ## v0.3.1
 
 * better validation and more creation possibilities
+* create from bigInteger
 
 ## v0.3.0
 
diff --git a/README.md b/README.md
@@ -6,6 +6,124 @@
 [![Coverage Status](https://coveralls.io/repos/github/patrickfav/bytes-java/badge.svg?branch=master)](https://coveralls.io/github/patrickfav/bytes-java?branch=master)
 
 
+## API Description
+
+### Constructors
+
+There are 2 basic constructors:
+
+ * `wrap()` which reuses the given array reference; this is equivalent to `ByteBuffer.wrap()`
+ * `from()` which always creates a new internal array reference (i.e. a copy of the passed reference)
+
+Here is a simple example to show the difference
+
+    byte[] myArray = ...
+    Bytes bWrap = Bytes.wrap(myArray);
+    assertSame(myArray, bWrap.array());
+
+    byte[] myArray2 = ...
+    Bytes bFrom = Bytes.from(myArray2);
+    assertNotSame(myArray2, bFrom.array());
+    assertArrayEquals(myArray2, bFrom.array());
+
+The following code is equivalent:
+
+    Bytes.wrap(myArray).copy() ~ Bytes.from(myArray)
+
+### More Use Cases
+
+Concatenating of multiple byte arrays or bytes:
+
+    Bytes.from(array1, array2, array3);
+    Bytes.from((byte) 0x01, (byte) 0x02, (byte) 0x03);
+
+Creating byte arrays from primitive integer types:
+
+    Bytes.from(8);  //00000000 00000000 00000000 00001000
+    Bytes.from(1897621543227L);
+
+Initializing empty arrays of arbitrary length:
+
+    Bytes.allocate(16);
+    Bytes.allocate(4,(byte) 1); //fill with 0x01
+
+Creating random byte arrays for e.g. testing:
+
+    Bytes.random(12);
+
+Reading byte content of encoded `String`s:
+
+    Bytes.from(utf8String)
+    Bytes.from(utf8StringToNormalize, Normalizer.Form.NFKD) //normalizes unicode
+    Bytes.from(asciiString, StandardCharset.US_ASCII) //any charset
+
+And other types:
+
+    Bytes.from(byteInputStream); //any inputStream
+    Bytes.from(byteList); //List<Byte> byteList = ...
+    Bytes.from(myBitSet); //BitSet myBitSet = ...
+    Bytes.from(bigInteger);
+
+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`).
+
+    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`
+
+    Bytes result = Bytes.wrap(array1).append(array2);
+    Bytes result = Bytes.wrap(array1).append(1341);
+    Bytes result = Bytes.wrap(array1).append((byte) 3);
+
+Bitwise operations: XOR, OR, AND, NOT as well as left and right shifts and switching bits:
+
+    Bytes result = Bytes.wrap(array).xor(array2);
+    Bytes result = Bytes.wrap(array).or(array2);
+    Bytes result = Bytes.wrap(array).and(array2);
+    Bytes result = Bytes.wrap(array).negate();
+    Bytes result = Bytes.wrap(array).leftShift(8);
+    Bytes result = Bytes.wrap(array).rightShift(8);
+    Bytes result = Bytes.wrap(array).switchBit(3, true);
+
+Copy operations, which copies the internal byte array to a new instance:
+
+    Bytes copy = Bytes.wrap(array).copy();
+    Bytes copy = Bytes.wrap(array).copy(3, 17); //copy partial array
+
+Resizing the internal byte array:
+
+    Bytes resized = Bytes.wrap(array).resize(3); //from {3, 9, 2, 1} to {9, 2, 1}
+
+Other transformers:
+
+    Bytes result = Bytes.wrap(array).shuffle();
+    Bytes result = Bytes.wrap(array).sort(myComparator);
+    Bytes result = Bytes.wrap(array).reverse();
+
+### Parser and Encoder
+
+### Validation
+
+A simple validation framework which can be used to check the internal byte array:
+
+    Bytes.wrap(new byte[]{8, 3, 9}.validate(BytesValidators.atLeast(3)); // true
+
+This is especially convenient when combining validators:
+
+    Bytes.wrap(new byte[]{0, 1}.validate(BytesValidators.atMost(2), BytesValidators.notOnlyOf((byte)  0)); // true
+
+### Converting
+
+### Mutable and Read-Only
+
 ## Digital Signatures
 
 ### Signed Jar
diff --git a/src/main/java/at/favre/lib/bytes/Bytes.java b/src/main/java/at/favre/lib/bytes/Bytes.java
@@ -53,7 +53,7 @@
  * <strong>Example:</strong>
  * <pre>
  *     Bytes b = Bytes.from(array);
- *     b.negate();
+ *     b.not();
  *     System.out.println(b.encodeHex());
  * </pre>
  */
@@ -265,7 +265,7 @@ public static Bytes from(ByteBuffer buffer) {
     }
 
     /**
-     * Creates a new instance from given BitSet.
+     * Creates a new instance from given {@link BitSet}.
      *
      * @param set to get the byte array from
      * @return new instance
@@ -274,6 +274,17 @@ public static Bytes from(BitSet set) {
         return wrap(set.toByteArray());
     }
 
+    /**
+     * /**
+     * Creates a new instance from given {@link BigInteger}.
+     *
+     * @param bigInteger to get the byte array from
+     * @return new instance
+     */
+    public static Bytes from(BigInteger bigInteger) {
+        return wrap(bigInteger.toByteArray());
+    }
+
     /**
      * Reads given input stream and creates a new instance from read data
      *
@@ -574,13 +585,13 @@ public Bytes or(byte[] secondArray) {
     }
 
     /**
-     * Bitwise negate operation on the whole internal byte array.
+     * Bitwise not operation on the whole internal byte array.
      * See the considerations about possible in-place operation in {@link #transform(BytesTransformer)}.
      *
      * @return negated instance
      * @see <a href="https://en.wikipedia.org/wiki/Bitwise_operation#NOT">Bitwise operators: NOT</a>
      */
-    public Bytes negate() {
+    public Bytes not() {
         return transform(new BytesTransformer.NegateTransformer());
     }
 
@@ -610,6 +621,27 @@ public Bytes rightShift(int shiftCount) {
         return transform(new BytesTransformer.ShiftTransformer(shiftCount, BytesTransformer.ShiftTransformer.Type.RIGHT_SHIFT));
     }
 
+    /**
+     * Returns a Byte whose value is equivalent to this Byte with the designated bit set to newBitValue. Bits start to count from the LSB (ie. Bytes.from(0).switchBit(0,true) == 1)
+     *
+     * @param bitPosition not to confuse with byte position
+     * @param newBitValue if true set to 1, 0 otherwise
+     * @return instance with bit switched
+     */
+    public Bytes switchBit(int bitPosition, boolean newBitValue) {
+        return transform(new BytesTransformer.BitSwitchTransformer(bitPosition, newBitValue));
+    }
+
+    /**
+     * Returns a Byte whose value is equivalent to this Byte with the designated bit switched.
+     *
+     * @param bitPosition not to confuse with byte position
+     * @return instance with bit switched
+     */
+    public Bytes switchBit(int bitPosition) {
+        return transform(new BytesTransformer.BitSwitchTransformer(bitPosition, null));
+    }
+
     /**
      * Creates a new instance with a copy of the internal byte array and all other attributes.
      *
@@ -704,27 +736,6 @@ public Bytes resize(int newByteLength) {
         return transform(new BytesTransformer.ResizeTransformer(newByteLength));
     }
 
-    /**
-     * Returns a Byte whose value is equivalent to this Byte with the designated bit set to newBitValue. Bits start to count from the LSB (ie. Bytes.from(0).switchBit(0,true) == 1)
-     *
-     * @param bitPosition not to confuse with byte position
-     * @param newBitValue if true set to 1, 0 otherwise
-     * @return instance with bit switched
-     */
-    public Bytes switchBit(int bitPosition, boolean newBitValue) {
-        return transform(new BytesTransformer.BitSwitchTransformer(bitPosition, newBitValue));
-    }
-
-    /**
-     * Returns a Byte whose value is equivalent to this Byte with the designated bit switched.
-     *
-     * @param bitPosition not to confuse with byte position
-     * @return instance with bit switched
-     */
-    public Bytes switchBit(int bitPosition) {
-        return transform(new BytesTransformer.BitSwitchTransformer(bitPosition, null));
-    }
-
     /**
      * Generic transformation of this instance.
      * <p>
@@ -973,23 +984,7 @@ private ByteBuffer internalBuffer() {
         return ByteBuffer.wrap(internalArray()).order(byteOrder);
     }
 
-    /**
-     * The internal byte array wrapped in a {@link BigInteger} instance.
-     * <p>
-     * If the internal byte order is {@link ByteOrder#LITTLE_ENDIAN}, a copy of the internal
-     * array will be reversed and used as backing array with the big integer. Otherwise the internal
-     * array will be used directly.
-     *
-     * @return big integer
-     * @throws ReadOnlyBufferException if this is a read-only instance
-     */
-    public BigInteger bigInteger() {
-        if (byteOrder == ByteOrder.LITTLE_ENDIAN) {
-            return new BigInteger(new BytesTransformer.ReverseTransformer().transform(array(), false));
-        } else {
-            return new BigInteger(array());
-        }
-    }
+
 
     /**
      * Returns a mutable version of this instance with sharing the same underlying byte-array.
@@ -1182,6 +1177,23 @@ public BitSet toBitSet() {
         return BitSet.valueOf(internalArray());
     }
 
+    /**
+     * The internal byte array wrapped in a {@link BigInteger} instance.
+     * <p>
+     * If the internal byte order is {@link ByteOrder#LITTLE_ENDIAN}, a copy of the internal
+     * array will be reversed and used as backing array with the big integer. Otherwise the internal
+     * array will be used directly.
+     *
+     * @return big integer
+     */
+    public BigInteger toBigInteger() {
+        if (byteOrder == ByteOrder.LITTLE_ENDIAN) {
+            return new BigInteger(new BytesTransformer.ReverseTransformer().transform(internalArray(), false));
+        } else {
+            return new BigInteger(internalArray());
+        }
+    }
+
     /**
      * If the underlying byte array is smaller than or equal to 1 byte / 8 bit returns unsigned two-complement
      * representation for a Java byte value.
diff --git a/src/test/java/at/favre/lib/bytes/BytesByteOrderTest.java b/src/test/java/at/favre/lib/bytes/BytesByteOrderTest.java
@@ -126,8 +126,8 @@ public void toLong() throws Exception {
     @Test
     public void bigInteger() throws Exception {
         Bytes b = Bytes.from(example_bytes_four);
-        assertNotEquals(b.byteOrder(ByteOrder.BIG_ENDIAN).bigInteger(), b.byteOrder(ByteOrder.LITTLE_ENDIAN).bigInteger());
-        assertEquals(b.byteOrder(ByteOrder.BIG_ENDIAN).bigInteger(), b.byteOrder(ByteOrder.LITTLE_ENDIAN).reverse().bigInteger());
+        assertNotEquals(b.byteOrder(ByteOrder.BIG_ENDIAN).toBigInteger(), b.byteOrder(ByteOrder.LITTLE_ENDIAN).toBigInteger());
+        assertEquals(b.byteOrder(ByteOrder.BIG_ENDIAN).toBigInteger(), b.byteOrder(ByteOrder.LITTLE_ENDIAN).reverse().toBigInteger());
     }
 
 }
diff --git a/src/test/java/at/favre/lib/bytes/BytesConstructorTests.java b/src/test/java/at/favre/lib/bytes/BytesConstructorTests.java
@@ -24,6 +24,7 @@
 import org.junit.Test;
 
 import java.io.ByteArrayInputStream;
+import java.math.BigInteger;
 import java.nio.ByteBuffer;
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
@@ -79,6 +80,7 @@ public void fromBitSet() throws Exception {
         checkBitSet(example_bytes_two);
         checkBitSet(example_bytes_seven);
         checkBitSet(example_bytes_eight);
+        checkBitSet(example_bytes_twentyfour);
     }
 
     private void checkBitSet(byte[] array) {
@@ -87,6 +89,21 @@ private void checkBitSet(byte[] array) {
         assertEquals(bitSet, Bytes.from(bitSet).toBitSet());
     }
 
+    @Test
+    public void fromBigInteger() throws Exception {
+        checkBigInteger(example_bytes_one);
+        checkBigInteger(example_bytes_two);
+        checkBigInteger(example_bytes_seven);
+        checkBigInteger(example_bytes_eight);
+        checkBigInteger(example_bytes_twentyfour);
+    }
+
+    private void checkBigInteger(byte[] array) {
+        BigInteger bigInteger = new BigInteger(array);
+        assertArrayEquals(array, Bytes.from(bigInteger).array());
+        assertEquals(bigInteger, Bytes.from(bigInteger).toBigInteger());
+    }
+
     @Test
     public void fromByte() throws Exception {
         byte test = 0x4E;
diff --git a/src/test/java/at/favre/lib/bytes/BytesMiscTest.java b/src/test/java/at/favre/lib/bytes/BytesMiscTest.java
@@ -192,7 +192,7 @@ public void readOnlyShouldKeepProperty() throws Exception {
         assertTrue(b.resize(6).isReadOnly());
         assertTrue(b.sort().isReadOnly());
         assertTrue(b.shuffle().isReadOnly());
-        assertTrue(b.negate().isReadOnly());
+        assertTrue(b.not().isReadOnly());
         assertTrue(b.leftShift(1).isReadOnly());
         assertTrue(b.rightShift(1).isReadOnly());
         assertTrue(b.and(Bytes.random(b.length())).isReadOnly());
diff --git a/src/test/java/at/favre/lib/bytes/BytesSharedDataConverterTest.java b/src/test/java/at/favre/lib/bytes/BytesSharedDataConverterTest.java
@@ -42,12 +42,12 @@ public void array() throws Exception {
 
     @Test
     public void bigInteger() throws Exception {
-        assertArrayEquals(example_bytes_one, Bytes.from(example_bytes_one).bigInteger().toByteArray());
-        assertArrayEquals(example_bytes_two, Bytes.from(example_bytes_two).bigInteger().toByteArray());
-        assertArrayEquals(example_bytes_four, Bytes.from(example_bytes_four).bigInteger().toByteArray());
-        assertArrayEquals(example_bytes_seven, Bytes.from(example_bytes_seven).bigInteger().toByteArray());
-        assertArrayEquals(example_bytes_eight, Bytes.from(example_bytes_eight).bigInteger().toByteArray());
-        assertArrayEquals(example_bytes_sixteen, Bytes.from(example_bytes_sixteen).bigInteger().toByteArray());
+        assertArrayEquals(example_bytes_one, Bytes.from(example_bytes_one).toBigInteger().toByteArray());
+        assertArrayEquals(example_bytes_two, Bytes.from(example_bytes_two).toBigInteger().toByteArray());
+        assertArrayEquals(example_bytes_four, Bytes.from(example_bytes_four).toBigInteger().toByteArray());
+        assertArrayEquals(example_bytes_seven, Bytes.from(example_bytes_seven).toBigInteger().toByteArray());
+        assertArrayEquals(example_bytes_eight, Bytes.from(example_bytes_eight).toBigInteger().toByteArray());
+        assertArrayEquals(example_bytes_sixteen, Bytes.from(example_bytes_sixteen).toBigInteger().toByteArray());
     }
 
     @Test
diff --git a/src/test/java/at/favre/lib/bytes/BytesTransformTest.java b/src/test/java/at/favre/lib/bytes/BytesTransformTest.java
@@ -164,14 +164,14 @@ public void and() throws Exception {
 
     @Test
     public void negate() throws Exception {
-        assertArrayEquals(new byte[0], Bytes.from(new byte[0]).negate().array());
-        assertArrayEquals(new byte[]{(byte) 0xFF}, Bytes.from(new byte[1]).negate().array());
+        assertArrayEquals(new byte[0], Bytes.from(new byte[0]).not().array());
+        assertArrayEquals(new byte[]{(byte) 0xFF}, Bytes.from(new byte[1]).not().array());
 
-        assertArrayEquals(new byte[]{-104}, Bytes.from(example_bytes_one).negate().array());
-        assertArrayEquals(new byte[]{-27, -112}, Bytes.from(example_bytes_two).negate().array());
-        assertArrayEquals(new byte[]{81, -31}, Bytes.from(new byte[]{(byte) 0xAE, (byte) 0x1E}).negate().array());
+        assertArrayEquals(new byte[]{-104}, Bytes.from(example_bytes_one).not().array());
+        assertArrayEquals(new byte[]{-27, -112}, Bytes.from(example_bytes_two).not().array());
+        assertArrayEquals(new byte[]{81, -31}, Bytes.from(new byte[]{(byte) 0xAE, (byte) 0x1E}).not().array());
 
-        assertArrayNotEquals(new byte[0], Bytes.from(example_bytes_one).negate().array());
+        assertArrayNotEquals(new byte[0], Bytes.from(example_bytes_one).not().array());
     }
 
     @Test
diff --git a/src/test/java/at/favre/lib/bytes/MutableBytesABytesTest.java b/src/test/java/at/favre/lib/bytes/MutableBytesABytesTest.java
@@ -117,7 +117,7 @@ public void testTransformerShouldBeMutable() throws Exception {
         assertTrue(b.resize(6).isMutable());
         assertTrue(b.sort().isMutable());
         assertTrue(b.shuffle().isMutable());
-        assertTrue(b.negate().isMutable());
+        assertTrue(b.not().isMutable());
         assertTrue(b.leftShift(1).isMutable());
         assertTrue(b.rightShift(1).isMutable());
         assertTrue(b.and(Bytes.random(b.length())).isMutable());

Original file line number	Diff line number	Diff line change
`@@ -126,8 +126,8 @@ public void toLong() throws Exception {`
`126`	`126`	`@Test`
`127`	`127`	`public void bigInteger() throws Exception {`
`128`	`128`	`Bytes b = Bytes.from(example_bytes_four);`
`129`		`- assertNotEquals(b.byteOrder(ByteOrder.BIG_ENDIAN).bigInteger(), b.byteOrder(ByteOrder.LITTLE_ENDIAN).bigInteger());`
`130`		`- assertEquals(b.byteOrder(ByteOrder.BIG_ENDIAN).bigInteger(), b.byteOrder(ByteOrder.LITTLE_ENDIAN).reverse().bigInteger());`
	`129`	`+ assertNotEquals(b.byteOrder(ByteOrder.BIG_ENDIAN).toBigInteger(), b.byteOrder(ByteOrder.LITTLE_ENDIAN).toBigInteger());`
	`130`	`+ assertEquals(b.byteOrder(ByteOrder.BIG_ENDIAN).toBigInteger(), b.byteOrder(ByteOrder.LITTLE_ENDIAN).reverse().toBigInteger());`
`131`	`131`	`}`
`132`	`132`
`133`	`133`	`}`