From b1df8caa0e464382281a450cc66734362556a975 Mon Sep 17 00:00:00 2001
From: Patrick Favre-Bulle <patrick@favre.at>
Date: Wed, 15 Feb 2023 19:25:47 +0100
Subject: [PATCH 1/2] Fix bugs found by sonar, mainly adding "& 0xff" to not
 promote int

---
 src/main/java/at/favre/lib/bytes/Base64.java | 2 +-
 src/main/java/at/favre/lib/bytes/Util.java   | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/main/java/at/favre/lib/bytes/Base64.java b/src/main/java/at/favre/lib/bytes/Base64.java
index 730c554..dd31fbf 100644
--- a/src/main/java/at/favre/lib/bytes/Base64.java
+++ b/src/main/java/at/favre/lib/bytes/Base64.java
@@ -93,7 +93,7 @@ static byte[] decode(CharSequence in) {
             }
 
             // Append this char's 6 bits to the word.
-            word = (word << 6) | (byte) bits;
+            word = (word << 6) | (byte) bits & 0xff;
 
             // For every 4 chars of input, we accumulate 24 bits of output. Emit 3 bytes.
             inCount++;
diff --git a/src/main/java/at/favre/lib/bytes/Util.java b/src/main/java/at/favre/lib/bytes/Util.java
index 710c4d3..4efb673 100644
--- a/src/main/java/at/favre/lib/bytes/Util.java
+++ b/src/main/java/at/favre/lib/bytes/Util.java
@@ -309,7 +309,7 @@ static byte[] shiftLeft(byte[] byteArray, int shiftBitCount, ByteOrder byteOrder
                         byte src = byteArray[sourceIndex];
                         byte dst = (byte) (src << shiftMod);
                         if (sourceIndex + 1 < byteArray.length) {
-                            dst |= byteArray[sourceIndex + 1] >>> (8 - shiftMod) & carryMask;
+                            dst |= byteArray[sourceIndex + 1] >>> (8 - shiftMod) & carryMask & 0xff;
                         }
                         byteArray[i] = dst;
                     }
@@ -323,7 +323,7 @@ static byte[] shiftLeft(byte[] byteArray, int shiftBitCount, ByteOrder byteOrder
                         byte src = byteArray[sourceIndex];
                         byte dst = (byte) (src << shiftMod);
                         if (sourceIndex - 1 >= 0) {
-                            dst |= byteArray[sourceIndex - 1] >>> (8 - shiftMod) & carryMask;
+                            dst |= byteArray[sourceIndex - 1] >>> (8 - shiftMod) & carryMask & 0xff;
                         }
                         byteArray[i] = dst;
                     }
@@ -365,7 +365,7 @@ static byte[] shiftRight(byte[] byteArray, int shiftBitCount, ByteOrder byteOrde
                         byte src = byteArray[sourceIndex];
                         byte dst = (byte) ((0xff & src) >>> shiftMod);
                         if (sourceIndex - 1 >= 0) {
-                            dst |= byteArray[sourceIndex - 1] << (8 - shiftMod) & carryMask;
+                            dst |= byteArray[sourceIndex - 1] << (8 - shiftMod) & carryMask & 0xff;
                         }
                         byteArray[i] = dst;
                     }
@@ -379,7 +379,7 @@ static byte[] shiftRight(byte[] byteArray, int shiftBitCount, ByteOrder byteOrde
                         byte src = byteArray[sourceIndex];
                         byte dst = (byte) ((0xff & src) >>> shiftMod);
                         if (sourceIndex + 1 < byteArray.length) {
-                            dst |= byteArray[sourceIndex + 1] << (8 - shiftMod) & carryMask;
+                            dst |= byteArray[sourceIndex + 1] << (8 - shiftMod) & carryMask & 0xff;
                         }
                         byteArray[i] = dst;
                     }

From cb0efd0233bcc8fa180704ee18c3f492b6099a59 Mon Sep 17 00:00:00 2001
From: Patrick Favre-Bulle <patrick@favre.at>
Date: Wed, 15 Feb 2023 19:41:29 +0100
Subject: [PATCH 2/2] Fix various issues mostly javadoc and typos and some
 simple code fixes

---
 .../java/at/favre/lib/bytes/BaseEncoding.java |  6 +-
 src/main/java/at/favre/lib/bytes/Bytes.java   | 76 +++++++++----------
 .../at/favre/lib/bytes/BytesTransformer.java  |  8 +-
 .../at/favre/lib/bytes/BytesTransformers.java | 10 +--
 .../at/favre/lib/bytes/BytesValidators.java   | 20 ++---
 .../java/at/favre/lib/bytes/MutableBytes.java |  8 +-
 src/main/java/at/favre/lib/bytes/Util.java    | 34 ++++-----
 7 files changed, 82 insertions(+), 80 deletions(-)

