Add to unsigned conversations

Author: patrickfav

CHANGELOG

@@ -3,6 +3,7 @@
 ## v0.4.4
 
 * add feature for gathering parts of the array as primitives (e.g. intAt(int position))
+* add to unsigned byte conversations
 
 ## v0.4.3
 

README.md

@@ -318,7 +318,8 @@ Accessing part of the array as primitives from arbitrary position:
 
 ```java
 Bytes.wrap(array).bitAt(4); // 0010 1000 -> false
-Bytes.wrap(array).byteAt(14);
+Bytes.wrap(array).byteAt(14); // 1111 1111 -> -1
+Bytes.wrap(array).unsignedByteAt(14); // 1111 1111 -> 255
 Bytes.wrap(array).intAt(4);
 Bytes.wrap(array).longAt(6);
 ```
@@ -420,6 +421,7 @@ To primitives (if the internal array is not too long)
 
 ```java
 Bytes.wrap(array).toByte();
+Bytes.wrap(array).toUnsignedByte();
 Bytes.wrap(array).toInt();
 Bytes.wrap(array).toDouble();
 ```

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

@@ -960,9 +960,7 @@ public int lastIndexOf(byte target) {
      * @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 > lengthBit()) {
-            throw new IndexOutOfBoundsException("cannot get bit from index out of bounds: " + bitIndex);
-        }
+        Util.checkIndexBounds(lengthBit(), bitIndex, 1, "bit");
         return ((byteAt(length() - 1 - (bitIndex / 8)) >>> bitIndex % 8) & 1) != 0;
     }
 
@@ -976,12 +974,24 @@ public boolean bitAt(int bitIndex) {
      * @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()) {
-            throw new IndexOutOfBoundsException("cannot get byte from index out of bounds: " + index);
-        }
+        Util.checkIndexBounds(length(), index, 1, "byte");
         return internalArray()[index];
     }
 
+    /**
+     * Returns the unsigned {@code byte} value at the specified index as an int.
+     * An index ranges from {@code 0} to {@code length() - 1}. The first {@code char} value of the sequence
+     * is at index {@code 0}, the next at index {@code 1}, and so on, as for array indexing.
+     *
+     * @param index the index of the unsigned {@code byte} value.
+     * @return the unsigned {@code byte} value at the specified index of the underlying byte array as type 4 byte integer
+     * @throws IndexOutOfBoundsException if the {@code index} argument is negative or not less than the length of this array.
+     */
+    public int unsignedByteAt(int index) {
+        Util.checkIndexBounds(length(), index, 1, "unsigned byte");
+        return 0xff & internalArray()[index];
+    }
+
     /**
      * Returns the {@code char} value at the specified index.
      * Reads the primitive from given index and the following byte and interprets it according to byte order.
@@ -1334,7 +1344,7 @@ public BigInteger toBigInteger() {
     }
 
     /**
-     * If the underlying byte array is exactly 1 byte / 8 bit long, returns unsigned two-complement
+     * If the underlying byte array is exactly 1 byte / 8 bit long, returns signed two-complement
      * representation for a Java byte value.
      * <p>
      * If you just want to get the first element as {@code byte}, see {@link #byteAt(int)}, using index zero.
@@ -1348,6 +1358,21 @@ public byte toByte() {
         return internalArray()[0];
     }
 
+    /**
+     * If the underlying byte array is exactly 1 byte / 8 bit long, returns unsigned two-complement
+     * representation for a Java byte value wrapped in an 4 byte int.
+     * <p>
+     * If you just want to get the first element as {@code byte}, see {@link #byteAt(int)}, using index zero.
+     *
+     * @return the unsigned byte representation wrapped in an int
+     * @throws IllegalStateException if byte array has length not equal to 1
+     * @see <a href="https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html">Primitive Types</a>
+     */
+    public int toUnsignedByte() {
+        Util.checkExactLength(length(), 1, "unsigned byte");
+        return unsignedByteAt(0);
+    }
+
     /**
      * If the underlying byte array is exactly 2 byte / 16 bit long, return unsigned two-complement
      * representation for a Java char integer value. The output is dependent on the set {@link #byteOrder()}.

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

@@ -190,6 +190,7 @@ public void bitAt() throws Exception {
     public void byteAt() throws Exception {
         assertEquals(0, Bytes.allocate(1).byteAt(0));
         assertEquals(0, Bytes.allocate(128).byteAt(127));
+        assertEquals(-1, Bytes.from((byte) 0b1111_1111).byteAt(0));
 
         for (int i = 0; i < example_bytes_twentyfour.length; i++) {
             assertEquals(example_bytes_twentyfour[i], Bytes.wrap(example_bytes_twentyfour).byteAt(i));
@@ -208,6 +209,25 @@ public void byteAt() throws Exception {
         }
     }
 
+    @Test
+    public void unsignedByteAt() throws Exception {
+        assertEquals(0, Bytes.allocate(1).unsignedByteAt(0));
+        assertEquals(0, Bytes.allocate(128).unsignedByteAt(127));
+        assertEquals(255, Bytes.from((byte) 0b1111_1111).unsignedByteAt(0));
+
+        try {
+            Bytes.allocate(1).unsignedByteAt(1);
+            fail();
+        } catch (IndexOutOfBoundsException ignored) {
+        }
+
+        try {
+            Bytes.allocate(16).unsignedByteAt(-1);
+            fail();
+        } catch (IndexOutOfBoundsException ignored) {
+        }
+    }
+
     @Test
     public void charAt() throws Exception {
         assertEquals(0, Bytes.allocate(2).charAt(0));

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

@@ -79,6 +79,7 @@ public void toBitSet() throws Exception {
     public void toByte() throws Exception {
         assertEquals(example_bytes_one[0], Bytes.from(example_bytes_one).toByte());
         assertEquals((byte) 0, Bytes.from(new byte[1]).toByte());
+        assertEquals(-1, Bytes.from((byte) 0b1111_1111).toByte());
 
         try {
             Bytes.from(example_bytes_two).toByte();
@@ -87,6 +88,19 @@ public void toByte() throws Exception {
         }
     }
 
+    @Test
+    public void toUnsignedByte() throws Exception {
+        assertEquals(example_bytes_one[0], Bytes.from(example_bytes_one).toUnsignedByte());
+        assertEquals((byte) 0, Bytes.from(new byte[1]).toUnsignedByte());
+        assertEquals(255, Bytes.from((byte) 0b1111_1111).toUnsignedByte());
+
+        try {
+            Bytes.from(example_bytes_two).toUnsignedByte();
+            fail();
+        } catch (IllegalStateException ignored) {
+        }
+    }
+
     @Test
     public void toChar() throws Exception {
         assertEquals(6767, Bytes.from(example_bytes_two).toChar());