Add bitAt() feature

Author: patrickfav

CHANGELOG

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.4.1
+
+* add bitAt() utility
+
 ## v0.4.0
 
 * logical expressions in validators

README.md

@@ -36,7 +36,7 @@ It's main features include:
 * **Validators** with the ability to arbitrarily combine multiple ones
 * **Parsing and Encoding** in most common binary-to-text-encodings: [hex](https://en.wikipedia.org/wiki/Hexadecimal), [base64](https://en.wikipedia.org/wiki/Base64), ...
 * **Immutable, Mutable and Read-Only** versions
-* **Utility Features** like `indexOf`, `count`, `isEmpty`, `byteAt`, ...
+* **Utility Features** like `indexOf`, `count`, `isEmpty`, `bitAt`, ...
 
 It is written in Java 7 to keep backwards compatibility with *Android* and older *Java* applications.
 
@@ -259,6 +259,7 @@ Bytes.wrap(array).isEmpty();
 And others:
 
 ```java
+Bytes.wrap(array).bitAt(4);
 Bytes.wrap(array).byteAt(14);
 Bytes.wrap(array).count(0x01); //occurrence of 0x01
 Bytes.wrap(array).entropy();

pom.xml

@@ -6,12 +6,13 @@
 
     <groupId>at.favre.lib</groupId>
     <artifactId>bytes</artifactId>
-    <version>0.4.0</version>
+    <version>0.4.1</version>
     <packaging>jar</packaging>
 
-    <name>Bytes Java Primitive Tools</name>
-    <description>Convenience toolkit for easier handling, creating, converting and encoding of any form of byte arrays.
-        Per default everything is immutable, but also supports faster mutable version.
+    <name>Bytes Utility Library</name>
+    <description>Bytes is a utility library that makes it easy to create, parse, transform, validate and convert byte
+        arrays in Java. It supports endianness as well as immutability and mutability, so the caller may decide to favor
+        performance.
     </description>
     <url>https://github.com/patrickfav/bytes-java</url>
     <inceptionYear>2017</inceptionYear>
@@ -163,18 +164,6 @@
             <version>4.12</version>
             <scope>test</scope>
         </dependency>
-        <dependency>
-            <groupId>org.apache.commons</groupId>
-            <artifactId>commons-lang3</artifactId>
-            <version>3.6</version>
-            <scope>test</scope>
-        </dependency>
-        <dependency>
-            <groupId>commons-codec</groupId>
-            <artifactId>commons-codec</artifactId>
-            <version>1.10</version>
-            <scope>test</scope>
-        </dependency>
     </dependencies>
     <developers>
         <developer>

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

@@ -926,7 +926,7 @@ public int lastIndexOf(byte target) {
      *
      * @param index the index of the {@code byte} value.
      * @return the {@code byte} value at the specified index of the underlying byte array.
-     * @throws IndexOutOfBoundsException if the {@code index} argument is negative or not less than the length of this string.
+     * @throws IndexOutOfBoundsException if the {@code index} argument is negative or not less than the length of this array.
      */
     public byte byteAt(int index) {
         if (index < 0 || index > length()) {
@@ -935,6 +935,20 @@ public byte byteAt(int index) {
         return internalArray()[index];
     }
 
+    /**
+     * Returns the {@code bit} value as boolean at the specified index.
+     *
+     * @param bitIndex the index of the {@code bit} value.
+     * @return true if bit at given index is set, false otherwise
+     * @throws IndexOutOfBoundsException if the {@code bitIndex} argument is negative or not less than the length of this array in bits.
+     */
+    public boolean bitAt(int bitIndex) {
+        if (bitIndex < 0 || bitIndex > length() * 8) {
+            throw new IndexOutOfBoundsException("cannot get bit from index out of bounds: " + bitIndex);
+        }
+        return (byteAt(bitIndex / 8) >> (bitIndex % 8) & 1) == 1;
+    }
+
     /**
      * Traverses the internal byte array counts the occurrences of given byte.
      * This has a time complexity of O(n).

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

@@ -303,7 +303,6 @@ public byte[] transform(byte[] currentArray, boolean inPlace) {
                 throw new IllegalArgumentException("bit index " + (position * 8) + " out of bounds");
             }
 
-
             int bytePosition = currentArray.length - 1 - position / 8;
             if (newBitValue == null) {
                 out[bytePosition] ^= (1 << position % 8);

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

@@ -160,6 +160,35 @@ public void byteAt() throws Exception {
         }
     }
 
+    @Test
+    public void bitAt() throws Exception {
+        for (int i = 0; i < 8; i++) {
+            assertFalse(Bytes.allocate(1).bitAt(i));
+        }
+
+        for (int i = 0; i < 8; i++) {
+            assertTrue(Bytes.from((byte) 0xFF).bitAt(i));
+        }
+
+        assertFalse(Bytes.from((byte) 8).bitAt(0));
+        assertFalse(Bytes.from((byte) 8).bitAt(1));
+        assertFalse(Bytes.from((byte) 8).bitAt(2));
+        assertTrue(Bytes.from((byte) 8).bitAt(3));
+        assertFalse(Bytes.from((byte) 8).bitAt(4));
+
+        try {
+            Bytes.allocate(1).bitAt(8);
+            fail();
+        } catch (IndexOutOfBoundsException e) {
+        }
+
+        try {
+            Bytes.allocate(16).bitAt(-1);
+            fail();
+        } catch (IndexOutOfBoundsException e) {
+        }
+    }
+
     @Test
     public void count() throws Exception {
         assertEquals(0, Bytes.allocate(0).count((byte) 0));