Move shuffle and sort to additional transformers

Author: patrickfav

README.md

@@ -201,11 +201,25 @@ Bytes hash = Bytes.wrap(array).sha256();
 Bytes hash = Bytes.wrap(array).hash("MD5");
 ```
 
-**Checksum** can be calculated or automatically appended:
+Other transformers:
+
+```java
+Bytes result = Bytes.wrap(array).sort(myComparator);
+Bytes result = Bytes.wrap(array).reverse();
+```
+
+#### Additional Transformers
+
+More transformers can be accessed through the `BytesTransformers`, which
+can be statically imported for a less verbose syntax:
 
 ```java
 import static at.favre.lib.bytes.BytesTransformers.*;
+```
+
+**Checksum** can be calculated or automatically appended:
 
+```java
 Bytes.wrap(array).transform(checksumAppendCrc32());
 Bytes.wrap(array).transform(checksumCrc32());
 Bytes.wrap(array).transform(checksum(new Adler32(), ChecksumTransformer.Mode.TRANSFORM, 4));
@@ -214,18 +228,21 @@ Bytes.wrap(array).transform(checksum(new Adler32(), ChecksumTransformer.Mode.TRA
 **GZip compression** is supported by [`GZIPInputStream`](https://docs.oracle.com/javase/7/docs/api/java/util/zip/GZIPInputStream.html):
 
 ```java
-import static at.favre.lib.bytes.BytesTransformers.*;
-
 Bytes compressed = Bytes.wrap(array).transform(compressGzip());
 Bytes decompressed = compressed.transform(decompressGzip());
 ```
 
-Other transformers:
+**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(byteComparator));
+```
+
+**Shuffling** of individual bytes:
 
 ```java
-Bytes.wrap(array).shuffle();
-Bytes.wrap(array).sort(myComparator);
-Bytes.wrap(array).reverse();
+Bytes.wrap(array).transform(shuffle());
 ```
 
 ### Parser and Encoder for Binary-Text-Encodings

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

@@ -719,52 +719,6 @@ public Bytes reverse() {
         return transform(new BytesTransformer.ReverseTransformer());
     }
 
-    /**
-     * Sorts the internal byte array according to given comparator.
-     * <p>
-     * See the considerations about possible in-place operation in {@link #transform(BytesTransformer)}.
-     *
-     * @param comparator to sort the bytes
-     * @return sorted instance
-     */
-    public Bytes sort(Comparator<Byte> comparator) {
-        return transform(new BytesTransformer.SortTransformer(comparator));
-    }
-
-    /**
-     * Sorts the internal byte array with it's natural ordering
-     * <p>
-     * See the considerations about possible in-place operation in {@link #transform(BytesTransformer)}.
-     *
-     * @return sorted instance
-     */
-    public Bytes sort() {
-        return transform(new BytesTransformer.SortTransformer());
-    }
-
-    /**
-     * Shuffles the internal byte array
-     * <p>
-     * See the considerations about possible in-place operation in {@link #transform(BytesTransformer)}.
-     *
-     * @param random used to create entropy for the shuffle
-     * @return a shuffled instance
-     */
-    public Bytes shuffle(Random random) {
-        return transform(new BytesTransformer.ShuffleTransformer(random));
-    }
-
-    /**
-     * Shuffles the internal byte array with a new {@link SecureRandom} instance.
-     * <p>
-     * See the considerations about possible in-place operation in {@link #transform(BytesTransformer)}.
-     *
-     * @return a shuffled instance
-     */
-    public Bytes shuffle() {
-        return transform(new BytesTransformer.ShuffleTransformer(new SecureRandom()));
-    }
-
     /**
      * Copies the specified array, truncating or padding with zeros (if necessary)
      * so the copy has the specified length.  For all indices that are
@@ -782,7 +736,6 @@ public Bytes resize(int newByteLength) {
         return transform(new BytesTransformer.ResizeTransformer(newByteLength));
     }
 
-
     /**
      * Calculates sha256 on the underlying byte array and returns a byte instance containing the hash.
      *
@@ -794,17 +747,6 @@ public Bytes hashSha256() {
         return hash(BytesTransformer.MessageDigestTransformer.ALGORITHM_SHA_256);
     }
 
-    /**
-     * Calculates sha512 on the underlying byte array and returns a byte instance containing the hash.
-     *
-     * @return sha512 hash (64 bytes) of internal byte array
-     * @throws IllegalArgumentException if the message digest algorithm can not be found in the security providers
-     * @see <a href="https://en.wikipedia.org/wiki/Secure_Hash_Algorithms">Secure Hash Algorithms</a>
-     */
-    public Bytes hashSha512() {
-        return hash(BytesTransformer.MessageDigestTransformer.ALGORITHM_SHA_512);
-    }
-
     /**
      * Calculates hash with provided algorithm on the underlying byte array and returns a byte instance
      * containing the hash.

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

@@ -24,7 +24,7 @@
 import java.math.BigInteger;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
-import java.util.*;
+import java.util.Objects;
 
 /**
  * Interface for transforming {@link Bytes}
@@ -175,54 +175,6 @@ public byte[] transform(byte[] currentArray, boolean inPlace) {
         }
     }
 
-    /**
-     * Sorts the internal byte array with given {@link java.util.Comparator}
-     */
-    final class SortTransformer implements BytesTransformer {
-        private final Comparator<Byte> comparator;
-
-        SortTransformer() {
-            this(null);
-        }
-
-        SortTransformer(Comparator<Byte> comparator) {
-            this.comparator = comparator;
-        }
-
-        @Override
-        public byte[] transform(byte[] currentArray, boolean inPlace) {
-            if (comparator == null) {
-                byte[] out = inPlace ? currentArray : Bytes.from(currentArray).array();
-                Arrays.sort(out);
-                return out;
-            } else {
-                //no in-place implementation with comparator
-                List<Byte> list = Bytes.wrap(currentArray).toList();
-                Collections.sort(list, comparator);
-                return Bytes.from(list).array();
-            }
-        }
-    }
-
-    /**
-     * Shuffles the internal byte array
-     */
-    final class ShuffleTransformer implements BytesTransformer {
-        private final Random random;
-
-        ShuffleTransformer(Random random) {
-            Objects.requireNonNull(random, "passed random must not be null");
-            this.random = random;
-        }
-
-        @Override
-        public byte[] transform(byte[] currentArray, boolean inPlace) {
-            byte[] out = inPlace ? currentArray : Bytes.from(currentArray).array();
-            Util.shuffle(out, random);
-            return out;
-        }
-    }
-
     /**
      * Creates a new instance with a copy of the internal byte array and all other attributes.
      */

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

@@ -2,7 +2,8 @@
 
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
-import java.util.Objects;
+import java.security.SecureRandom;
+import java.util.*;
 import java.util.zip.CRC32;
 import java.util.zip.Checksum;
 import java.util.zip.GZIPInputStream;
@@ -16,6 +17,45 @@ public final class BytesTransformers {
     private BytesTransformers() {
     }
 
+    /**
+     * Create a {@link BytesTransformer} which shuffles the individual bytes in an array
+     * with an {@link SecureRandom} instance.
+     *
+     * @return transformer
+     */
+    public static BytesTransformer shuffle() {
+        return new ShuffleTransformer(new SecureRandom());
+    }
+
+    /**
+     * Create a {@link BytesTransformer} which shuffles the individual bytes in an array
+     *
+     * @param random to use for entropy
+     * @return transformer
+     */
+    public static BytesTransformer shuffle(Random random) {
+        return new ShuffleTransformer(random);
+    }
+
+    /**
+     * Create a {@link BytesTransformer} which sorts the internal byte array with it's natural ordering.
+     *
+     * @return transformer
+     */
+    public static BytesTransformer sort() {
+        return new SortTransformer();
+    }
+
+    /**
+     * Create a {@link BytesTransformer} which sorts the internal byte array according to given comparator.
+     *
+     * @param comparator to sort the bytes
+     * @return transformer
+     */
+    public static BytesTransformer sort(Comparator<Byte> comparator) {
+        return new SortTransformer(comparator);
+    }
+
     /**
      * Create a {@link BytesTransformer} which appends 4 byte Crc32 checksum to given bytes
      *
@@ -69,6 +109,54 @@ public static BytesTransformer decompressGzip() {
         return new GzipCompressor(false);
     }
 
+    /**
+     * Shuffles the internal byte array
+     */
+    final static class ShuffleTransformer implements BytesTransformer {
+        private final Random random;
+
+        ShuffleTransformer(Random random) {
+            Objects.requireNonNull(random, "passed random must not be null");
+            this.random = random;
+        }
+
+        @Override
+        public byte[] transform(byte[] currentArray, boolean inPlace) {
+            byte[] out = inPlace ? currentArray : Bytes.from(currentArray).array();
+            Util.shuffle(out, random);
+            return out;
+        }
+    }
+
+    /**
+     * Sorts the internal byte array with given {@link java.util.Comparator}
+     */
+    final static class SortTransformer implements BytesTransformer {
+        private final Comparator<Byte> comparator;
+
+        SortTransformer() {
+            this(null);
+        }
+
+        SortTransformer(Comparator<Byte> comparator) {
+            this.comparator = comparator;
+        }
+
+        @Override
+        public byte[] transform(byte[] currentArray, boolean inPlace) {
+            if (comparator == null) {
+                byte[] out = inPlace ? currentArray : Bytes.from(currentArray).array();
+                Arrays.sort(out);
+                return out;
+            } else {
+                //no in-place implementation with comparator
+                List<Byte> list = Bytes.wrap(currentArray).toList();
+                Collections.sort(list, comparator);
+                return Bytes.from(list).array();
+            }
+        }
+    }
+
     /**
      * Adds or converts to arbitrary checksum
      */
@@ -88,7 +176,7 @@ enum Mode {
         private final Mode mode;
         private final int checksumLengthByte;
 
-        public ChecksumTransformer(Checksum checksum, Mode mode, int checksumLengthByte) {
+        ChecksumTransformer(Checksum checksum, Mode mode, int checksumLengthByte) {
             if (checksumLengthByte <= 0 || checksumLengthByte > 8)
                 throw new IllegalArgumentException("checksumlength must be between 1 and 8 bytes");
 
@@ -117,7 +205,7 @@ public byte[] transform(byte[] currentArray, boolean inPlace) {
     final static class GzipCompressor implements BytesTransformer {
         private final boolean compress;
 
-        public GzipCompressor(boolean compress) {
+        GzipCompressor(boolean compress) {
             this.compress = compress;
         }
 

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

@@ -219,15 +219,14 @@ public void readOnlyShouldKeepProperty() throws Exception {
         assertTrue(b.reverse().isReadOnly());
         assertTrue(b.resize(7).isReadOnly());
         assertTrue(b.resize(6).isReadOnly());
-        assertTrue(b.sort().isReadOnly());
-        assertTrue(b.shuffle().isReadOnly());
         assertTrue(b.not().isReadOnly());
         assertTrue(b.leftShift(1).isReadOnly());
         assertTrue(b.rightShift(1).isReadOnly());
         assertTrue(b.and(Bytes.random(b.length())).isReadOnly());
         assertTrue(b.or(Bytes.random(b.length())).isReadOnly());
         assertTrue(b.xor(Bytes.random(b.length())).isReadOnly());
         assertTrue(b.append(3).isReadOnly());
+        assertTrue(b.hashSha256().isReadOnly());
     }
 
     @Test

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

@@ -208,23 +208,23 @@ public void copy() throws Exception {
     }
 
     @Test
-    public void shuffle() throws Exception {
-        assertArrayNotEquals(example_bytes_twentyfour, Bytes.from(example_bytes_twentyfour).shuffle().array());
-        assertArrayNotEquals(example_bytes_twentyfour, Bytes.from(example_bytes_twentyfour).shuffle(new SecureRandom()).array());
-        assertArrayNotEquals(new byte[24], Bytes.from(example_bytes_twentyfour).shuffle(new SecureRandom()).array());
+    public void shuffleTest() throws Exception {
+        assertArrayNotEquals(example_bytes_twentyfour, Bytes.from(example_bytes_twentyfour).transform(shuffle()).array());
+        assertArrayNotEquals(example_bytes_twentyfour, Bytes.from(example_bytes_twentyfour).transform(shuffle(new SecureRandom())).array());
+        assertArrayNotEquals(new byte[24], Bytes.from(example_bytes_twentyfour).transform(shuffle(new SecureRandom())).array());
     }
 
     @Test
-    public void sort() throws Exception {
+    public void sortTest() throws Exception {
         byte[] sorted = new byte[]{0, 1, 2, 3, 4, 5, 6};
-        assertArrayEquals(sorted, Bytes.from(sorted).shuffle().sort().array());
-        assertArrayEquals(sorted, Bytes.from(new byte[]{6, 0, 3, 4, 1, 5, 2}).sort().array());
-        assertArrayEquals(Bytes.from(sorted).reverse().array(), Bytes.from(new byte[]{6, 0, 3, 4, 1, 5, 2}).sort(new Comparator<Byte>() {
+        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>() {
             @Override
             public int compare(Byte o1, Byte o2) {
                 return o2.compareTo(o1);
             }
-        }).array());
+        })).array());
     }
 
     @Test
@@ -274,8 +274,8 @@ public void bitSwitchOutOfBounds() throws Exception {
     public void hash() throws Exception {
         assertEquals(Bytes.parseHex("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"), Bytes.from("").hashSha256());
         assertEquals(Bytes.parseHex("e362eea626386c93a54c9b82e6b896c0350fbff0ee12f284660253aac0908cfb"), Bytes.from("ö9h%6Ghh1\"").hashSha256());
-        assertEquals(Bytes.parseHex("cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e"), Bytes.from("").hashSha512());
-        assertEquals(Bytes.parseHex("106747C3DDC117091BEF8D21AEBAA8D314656D3AE1135AB36F4C0B07A264127CF625FE616751BEC66B43032B904E2D3B6C21BF14E078F6BB775A72503F48111D"), Bytes.from("ö9h%6Ghh1\"").hashSha512());
+        assertEquals(Bytes.parseHex("cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e"), Bytes.from("").hash("SHA-512"));
+        assertEquals(Bytes.parseHex("106747C3DDC117091BEF8D21AEBAA8D314656D3AE1135AB36F4C0B07A264127CF625FE616751BEC66B43032B904E2D3B6C21BF14E078F6BB775A72503F48111D"), Bytes.from("ö9h%6Ghh1\"").hash("SHA-512"));
         assertEquals(Bytes.parseHex("d41d8cd98f00b204e9800998ecf8427e"), Bytes.from("").hash("MD5"));
         assertEquals(Bytes.parseHex("ff38205f1cb22f588d8bc9ae21f22092"), Bytes.from("ö9h%6Ghh1\"").hash("MD5"));
     }