diff --git a/src/main/java/at/favre/lib/bytes/BaseEncoding.java b/src/main/java/at/favre/lib/bytes/BaseEncoding.java
index 8fe8d3e..8e23588 100644
--- a/src/main/java/at/favre/lib/bytes/BaseEncoding.java
+++ b/src/main/java/at/favre/lib/bytes/BaseEncoding.java
@@ -28,10 +28,10 @@
 
 /**
  * Encoder which supports arbitrary alphabet and padding.
- *
+ * <p>
  * Derived from Google Guava's common/io/ BaseEncoding
  * <p>
- * See: https://github.com/google/guava/blob/v26.0/guava/src/com/google/common/io/BaseEncoding.java
+ * See: <a href="https://github.com/google/guava/blob/v26.0/guava/src/com/google/common/io/BaseEncoding.java">BaseEncoding</a>
  */
 final class BaseEncoding implements BinaryToTextEncoding.EncoderDecoder {
     private static final char ASCII_MAX = 127;
@@ -190,7 +190,7 @@ char encode(int bits) {
         }
 
         int decode(char ch) {
-            return (int) decodabet[ch];
+            return decodabet[ch];
         }
     }
 
diff --git a/src/main/java/at/favre/lib/bytes/Bytes.java b/src/main/java/at/favre/lib/bytes/Bytes.java
index c2b5b20..33fb08d 100644
--- a/src/main/java/at/favre/lib/bytes/Bytes.java
+++ b/src/main/java/at/favre/lib/bytes/Bytes.java
@@ -31,7 +31,7 @@
 import java.util.*;
 
 /**
- * Bytes is wrapper class for an byte-array that allows a lot of convenience operations on it:
+ * "Bytes" is wrapper class for a byte-array that allows a lot of convenience operations on it:
  * <ul>
  * <li>Creation from various source: arrays, primitives, parsed or random</li>
  * <li>Encoding in many formats: hex, base64, etc.</li>
@@ -45,7 +45,7 @@
  * It supports byte ordering (little/big endianness).
  * <p>
  * This class is immutable as long as the internal array is not changed from outside (which can't be assured, when
- * using using <code>wrap()</code>). It is possible to create a mutable version (see {@link MutableBytes}).
+ * using <code>wrap()</code>). It is possible to create a mutable version (see {@link MutableBytes}).
  * <p>
  * <strong>Example:</strong>
  * <pre>
@@ -92,7 +92,7 @@ public static Bytes allocate(int length, byte defaultValue) {
     }
 
     /**
-     * Creates an Byte instance with an internal empty byte array. Same as calling {@link #allocate(int)} with 0.
+     * Creates a Byte instance with an internal empty byte array. Same as calling {@link #allocate(int)} with 0.
      *
      * @return the empty instance (always the same reference
      */
