Add unsigned sort transformer

fixes #17

Author: patrickfav

CHANGELOG

@@ -11,6 +11,7 @@
  * add `startsWith()` and `endsWidth()` methods #12
  * add cache for calculating the hashCode
  * add HMAC byte transformer #11
+ * add unsigned sort transformer #17
 
 ## v0.6.0
 

README.md

@@ -271,7 +271,8 @@ Bytes decompressed = compressed.transform(decompressGzip());
 **Sorting** of individual bytes with either [`Comparator`](https://docs.oracle.com/javase/7/docs/api/java/util/Comparator.html) or natural order:
 
 ```java
-Bytes.wrap(array).transform(sort());
+Bytes.wrap(array).transform(sort()); // 0x00 sorts after 0xff
+Bytes.wrap(array).transform(sortUnsigned()); // 0xff sorts after 0x00
 Bytes.wrap(array).transform(sort(byteComparator));
 ```
 

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

@@ -21,11 +21,7 @@
 
 package at.favre.lib.bytes;
 
-import java.io.ByteArrayInputStream;
-import java.io.DataInput;
-import java.io.File;
-import java.io.InputStream;
-import java.io.Serializable;
+import java.io.*;
 import java.math.BigInteger;
 import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
@@ -35,14 +31,7 @@
 import java.nio.charset.StandardCharsets;
 import java.security.SecureRandom;
 import java.text.Normalizer;
-import java.util.Arrays;
-import java.util.BitSet;
-import java.util.Collection;
-import java.util.Iterator;
-import java.util.List;
-import java.util.Objects;
-import java.util.Random;
-import java.util.UUID;
+import java.util.*;
 
 /**
  * Bytes is wrapper class for an byte-array that allows a lot of convenience operations on it:
@@ -67,6 +56,10 @@
  *     b.not();
  *     System.out.println(b.encodeHex());
  * </pre>
+ *
+ * <h3>Comparable</h3>
+ * The implemented comparator treats the bytes as signed bytes. If you want to sort, treating each byte as unsigned,
+ * use {@link BytesTransformers#sortUnsigned()}.
  */
 @SuppressWarnings("WeakerAccess")
 public class Bytes implements Comparable<Bytes>, Serializable, Iterable<Byte> {

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

@@ -44,17 +44,34 @@ public static BytesTransformer shuffle(Random random) {
     }
 
     /**
-     * Create a {@link BytesTransformer} which sorts the internal byte array with it's natural ordering.
+     * Create a {@link BytesTransformer} which sorts the internal byte array with it's natural ordering treating
+     * each byte as signed byte (-128...127). Using inplace sorting, this can be reasonable fast.
      *
      * @return transformer
      */
     public static BytesTransformer sort() {
         return new SortTransformer();
     }
 
+    /**
+     * Create a {@link BytesTransformer} which sorts the internal byte array with it's natural ordering treating
+     * each byte as unsigned byte (0...255). That is, the byte string {@code ff} sorts after {@code 00}.
+     *
+     * <strong>Note:</strong> this requires 2 copies of the internal array and a lot of unboxing due to
+     * the fact that no primitives are not allowed as generic type arguments - so only use on small arrays.
+     *
+     * @return transformer
+     */
+    public static BytesTransformer sortUnsigned() {
+        return new SortTransformer(new SortTransformer.UnsignedByteComparator());
+    }
+
     /**
      * Create a {@link BytesTransformer} which sorts the internal byte array according to given comparator.
      *
+     * <strong>Note:</strong> this requires 2 copies of the internal array and a lot of unboxing due to
+     * the fact that no primitives are not allowed as generic type arguments - so only use on small arrays.
+     *
      * @param comparator to sort the bytes
      * @return transformer
      */
@@ -168,6 +185,7 @@ public byte[] transform(byte[] currentArray, boolean inPlace) {
         public boolean supportInPlaceTransformation() {
             return true;
         }
+
     }
 
     /**
@@ -202,26 +220,26 @@ public byte[] transform(byte[] currentArray, boolean inPlace) {
         public boolean supportInPlaceTransformation() {
             return comparator == null;
         }
+
+        /**
+         * Converting each byte into unsinged version and comparing it (0...255) vs (-128..127)
+         */
+        static final class UnsignedByteComparator implements Comparator<Byte> {
+            @Override
+            public int compare(Byte o1, Byte o2) {
+                int byteA = o1 & 0xff;
+                int byteB = o2 & 0xff;
+                if (byteA == byteB) return 0;
+                return byteA < byteB ? -1 : 1;
+            }
+        }
+
     }
 
     /**
      * Adds or converts to arbitrary checksum
      */
     public static final class ChecksumTransformer implements BytesTransformer {
-        /**
-         * Definitions of the mode
-         */
-        public enum Mode {
-            /**
-             * Appends checksum to given byte array
-             */
-            APPEND,
-            /**
-             * Transforms byte array and returns only checksum
-             */
-            TRANSFORM
-        }
-
         private final Checksum checksum;
         private final Mode mode;
         private final int checksumLengthByte;
@@ -252,6 +270,20 @@ public byte[] transform(byte[] currentArray, boolean inPlace) {
         public boolean supportInPlaceTransformation() {
             return false;
         }
+
+        /**
+         * Definitions of the mode
+         */
+        public enum Mode {
+            /**
+             * Appends checksum to given byte array
+             */
+            APPEND,
+            /**
+             * Transforms byte array and returns only checksum
+             */
+            TRANSFORM
+        }
     }
 
     /**

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

@@ -497,8 +497,8 @@ static ByteBuffer getBytesFromUUID(UUID uuid) {
     /**
      * Hashcode implementation for a byte array and given byte order
      *
-     * @param byteArray
-     * @param byteOrder
+     * @param byteArray to calculate hashCode of
+     * @param byteOrder to calculate hashCode of
      * @return hashCode
      */
     static int hashCode(byte[] byteArray, ByteOrder byteOrder) {

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

@@ -270,16 +270,26 @@ public void shuffleTest() {
     }
 
     @Test
-    public void sortTest() {
-        byte[] sorted = new byte[]{0, 1, 2, 3, 4, 5, 6};
+    public void sortSignedTest() {
+        byte[] sorted = new byte[]{-2, -1, 0, 1, 2, 3, 4, 5, 6};
         assertArrayEquals(sorted, Bytes.from(sorted).transform(shuffle()).transform(sort()).array());
-        assertArrayEquals(sorted, Bytes.from(new byte[]{6, 0, 3, 4, 1, 5, 2}).transform(sort()).array());
-        assertArrayEquals(Bytes.from(sorted).reverse().array(), Bytes.from(new byte[]{6, 0, 3, 4, 1, 5, 2}).transform(sort(new Comparator<Byte>() {
+        assertArrayEquals(sorted, Bytes.from(new byte[]{6, 0, 3, -2, -1, 4, 1, 5, 2}).transform(sort()).array());
+        assertArrayEquals(Bytes.from(sorted).reverse().array(), Bytes.from(new byte[]{6, -2, -1, 0, 3, 4, 1, 5, 2}).transform(sort(new Comparator<Byte>() {
             @Override
             public int compare(Byte o1, Byte o2) {
                 return o2.compareTo(o1);
             }
         })).array());
+
+        byte[] checkSignedSorted = new byte[]{(byte) 0x80, (byte) 0xFE, (byte) 0xFF, 0x00, 0x01};
+        assertArrayEquals(checkSignedSorted, Bytes.from(checkSignedSorted).transform(shuffle()).transform(sort()).array());
+    }
+
+    @Test
+    public void sortUnsignedTest() {
+        byte[] sorted = new byte[]{0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, (byte) 0x80, (byte) 0xAE, (byte) 0xFF};
+        assertArrayEquals(sorted, Bytes.from(sorted).transform(shuffle()).transform(sortUnsigned()).array());
+        assertArrayEquals(sorted, Bytes.from(new byte[]{(byte) 0x80, (byte) 0xAE, (byte) 0xFF, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06}).transform(sortUnsigned()).array());
     }
 
     @Test