Add normalized utf-8 creator

Author: patrickfav

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

@@ -30,6 +30,7 @@
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 import java.security.SecureRandom;
+import java.text.Normalizer;
 import java.util.*;
 
 /**
@@ -40,7 +41,8 @@
  * <li>Helper functions like: indexOf, count, entropy</li>
  * <li>Transformations like: append, reverse, xor, and, resize, ...</li>
  * <li>Conversation to other types: primitives, List, object array, ByteBuffer, BigInteger, ...</li>
- * <li>Making it mutable</li>
+ * <li>Validation: built-in or provided</li>
+ * <li>Making it mutable or read-only</li>
  * </ul>
  * <p>
  * It supports byte ordering (little/big endianness).
@@ -61,7 +63,7 @@ public class Bytes implements Comparable<Bytes>, AbstractBytes {
     /* FACTORY ***************************************************************************************************/
 
     /**
-     * Creates a new instance with an empty array filled zeros.
+     * Creates a new instance with an empty array filled with zeros.
      *
      * @param length of the internal array
      * @return new instance
@@ -277,6 +279,17 @@ public static Bytes from(String utf8String) {
         return from(utf8String, StandardCharsets.UTF_8);
     }
 
+    /**
+     * Creates a new instance from normalized form of given utf-8 encoded string
+     *
+     * @param utf8String to get the internal byte array from
+     * @param form       to normalize, usually you want {@link java.text.Normalizer.Form#NFKD} for compatibility
+     * @return new instance
+     */
+    public static Bytes from(String utf8String, Normalizer.Form form) {
+        return from(Normalizer.normalize(utf8String, form), StandardCharsets.UTF_8);
+    }
+
     /**
      * Creates a new instance from given string
      *
@@ -363,7 +376,6 @@ public static Bytes random(int length) {
         return random(length, new SecureRandom());
     }
 
-
     /**
      * A new instance with random bytes.
      *
@@ -402,7 +414,10 @@ public static Bytes random(int length, Random random) {
     /* TRANSFORMER **********************************************************************************************/
 
     /**
-     * Creates a new instance with the current array appended with the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (ie. 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.
      *
      * @param bytes to append
      * @return appended instance
@@ -412,17 +427,17 @@ public Bytes append(Bytes bytes) {
     }
 
     /**
-     * Creates a new instance with the current array appended with the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
      *
      * @param singleByte to append
      * @return appended instance
      */
     public Bytes append(byte singleByte) {
-        return append(new byte[]{singleByte});
+        return append(Bytes.from(singleByte));
     }
 
     /**
-     * Creates a new instance with the current array appended with the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
      *
      * @param char2Bytes to append
      * @return appended instance
@@ -432,7 +447,7 @@ public Bytes append(char char2Bytes) {
     }
 
     /**
-     * Creates a new instance with the current array appended with the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
      *
      * @param short2Bytes to append
      * @return appended instance
@@ -442,7 +457,7 @@ public Bytes append(short short2Bytes) {
     }
 
     /**
-     * Creates a new instance with the current array appended with the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
      *
      * @param integer4Bytes to append
      * @return appended instance
@@ -452,7 +467,7 @@ public Bytes append(int integer4Bytes) {
     }
 
     /**
-     * Creates a new instance with the current array appended with the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
      *
      * @param long8Bytes to append
      * @return appended instance
@@ -462,7 +477,7 @@ public Bytes append(long long8Bytes) {
     }
 
     /**
-     * Creates a new instance with the current array appended with the provided data (ie. append at the end)
+     * Creates a new instance with the current array appended to the provided data (ie. append at the end)
      *
      * @param secondArray to append
      * @return appended instance
@@ -746,7 +761,7 @@ public boolean isEmpty() {
     }
 
     /**
-     * Get the set byte order or endianness. Default in Java is {@link ByteOrder#BIG_ENDIAN}.
+     * Get the set byte order/endianness. Default in Java is {@link ByteOrder#BIG_ENDIAN}.
      *
      * @return either {@link ByteOrder#BIG_ENDIAN} or {@link ByteOrder#LITTLE_ENDIAN}
      * @see <a href="https://en.wikipedia.org/wiki/Endianness">Endianness</a>
@@ -1132,7 +1147,7 @@ public BitSet toBitSet() {
     }
 
     /**
-     * If the underlying byte array is smaller than 1 byte / 8 bit returns unsigned two-complement
+     * If the underlying byte array is smaller than or equal to 1 byte / 8 bit returns unsigned two-complement
      * representation for a Java byte value.
      *
      * @return the byte representation
@@ -1147,7 +1162,7 @@ public byte toByte() {
     }
 
     /**
-     * If the underlying byte array is smaller than 2 byte / 16 bit returns unsigned two-complement
+     * If the underlying byte array is smaller than or equal to 2 byte / 16 bit returns unsigned two-complement
      * representation for a Java char integer value. The output is dependent on the set {@link #byteOrder()}.
      *
      * @return the int representation
@@ -1162,7 +1177,7 @@ public char toChar() {
     }
 
     /**
-     * If the underlying byte array is smaller than 2 byte / 16 bit returns signed two-complement
+     * If the underlying byte array is smaller than or equal to 2 byte / 16 bit returns signed two-complement
      * representation for a Java short integer value. The output is dependent on the set {@link #byteOrder()}.
      *
      * @return the int representation
@@ -1177,7 +1192,7 @@ public short toShort() {
     }
 
     /**
-     * If the underlying byte array is smaller than 4 byte / 32 bit returns signed two-complement
+     * If the underlying byte array is smaller than or equal to 4 byte / 32 bit returns signed two-complement
      * representation for a Java signed integer value. The output is dependent on the set {@link #byteOrder()}.
      *
      * @return the int representation
@@ -1192,7 +1207,7 @@ public int toInt() {
     }
 
     /**
-     * If the underlying byte array is smaller than 8 byte / 64 bit returns signed two-complement
+     * If the underlying byte array is smaller than or equal to 8 byte / 64 bit returns signed two-complement
      * representation for a Java signed long integer value. The output is dependent on the set {@link #byteOrder()}.
      *
      * @return the long representation

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

@@ -1,3 +1,24 @@
+/*
+ * Copyright 2017 Patrick Favre-Bulle
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
 package at.favre.lib.bytes;
 
 /**

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

@@ -1,3 +1,24 @@
+/*
+ * Copyright 2017 Patrick Favre-Bulle
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
 package at.favre.lib.bytes;
 
 /**

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

@@ -1,3 +1,24 @@
+/*
+ * Copyright 2017 Patrick Favre-Bulle
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
 package at.favre.lib.bytes;
 
 import org.junit.Test;

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

@@ -1,3 +1,24 @@
+/*
+ * Copyright 2017 Patrick Favre-Bulle
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
 package at.favre.lib.bytes;
 
 import org.junit.Test;

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

@@ -1,3 +1,24 @@
+/*
+ * Copyright 2017 Patrick Favre-Bulle
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
 package at.favre.lib.bytes;
 
 import org.junit.Test;