@@ -451,7 +451,7 @@ public static Bytes from(InputStream stream) {
 
     /**
      * Reads given input stream up to maxLength and creates a new instance from read data.
-     * Read maxLength is never longer than stream size (ie. maxLength is only limiting, not assuring maxLength)
+     * Read maxLength is never longer than stream size (i.e. maxLength is only limiting, not assuring maxLength)
      *
      * @param stream    to read from
      * @param maxLength read to this maxLength or end of stream
@@ -568,7 +568,7 @@ public static Bytes from(char[] charArray, Charset charset, int offset, int leng
 
     /**
      * Convert UUID to a newly generated 16 byte long array representation. Puts the 8 byte most significant bits and
-     * 8 byte least significant bits into an byte array.
+     * 8 byte the least significant bits into a byte array.
      *
      * @param uuid to convert to array
      * @return new instance
@@ -611,7 +611,7 @@ public static Bytes parseDec(CharSequence decString) {
      * Encodes with given radix string representation (e.g. radix 16 would be hex).
      * See also {@link BigInteger#toString(int)}.
      * <p>
-     * This is usually a number encoding, not a data encoding (ie. leading zeros are not preserved), but this implementation
+     * This is usually a number encoding, not a data encoding (i.e. leading zeros are not preserved), but this implementation
      * tries to preserve the leading zeros, to keep the in/output byte length size the same, but use at your own risk!
      *
      * @param radixNumberString the encoded string
@@ -628,7 +628,7 @@ public static Bytes parseRadix(CharSequence radixNumberString, int radix) {
      * <ul>
      *     <li>Upper- and lowercase <code>a-f</code> (also mixed case)</li>
      *     <li>Prefix with <code>0x</code> which will be ignored</li>
-     *     <li>Even and odd number of string length with auto zero padding (ie. 'E3F' is same as '0E3F')</li>
+     *     <li>Even and odd number of string length with auto zero padding (i.e. 'E3F' is same as '0E3F')</li>
      * </ul>
      *
      * @param hexString the encoded string
@@ -654,7 +654,7 @@ public static Bytes parseBase32(CharSequence base32Rfc4648String) {
     /**
      * Parsing of base36 encoded byte arrays.
      * <p>
-     * This is usually a number encoding, not a data encoding (ie. leading zeros are not preserved), but this implementation
+     * This is usually a number encoding, not a data encoding (i.e. leading zeros are not preserved), but this implementation
      * tries to preserve the leading zeros, to keep the in/output byte length size the same.
      *
      * @param base36String the encoded string
@@ -766,7 +766,7 @@ public static Bytes random(int length, Random random) {
     /* TRANSFORMER **********************************************************************************************/
 
     /**
-     * Creates a new instance with the current array appended to the provided data (ie. append at the end).
+     * Creates a new instance with the current array appended to the provided data (i.e. append at the end).
      * <p>
      * This will create a new byte array internally, so it is not suitable to use as extensive builder pattern -
      * use {@link ByteBuffer} or {@link java.io.ByteArrayOutputStream} for that.
@@ -779,7 +779,7 @@ public Bytes append(Bytes bytes) {
     }
 
     /**
-     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (i.e. append at the end)
      *
      * @param singleByte to append
      * @return appended instance
@@ -789,7 +789,7 @@ public Bytes append(byte singleByte) {
     }
 
     /**
-     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (i.e. append at the end)
      *
      * @param char2Bytes to append
      * @return appended instance
@@ -799,7 +799,7 @@ public Bytes append(char char2Bytes) {
     }
 
     /**
-     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (i.e. append at the end)
      *
      * @param short2Bytes to append
      * @return appended instance
@@ -809,7 +809,7 @@ public Bytes append(short short2Bytes) {
     }
 
     /**
-     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (i.e. append at the end)
      *
      * @param integer4Bytes to append
      * @return appended instance
@@ -819,7 +819,7 @@ public Bytes append(int integer4Bytes) {
     }
 
     /**
-     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (i.e. append at the end)
      *
      * @param long8Bytes to append
      * @return appended instance
@@ -829,7 +829,7 @@ public Bytes append(long long8Bytes) {
     }
 
     /**
-     * Creates a new instance with the current array appended to the provided data (ie. append at the end).
+     * Creates a new instance with the current array appended to the provided data (i.e. append at the end).
      * You may use this to append multiple byte arrays without the need for chaining the {@link #append(byte[])} call
      * and therefore generating intermediate copies of the byte array, making this approach use less memory.
      *
@@ -841,7 +841,7 @@ public Bytes append(byte[]... arrays) {
     }
 
     /**
-     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (i.e. append at the end)
      *
      * @param secondArray to append
      * @return appended instance
@@ -851,7 +851,7 @@ public Bytes append(byte[] secondArray) {
     }
 
     /**
-     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (i.e. append at the end)
      * <p>
      * If given array is null, the nothing will be appended.
      *
@@ -1004,7 +1004,7 @@ public Bytes rightShift(int shiftCount) {
     }
 
     /**
-     * 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)
+     * Returns a Byte whose value is equivalent to this Byte with the designated bit set to newBitValue. Bits start to count from the LSB (i.e. Bytes.from(0).switchBit(0,true) == 1)
      *
      * @param bitPosition not to confuse with byte position
      * @param newBitValue if true set to 1, 0 otherwise
@@ -1063,7 +1063,7 @@ public Bytes reverse() {
      * copy but not the original, the copy will contain {@code (byte)0}.
      * <p>
      * Resize from LSB or length, so an array [0,1,2,3] resized to 3 will result in [1,2,3] or resized to 5 [0,0,1,2,3].
-     * So when a 8 byte value resized to 4 byte will result in the same 32 bit integer value
+     * So when an 8 byte value resized to 4 byte will result in the same 32-bit integer value
      *
      * @param newByteLength the length of the copy to be returned
      * @return a copy with the desired size or "this" instance if newByteLength == current length
@@ -1099,7 +1099,7 @@ public Bytes resize(int newByteLength, BytesTransformer.ResizeTransformer.Mode m
      * Calculates md5 on the underlying byte array and returns a byte instance containing the hash.
      * This hash algorithm SHOULD be supported by every JVM implementation (see
      * <a href="https://docs.oracle.com/javase/7/docs/api/java/security/MessageDigest.html">Javadoc for MessageDigest</a>)
-     *
+     * <p>
      * <strong>Do not use this algorithm in security relevant applications.</strong>
      *
      * @return md5 (16 bytes) hash of internal byte array
@@ -1114,7 +1114,7 @@ public Bytes hashMd5() {
      * Calculates sha1 on the underlying byte array and returns a byte instance containing the hash.
      * This hash algorithm SHOULD be supported by every JVM implementation (see
      * <a href="https://docs.oracle.com/javase/7/docs/api/java/security/MessageDigest.html">Javadoc for MessageDigest</a>)
-     *
+     * <p>
      * <strong>Do not use this algorithm in security relevant applications.</strong>
      *
      * @return sha1 (20 bytes) hash of internal byte array
@@ -1151,9 +1151,9 @@ public Bytes hash(String algorithm) {
     /**
      * Generic transformation of this instance.
      * <p>
-     * This transformation might be done in-place (ie. without copying the internal array and overwriting its old state),
+     * This transformation might be done in-place (i.e. without copying the internal array and overwriting its old state),
      * or on a copy of the internal data, depending on the type (e.g. {@link MutableBytes}) and if the operation can be done
-     * in-place. Therefore the caller has to ensure that certain side-effects, which occur due to the changing of the internal
+     * in-place. Therefore, the caller has to ensure that certain side effects, which occur due to the changing of the internal
      * data, do not create bugs in his/her code. Usually immutability is preferred, but when handling many or big byte arrays,
      * mutability enables drastically better performance.
      *
@@ -1199,7 +1199,7 @@ public int length() {
     /**
      * The bit length of the underlying byte array.
      *
-     * @return bit length
+     * @return the bit length
      */
     public int lengthBit() {
         return length() * 8;
@@ -1227,7 +1227,7 @@ public ByteOrder byteOrder() {
     /**
      * Checks if instance is mutable
      *
-     * @return true if mutable, ie. transformers will change internal array
+     * @return true if mutable, i.e. transformers will change internal array
      */
     public boolean isMutable() {
         return false;
@@ -1384,7 +1384,7 @@ public boolean endsWith(byte[] subArray) {
      * <code>1000 0000</code> has <code>bitAt(0) == false</code> and <code>bitAt(7) == true</code>.
      *
      * @param bitIndex the index of the {@code bit} value.
-     * @return true if bit at given index is set, false otherwise
+     * @return true if the 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) {
@@ -1434,7 +1434,7 @@ public int unsignedByteAt(int index) {
      */
     public char charAt(int index) {
         Util.Validation.checkIndexBounds(length(), index, 2, "char");
-        return ((ByteBuffer) internalBuffer().position(index)).getChar();
+        return internalBuffer().position(index).getChar();
     }
 
     /**
@@ -1447,7 +1447,7 @@ public char charAt(int index) {
      */
     public short shortAt(int index) {
         Util.Validation.checkIndexBounds(length(), index, 2, "short");
-        return ((ByteBuffer) internalBuffer().position(index)).getShort();
+        return internalBuffer().position(index).getShort();
     }
 
     /**
@@ -1460,7 +1460,7 @@ public short shortAt(int index) {
      */
     public int intAt(int index) {
         Util.Validation.checkIndexBounds(length(), index, 4, "int");
-        return ((ByteBuffer) internalBuffer().position(index)).getInt();
+        return internalBuffer().position(index).getInt();
     }
 
     /**
@@ -1473,7 +1473,7 @@ public int intAt(int index) {
      */
     public long longAt(int index) {
         Util.Validation.checkIndexBounds(length(), index, 8, "long");
-        return ((ByteBuffer) internalBuffer().position(index)).getLong();
+        return internalBuffer().position(index).getLong();
     }
 
     /**
@@ -1606,7 +1606,7 @@ public InputStream inputStream() {
     /**
      * The reference of te internal byte-array. This call requires no conversation or additional memory allocation.
      * <p>
-     * Modifications to this bytes's content will cause the returned
+     * Modifications to these byte's content will cause the returned
      * array's content to be modified, and vice versa.
      *
      * @return the direct reference of the internal byte array
@@ -1662,12 +1662,12 @@ public String encodeDec() {
     /**
      * Encodes the internal array in given radix representation (e.g. 2 = binary, 10 = decimal, 16 = hex).
      * <p>
-     * This is usually a number encoding, not a data encoding (ie. leading zeros are not preserved), but this implementation
+     * This is usually a number encoding, not a data encoding (i.e. leading zeros are not preserved), but this implementation
      * tries to preserve the leading zeros, to keep the in/output byte length size the same. To preserve the length padding
      * would be required, but is not supported in this implementation.
      * <p>
      * But still full disclaimer:
-     *
+     * <p>
      * <strong>This is NOT recommended for data encoding, only for number encoding</strong>
      * <p>
      * See <a href="https://en.wikipedia.org/wiki/Radix_economy">Radix Economy</a> and {@link BigInteger#toString(int)}.
@@ -1868,7 +1868,7 @@ public BitSet toBitSet() {
      * 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 reversed and used as backing array with the big integer. Otherwise, the internal
      * array will be used directly.
      *
      * @return big integer
@@ -2005,7 +2005,7 @@ public long toLong() {
     }
 
     /**
-     * Converts the internal byte array to an long array, that is, every 8 bytes will be packed into a single long.
+     * Converts the internal byte array to a long array, that is, every 8 bytes will be packed into a single long.
      * <p>
      * E.g. 8 bytes will be packed to a length 1 long array:
      * <pre>
@@ -2037,7 +2037,7 @@ public float toFloat() {
     }
 
     /**
-     * Converts the internal byte array to an float array, that is, every 4 bytes will be packed into a single float.
+     * Converts the internal byte array to a float array, that is, every 4 bytes will be packed into a single float.
      * <p>
      * E.g. 4 bytes will be packed to a length 1 float array:
      * <pre>
@@ -2069,7 +2069,7 @@ public double toDouble() {
     }
 
     /**
-     * Converts the internal byte array to an double array, that is, every 8 bytes will be packed into a single double.
+     * Converts the internal byte array to a double array, that is, every 8 bytes will be packed into a single double.
      * <p>
      * E.g. 8 bytes will be packed to a length 1 double array:
      * <pre>
@@ -2178,7 +2178,7 @@ public boolean equals(byte[] anotherArray) {
      * will not break on the first mismatch. This method is useful to prevent some side-channel attacks,
      * but is slower on average.
      * <p>
-     * This implementation uses the algorithm suggested in https://codahale.com/a-lesson-in-timing-attacks/
+     * This implementation uses the algorithm suggested in <a href="https://codahale.com/a-lesson-in-timing-attacks/">a-lesson-in-timing-attacks</a>
      *
      * @param anotherArray to compare with
      * @return true if {@link Arrays#equals(byte[], byte[])} returns true on given and internal array
diff --git a/src/main/java/at/favre/lib/bytes/BytesTransformer.java b/src/main/java/at/favre/lib/bytes/BytesTransformer.java
index 22367d8..efdd12c 100644
--- a/src/main/java/at/favre/lib/bytes/BytesTransformer.java
+++ b/src/main/java/at/favre/lib/bytes/BytesTransformer.java
@@ -231,7 +231,7 @@ public boolean supportInPlaceTransformation() {
      * contain identical values.  For any indices that are valid in the
      * copy but not the original, the copy will contain {@code (byte)0}.
      * <p>
-     * If if the internal array will be grown, zero bytes will be added on the left,
+     * If the internal array will be increased, zero bytes will be added on the left,
      * keeping the value the same.
      */
     final class ResizeTransformer implements BytesTransformer {
@@ -265,10 +265,12 @@ public byte[] transform(byte[] currentArray, boolean inPlace) {
             byte[] resizedArray = new byte[newSize];
 
             if (mode == Mode.RESIZE_KEEP_FROM_MAX_LENGTH) {
+                int max = Math.max(0, Math.abs(newSize - currentArray.length));
+
                 if (newSize > currentArray.length) {
-                    System.arraycopy(currentArray, 0, resizedArray, Math.max(0, Math.abs(newSize - currentArray.length)), Math.min(newSize, currentArray.length));
+                    System.arraycopy(currentArray, 0, resizedArray, max, currentArray.length);
                 } else {
-                    System.arraycopy(currentArray, Math.max(0, Math.abs(newSize - currentArray.length)), resizedArray, Math.min(0, Math.abs(newSize - currentArray.length)), Math.min(newSize, currentArray.length));
+                    System.arraycopy(currentArray, max, resizedArray, 0, newSize);
                 }
             } else {
                 System.arraycopy(currentArray, 0, resizedArray, 0, Math.min(currentArray.length, resizedArray.length));
diff --git a/src/main/java/at/favre/lib/bytes/BytesTransformers.java b/src/main/java/at/favre/lib/bytes/BytesTransformers.java
index fc448c9..c1914c0 100644
--- a/src/main/java/at/favre/lib/bytes/BytesTransformers.java
+++ b/src/main/java/at/favre/lib/bytes/BytesTransformers.java
@@ -44,7 +44,7 @@ public static BytesTransformer shuffle(Random random) {
     }
 
     /**
-     * Create a {@link BytesTransformer} which sorts the internal byte array with it's natural ordering treating
+     * Create a {@link BytesTransformer} which sorts the internal byte array with its natural ordering treating
      * each byte as signed byte (-128...127). Using inplace sorting, this can be reasonable fast.
      *
      * @return transformer
@@ -54,9 +54,9 @@ public static BytesTransformer sort() {
     }
 
     /**
-     * Create a {@link BytesTransformer} which sorts the internal byte array with it's natural ordering treating
+     * Create a {@link BytesTransformer} which sorts the internal byte array with its natural ordering treating
      * each byte as unsigned byte (0...255). That is, the byte string {@code ff} sorts after {@code 00}.
-     *
+     * <p>
      * <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.
      *
@@ -68,7 +68,7 @@ public static BytesTransformer sortUnsigned() {
 
     /**
      * Create a {@link BytesTransformer} which sorts the internal byte array according to given comparator.
-     *
+     * <p>
      * <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.
      *
@@ -192,7 +192,7 @@ public boolean supportInPlaceTransformation() {
      * Sorts the internal byte array with given {@link java.util.Comparator}
      */
     public static final class SortTransformer implements BytesTransformer {
-        private final Comparator comparator;
+        private final Comparator<Byte> comparator;
 
         SortTransformer() {
             this(null);
diff --git a/src/main/java/at/favre/lib/bytes/BytesValidators.java b/src/main/java/at/favre/lib/bytes/BytesValidators.java
index acc2104..0d0f30f 100644
--- a/src/main/java/at/favre/lib/bytes/BytesValidators.java
+++ b/src/main/java/at/favre/lib/bytes/BytesValidators.java
@@ -37,7 +37,7 @@ private BytesValidators() {
      * Checks the length of a byte array
      *
      * @param byteLength to check against
-     * @return true if longer or equal to given value
+     * @return validator that returns true if longer or equal to given value
      */
     public static BytesValidator atLeast(int byteLength) {
         return new BytesValidator.Length(byteLength, BytesValidator.Length.Mode.GREATER_OR_EQ_THAN);
@@ -47,7 +47,7 @@ public static BytesValidator atLeast(int byteLength) {
      * Checks the length of a byte array
      *
      * @param byteLength to check against
-     * @return true if smaller or equal to given value
+     * @return validator that returns true if smaller or equal to given value
      */
     public static BytesValidator atMost(int byteLength) {
         return new BytesValidator.Length(byteLength, BytesValidator.Length.Mode.SMALLER_OR_EQ_THAN);
@@ -57,7 +57,7 @@ public static BytesValidator atMost(int byteLength) {
      * Checks the length of a byte array
      *
      * @param byteLength to check against
-     * @return true if equal to given value
+     * @return validator that returns true if equal to given value
      */
     public static BytesValidator exactLength(int byteLength) {
         return new BytesValidator.Length(byteLength, BytesValidator.Length.Mode.EXACT);
@@ -67,7 +67,7 @@ public static BytesValidator exactLength(int byteLength) {
      * Checks individual byte content
      *
      * @param refByte to check against
-     * @return true if array only consists of refByte
+     * @return validator that returns true if array only consists of refByte
      */
     public static BytesValidator onlyOf(byte refByte) {
         return new BytesValidator.IdenticalContent(refByte, BytesValidator.IdenticalContent.Mode.ONLY_OF);
@@ -77,7 +77,7 @@ public static BytesValidator onlyOf(byte refByte) {
      * Checks individual byte content
      *
      * @param refByte to check against
-     * @return true if array has at least one byte that is not refByte
+     * @return validator that returns true  if array has at least one byte that is not refByte
      */
     public static BytesValidator notOnlyOf(byte refByte) {
         return new BytesValidator.IdenticalContent(refByte, BytesValidator.IdenticalContent.Mode.NOT_ONLY_OF);
@@ -87,7 +87,7 @@ public static BytesValidator notOnlyOf(byte refByte) {
      * Checks if the internal byte array starts with given bytes
      *
      * @param startsWithBytes the supposed prefix
-     * @return true all startsWithBytes match the first bytes in the internal array
+     * @return validator that returns true all startsWithBytes match the first bytes in the internal array
      */
     public static BytesValidator startsWith(byte... startsWithBytes) {
         return new BytesValidator.PrePostFix(true, startsWithBytes);
@@ -97,7 +97,7 @@ public static BytesValidator startsWith(byte... startsWithBytes) {
      * Checks if the internal byte array ends with given bytes
      *
      * @param endsWithBytes the supposed postfix
-     * @return true all startsWithBytes match the first bytes in the internal array
+     * @return validator that returns true all startsWithBytes match the first bytes in the internal array
      */
     public static BytesValidator endsWith(byte... endsWithBytes) {
         return new BytesValidator.PrePostFix(false, endsWithBytes);
@@ -107,7 +107,7 @@ public static BytesValidator endsWith(byte... endsWithBytes) {
      * Checks individual byte content
      *
      * @param refByte to check against
-     * @return true if array has no value refByte
+     * @return validator that returns true if array has no value refByte
      */
     public static BytesValidator noneOf(byte refByte) {
         return new BytesValidator.IdenticalContent(refByte, BytesValidator.IdenticalContent.Mode.NONE_OF);
@@ -117,7 +117,7 @@ public static BytesValidator noneOf(byte refByte) {
      * This will execute all passed validators and returns true if at least one returns true (i.e. OR concatenation)
      *
      * @param validators at least one validator must be passed
-     * @return true if at least one validator returns true
+     * @return validator that returns true if at least one validator returns true
      */
     public static BytesValidator or(BytesValidator... validators) {
         return new BytesValidator.Logical(Arrays.asList(validators), BytesValidator.Logical.Operator.OR);
@@ -127,7 +127,7 @@ public static BytesValidator or(BytesValidator... validators) {
      * This will execute all passed validators and returns true if all return true (i.e. AND concatenation)
      *
      * @param validators at least one validator must be passed
-     * @return true if all return true
+     * @return validator that returns true if all return true
      */
     public static BytesValidator and(BytesValidator... validators) {
         return new BytesValidator.Logical(Arrays.asList(validators), BytesValidator.Logical.Operator.AND);
diff --git a/src/main/java/at/favre/lib/bytes/MutableBytes.java b/src/main/java/at/favre/lib/bytes/MutableBytes.java
index 530f002..270ae29 100644
--- a/src/main/java/at/favre/lib/bytes/MutableBytes.java
+++ b/src/main/java/at/favre/lib/bytes/MutableBytes.java
@@ -69,7 +69,7 @@ public boolean isMutable() {
      *
      * @param newArray used to overwrite internal
      * @return this instance
-     * @throws IndexOutOfBoundsException if newArray.length &gt; internal length
+     * @throws IndexOutOfBoundsException if newArray.length() &gt; internal length
      */
     public MutableBytes overwrite(byte[] newArray) {
         return overwrite(newArray, 0);
@@ -80,7 +80,7 @@ public MutableBytes overwrite(byte[] newArray) {
      *
      * @param newBytes used to overwrite internal
      * @return this instance
-     * @throws IndexOutOfBoundsException if newArray.length &gt; internal length
+     * @throws IndexOutOfBoundsException if newArray.length() &gt; internal length
      */
     public MutableBytes overwrite(Bytes newBytes) {
         return overwrite(newBytes, 0);
@@ -92,7 +92,7 @@ public MutableBytes overwrite(Bytes newBytes) {
      * @param newArray            used to overwrite internal
      * @param offsetInternalArray index of the internal array to start overwriting
      * @return this instance
-     * @throws IndexOutOfBoundsException if newArray.length + offsetInternalArray &gt; internal length
+     * @throws IndexOutOfBoundsException if newArray.length() + offsetInternalArray &gt; internal length
      */
     public MutableBytes overwrite(byte[] newArray, int offsetInternalArray) {
         Objects.requireNonNull(newArray, "must provide non-null array as source");
@@ -106,7 +106,7 @@ public MutableBytes overwrite(byte[] newArray, int offsetInternalArray) {
      * @param newBytes            used to overwrite internal
      * @param offsetInternalArray index of the internal array to start overwriting
      * @return this instance
-     * @throws IndexOutOfBoundsException if newBytes.length + offsetInternalArray &gt; internal length
+     * @throws IndexOutOfBoundsException if newBytes.length() + offsetInternalArray &gt; internal length
      */
     public MutableBytes overwrite(Bytes newBytes, int offsetInternalArray) {
         return overwrite(Objects.requireNonNull(newBytes, "must provide non-null array as source").array(), offsetInternalArray);
diff --git a/src/main/java/at/favre/lib/bytes/Util.java b/src/main/java/at/favre/lib/bytes/Util.java
index 4efb673..ac234bb 100644
--- a/src/main/java/at/favre/lib/bytes/Util.java
+++ b/src/main/java/at/favre/lib/bytes/Util.java
@@ -163,7 +163,7 @@ static int lastIndexOf(byte[] array, byte target, int start, int end) {
         }
 
         /**
-         * Counts the occurrence of target in the the in the subject array
+         * Counts the occurrence of target in the subject array
          *
          * <p>
          * <strong>Analysis</strong>
@@ -189,7 +189,7 @@ static int countByte(byte[] array, byte target) {
         }
 
         /**
-         * Counts the times given pattern (ie. an array) can be found in given array
+         * Counts the times given pattern (i.e. an array) can be found in given array
          *
          * <p>
          * <strong>Analysis</strong>
@@ -226,7 +226,7 @@ static int countByteArray(byte[] array, byte[] pattern) {
          * Simple Durstenfeld shuffle.
          * This will shuffle given array and will not make a copy, so beware.
          * <p>
-         * See: https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm
+         * See: <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm">Yates_shuffle</a>
          *
          * <p>
          * <strong>Analysis</strong>
@@ -418,7 +418,7 @@ static boolean constantTimeEquals(byte[] array, byte[] anotherArray) {
          * Calculates the entropy factor of a byte array.
          * <p>
          * This implementation will not create a copy of the internal array and will only internally initialize
-         * a int array with 256 elements as temporary buffer.
+         * an int array with 256 elements as temporary buffer.
          *
          * <p>
          * <strong>Analysis</strong>
@@ -496,7 +496,7 @@ static byte[] toArray(Collection<java.lang.Byte> collection) {
         }
 
         /**
-         * Converts this primitive array to an boxed object array.
+         * Converts this primitive array to a boxed object array.
          * Will create a new array and not reuse the array reference.
          *
          * <p>
@@ -544,7 +544,7 @@ static List<java.lang.Byte> toList(byte[] array) {
         }
 
         /**
-         * Converts this object array to an primitives type array.
+         * Converts this object array to a primitives type array.
          * Will create a new array and not reuse the array reference.
          *
          * <p>
@@ -717,7 +717,7 @@ static byte[] toByteArray(double[] doubleArray) {
          * @param charArray to get the byte array from
          * @param charset   charset to be used to decode the char array
          * @param offset    to start reading the char array from (must be smaller than length and gt 0)
-         * @param length    from offset (must be between 0 and charArray.length)
+         * @param length    from offset (must be between 0 and charArray.length())
          * @return byte array of encoded chars
          */
         static byte[] charToByteArray(char[] charArray, Charset charset, int offset, int length) {
@@ -807,7 +807,7 @@ static int[] toIntArray(byte[] bytes, ByteOrder byteOrder) {
         }
 
         /**
-         * Converts the byte array to an long array. This will spread 8 bytes into a single long:
+         * Converts the byte array to a long array. This will spread 8 bytes into a single long:
          *
          * <pre>
          *     [b1, b2, b3, b4, b5, b6, b7, b8] = [long1]
@@ -834,7 +834,7 @@ static long[] toLongArray(byte[] bytes, ByteOrder byteOrder) {
         }
 
         /**
-         * Converts the byte array to an float array. This will spread 4 bytes into a single float:
+         * Converts the byte array to a float array. This will spread 4 bytes into a single float:
          *
          * <pre>
          *     [b1, b2, b3, b4] = [float1]
@@ -861,7 +861,7 @@ static float[] toFloatArray(byte[] bytes, ByteOrder byteOrder) {
         }
 
         /**
-         * Converts the byte array to an double array. This will spread 8 bytes into a single double:
+         * Converts the byte array to a double array. This will spread 8 bytes into a single double:
          *
          * <pre>
          *     [b1, b2, b3, b4, b5, b6, b7, b8] = [double1]
@@ -916,7 +916,7 @@ static short[] toShortArray(byte[] bytes, ByteOrder byteOrder) {
 
         /**
          * Convert UUID to a newly generated 16 byte long array representation. Puts the 8 byte most significant bits and
-         * 8 byte least significant bits into an byte array.
+         * 8 byte least-significant bits into a byte array.
          *
          * <p>
          * <strong>Analysis</strong>
@@ -1034,13 +1034,13 @@ private Validation() {
         }
 
         /**
-         * Check if a length of an primitive (e.g. int = 4 byte) fits in given length from given start index.
+         * Check if a length of a primitive (e.g. int = 4 byte) fits in given length from given start index.
          * Throws exception with descriptive exception message.
          *
          * @param length          of the whole array
          * @param index           to start from array length
          * @param primitiveLength length of the primitive type to check
-         * @param type            for easier debugging the human readable type of the checked primitive
+         * @param type            for easier debugging the human-readable type of the checked primitive
          *                        to put in exception message
          * @throws IndexOutOfBoundsException if index + primitiveLength > length
          */
@@ -1056,7 +1056,7 @@ static void checkIndexBounds(int length, int index, int primitiveLength, String
          *
          * @param length         of the whole array
          * @param expectedLength how length is expected
-         * @param type           for easier debugging the human readable type of the checked primitive
+         * @param type           for easier debugging the human-readable type of the checked primitive
          *                       to put in exception message
          * @throws IllegalArgumentException if length != expectedLength
          */
@@ -1073,7 +1073,7 @@ static void checkExactLength(int length, int expectedLength, String type) {
          *
          * @param length       of the byte array
          * @param modFactor    to divide the length
-         * @param errorSubject human readable message of the exact error subject
+         * @param errorSubject human-readable message of the exact error subject
          * @throws IllegalArgumentException if length % modFactor != 0
          */
         static void checkModLength(int length, int modFactor, String errorSubject) {
@@ -1086,7 +1086,7 @@ static void checkModLength(int length, int modFactor, String errorSubject) {
          * Check if the file exists and is a file.
          *
          * @param file to check
-         * @throws IllegalArgumentException if either file is null, does not exists or is not a file
+         * @throws IllegalArgumentException if either file is null, does not exist or is not a file
          */
         private static void checkFileExists(java.io.File file) {
             if (file == null || !file.exists() || !file.isFile()) {
@@ -1181,7 +1181,7 @@ static byte[] readFromFile(java.io.File file) {
          * @param file   to read bytes from
          * @param offset to read
          * @param length from offset
-         * @return byte array with length length
+         * @return byte array with length
          */
         static byte[] readFromFile(java.io.File file, int offset, int length) {
             Validation.checkFileExists(file);