#37 javadoc: arrays

assira.core/src/main/java/net/ranides/assira/collection/arrays/ArraySearch.java

@@ -19,7 +19,7 @@ import java.util.function.Predicate;
  *
  * Please note, that many times, methods accepts any type A as "array" and any type T as component.
  * It is responsibility of the caller to pass reasonable objects.
- * Generic declarations try to help in writing code without explicit cast, but at the cost of type safety.
+ * Generic declarations inferring types helps in writing code without explicit cast, but at the cost of type safety.
  *
  * Boxing and unboxing is supported.
  */
@@ -27,7 +27,7 @@ import java.util.function.Predicate;
     "PMD.AvoidReassigningParameters"
 })
 @UtilityClass
-public final class ArraySearch {
+public class ArraySearch {
 
     /**
      * Returns true, if array contains value.
@@ -98,6 +98,7 @@ public final class ArraySearch {
 
     /**
      * Returns last element matching predicate. Searches only inside specified range.
+     *
      * @param array array
      * @param begin begin
      * @param end end

assira.core/src/main/java/net/ranides/assira/collection/arrays/ArrayUtils.java

@@ -223,7 +223,7 @@ public final class ArrayUtils {
     }
 
     /**
-     * Finds [begin] and [end] elements and copies them, including [begin].
+     * Finds [begin] and [end] elements and copies content between them, including [begin].
      * It uses cmp function for search.
      *
      * @param values array

assira.core/src/main/java/net/ranides/assira/collection/arrays/IntArrays.java

@@ -6,29 +6,49 @@
  */
 package net.ranides.assira.collection.arrays;
 
+import lombok.experimental.UtilityClass;
 import net.ranides.assira.collection.iterators.IntListIterator;
 import net.ranides.assira.collection.iterators.RandomAccessIntIterator;
 import net.ranides.assira.collection.lists.IntList;
 import net.ranides.assira.collection.lists.NativeArrayList;
 
 /**
+ * Trivial methods for conversion int[] arrays into type-specific IntList, IntIterator etc
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */
-public final class IntArrays {
-    
-    private IntArrays() {
-        /* utility class */
-    }
-    
+@UtilityClass
+public class IntArrays {
+
+    /**
+     * Returns IntList view which reflects provided values.
+     * It is vararg method, but it can takes int[] too. Changes inside array will be visible in IntList.
+     *
+     * @param array array
+     * @return view
+     */
     public static IntList asList(int... array) {
 		return NativeArrayList.wrap(array);
 	}
-    
+
+    /**
+     * Returns IntListIterator traversing provided array
+     *
+     * @param array array
+     * @return iterator
+     */
     public static IntListIterator iterator(int[] array) {
         return iterator(array, 0, array.length);
     }
-    
+
+    /**
+     * Returns IntListIterator traversing provided array fragment
+     *
+     * @param array array
+     * @param begin begin
+     * @param end end
+     * @return iterator
+     */
     public static IntListIterator iterator(int[] array, int begin, int end) {
         return new RandomAccessIntIterator() {
             @Override

assira.core/src/main/java/net/ranides/assira/collection/arrays/NativeArray.java

@@ -8,8 +8,10 @@ package net.ranides.assira.collection.arrays;
 
 import java.io.Serializable;
 import java.lang.reflect.Array;
+import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Comparator;
+import java.util.List;
 import java.util.function.IntPredicate;
 import net.ranides.assira.collection.IntComparator;
 import net.ranides.assira.collection.Swapper;
@@ -18,43 +20,142 @@ import net.ranides.assira.reflection.util.ClassTraits;
 import net.ranides.assira.reflection.util.ClassUtils;
 
 /**
+ * NativeArray is a class which wraps any array (especially primitive array) and gives possibility to
+ * work with array in generic way (all boxing operations are done internally).
+ *
+ * It defines a bunch of methods for optimized comparing elements.
+ * For example, you can create IntPredicate for value "x" which checks if item at some index equals "x".
+ * Those predicate won't do unboxing over and over again. It will select optimized primitive operation.
+ *
+ * You can create those kind of comparators for
+ *      equality: value == array[index]
+ *      left comparison: compareTo(value, array[index])
+ *      right comparison: compareTo(array[index], value)
+ *
+ * You can create optimized comparator between array elements:
+ *      comparator(array) will return IntComparator which takes array indexes and compares elements inside array.
+ *
+ * You can create optimized function for moving elements from one array to another:
+ *      moveTo(target) will represent operation target[index] = source[index]
+ *      moveFrom(source) will represent operation source[index] = target[index]
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */
 public abstract class NativeArray implements Swapper, Comparable<NativeArray>, Cloneable, Serializable {
     
     private static final long serialVersionUID = 1L;
-    
+
+    /**
+     * Creates new array of the same type but different size.
+     * It is not copy or clone operation, it takes only component type from current array.
+     *
+     * @param size size
+     * @return NativeArray
+     */
     public abstract NativeArray allocate(int size);
-    
+
+    /**
+     * Returns array wrapped inside this object.
+     *
+     * @return array
+     */
     public abstract Object array();
-    
+
+    /**
+     * Returns array wrapped inside this object.
+     * It infers array type.
+     *
+     * @param <Auto> array
+     * @return array
+     */
     @SuppressWarnings("unchecked")
     public <Auto> Auto $array() {
         return (Auto)array();
     }
-    
+
+    /**
+     * Returns length of array
+     * @return int
+     */
     public abstract int size();
-    
+
+    /**
+     * Returns component type of array
+     * @return type
+     */
     public Class<?> component() {
         return array().getClass().getComponentType();
     }
-    
+
+    /**
+     * Sets value at specified index.
+     * Unboxes value if target array is primitive.
+     *
+     * @param index index
+     * @param value value
+     */
     public abstract void set(int index, Object value);
-    
+
+    /**
+     * Sets value for all elements in provided range.
+     * Unboxes value (but only once) if target array is primitive.
+     *
+     * @param begin begin
+     * @param end end
+     * @param value value
+     */
     public abstract void set(int begin, int end, Object value);
-    
+
+    /**
+     * Returns value stored in array at specified index
+     * Boxes value if target array is primitive.
+     *
+     * @param index index
+     * @return value
+     */
     public abstract Object get(int index);
-    
-    public abstract NativeMove move(NativeArray source);
+
+    /**
+     * Returns operator, which represents assignment: target[index] = source[index]
+     *
+     * Returned operators avoid unecessary boxing/unboxing operations
+     *
+     * @param source source
+     * @return operator
+     */
+    public abstract NativeMove moveFrom(NativeArray source);
+
+    /**
+     * Returns operator, which represents assignment: source[index] = target[index]
+     *
+     * Returned operators avoid unecessary boxing/unboxing operations
+     *
+     * @param source source
+     * @return operator
+     */
+    public NativeMove moveTo(NativeArray source) {
+        return source.moveTo(this);
+    }
 
     /**
      * Overwrites value at [index] with value from position [source].
+     * Avoid unecessary boxing/unboxing operations
+     *
      * @param index index
      * @param source source
      */
     public abstract void move(int index, int source);
-    
+
+    /**
+     * Sets value at specified index.
+     * Returns previous value stored in array.
+     *
+     * Unboxes value and boxes result if target array is primitive.
+     *
+     * @param index index
+     * @param value value
+     * @return
+     */
     public Object replace(int index, Object value) {
         Object prv = get(index);
         set(index, value);
@@ -73,7 +174,13 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         System.arraycopy(array(), 0, ret.array(), 0, size());
         return ret;
     }
-    
+
+    /**
+     * Allocates new array with boxed component and copies all elements into it.
+     * If array contains already boxed values, returns this object.
+     *
+     * @return array with boxed values
+     */
     public NativeArray box() {
         if(ClassTraits.isBoxed(component())) {
             return this;
@@ -84,7 +191,13 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         return ret;
     }
-    
+
+    /**
+     * Allocates new array with primitive component and copies all elements into it.
+     * If array contains primitive boxed values, returns this object.
+     *
+     * @return array with primitive values
+     */
     public NativeArray unbox() {
         if(!ClassTraits.isBoxed(component())) {
             return this;
@@ -95,29 +208,116 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         return ret;
     }
-    
+
+    /**
+     * Returns operator, which represents comparison: {@code value equals array[index]}
+     * In other words: checks if element at some "index" equals to "value"
+     *
+     * Returned operators avoid unecessary boxing/unboxing operations
+     *
+     * @param value
+     * @return operator
+     */
     public abstract IntPredicate cmp(Object value);
-    
+
+    /**
+     * Returns operator, which represents comparison: {@code value.compareTo(array[index])}
+     * In other words: checks if element at some "index" is lower or greater than "value"
+     *
+     * Returned operators avoid unecessary boxing/unboxing operations
+     *
+     * @param value
+     * @return operator
+     */
     public abstract NativeComparator lcmp(Object value);
-    
+
+    /**
+     * Returns operator, which represents comparison: {@code cmp.compareTo(value, array[index]) }
+     * In other words: checks if element at some "index" is lower or greater than "value" using provided comparator
+     *
+     * Because we pass values into generic comparator, all values will be boxed.
+     * There is optimization if you provide IntComparator for int[] arrays
+     *
+     * @param value
+     * @param cmp
+     * @return operator
+     */
     @SuppressWarnings("unchecked")
     public NativeComparator lcmp(Object value, Comparator cmp) {
         return index -> cmp.compare(value, get(index));
     }
-    
+
+    /**
+     * Returns operator, which represents comparison: {@code array[index].compareTo(value)}
+     * In other words: checks if "value" is lower or greater than element at some "index"
+     *
+     * Returned operators avoid unecessary boxing/unboxing operations
+     *
+     * @param value
+     * @return operator
+     */
     public abstract NativeComparator rcmp(Object value);
 
-    @SuppressWarnings("unchecked")    
+    /**
+     * Returns operator, which represents comparison: {@code cmp.compareTo(array[index], value) }
+     * In other words: checks if "value" is lower or greater than element at some "index" using provided comparator
+     *
+     * Because we pass values into generic comparator, all values will be boxed.
+     * There is optimization if you provide IntComparator for int[] arrays
+     *
+     * @param value
+     * @param cmp
+     * @return operator
+     */
+    @SuppressWarnings("unchecked")
     public NativeComparator rcmp(Object value, Comparator cmp) {
         return index -> cmp.compare(get(index), value);
     }
-    
+
+    /**
+     * Returns operator, which represents comparison: {@code array[index].compareTo(values[index])}
+     * In other words: compares elements of arrays at "index"
+     *
+     * Returned operators avoid unecessary boxing/unboxing operations
+     *
+     * @param values values
+     * @return operator
+     */
     public abstract IntComparator comparator(NativeArray values);
-    
+
+    /**
+     * Returns operator, which represents comparison: {@code cmp.compareTo(array[index], values[index])}
+     * In other words: compares elements of arrays at "index" using provided comparator
+     *
+     * Because we pass values into generic comparator, all values will be boxed.
+     * There is optimization if you provide IntComparator for int[] arrays
+     *
+     * @param values values
+     * @param cmp cmp
+     * @return operator
+     */
     public abstract IntComparator comparator(NativeArray values, Comparator cmp);
-    
+
+    /**
+     * Returns operator, which represents comparison: {@code array[index1].compareTo(array[index2])}
+     * In other words: compares two elements of this array
+     *
+     * Returned operators avoid unecessary boxing/unboxing operations
+     *
+     * @return operator
+     */
     public abstract IntComparator comparator();
-    
+
+    /**
+     * Returns operator, which represents comparison: {@code cmp.compareTo(array[index1], array[index2])}
+     * In other words: compares two elements of this array using provided comparator
+     *
+     * Because we pass values into generic comparator, all values will be boxed.
+     * There is optimization if you provide IntComparator for int[] arrays
+     *
+     * @param cmp
+     * @return
+     */
     @SuppressWarnings("unchecked")
     public IntComparator comparator(Comparator cmp) {
         return (a,b) -> cmp.compare(get(a), get(b));
@@ -127,9 +327,23 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
     public int hashCode() {
         return NativeArray.this.hashCode(0, size());
     }
-    
+
+    /**
+     * Calculates hashCode of element at "index"
+     *
+     * @param index index
+     * @return int
+     */
     public abstract int hashCode(int index);
-    
+
+    /**
+     * Calculates hashCode for elements from specified range.
+     * It uses the same algorithm as {@link List#hashCode}
+     *
+     * @param begin begin
+     * @param end end
+     * @return int
+     */
     public int hashCode(int begin, int end) {
         int result = 1;
         for(int i=begin; i<end; i++) {
@@ -137,7 +351,13 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         return result;
     }
-    
+
+    /**
+     * Checks for equality comparing all corresponding elements.
+     *
+     * @param object object
+     * @return bool
+     */
     @Override
     public boolean equals(Object object) {
         if(!(object instanceof NativeArray)) {
@@ -146,11 +366,26 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         NativeArray na = (NativeArray)object;
         return na.size()==size() && equals(na, 0, 0, size());
     }
-    
+
+    /**
+     * Checks for equality comparing all corresponding elements in specified range.
+     *
+     * @param object other array
+     * @param src start index of this array
+     * @param dst start index of another array
+     * @param size number of elements to compare
+     * @return bool
+     */
     public boolean equals(NativeArray object, int src, int dst, int size) {
         return 0 == compareTo(object, src, dst, size);
     }
-        
+
+    /**
+     * Compares all corresponding elements.
+     *
+     * @param object object
+     * @return int
+     */
     @Override
     public int compareTo(NativeArray object) {
         int a = size();
@@ -158,14 +393,30 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         int c = compareTo(object, 0, 0, Math.min(a,b));
         return 0 != c ? c : Integer.compare(a, b);
     }
-    
+
+    /**
+     * Compares all corresponding elements using provided comparator.
+     *
+     * @param object object
+     * @param comp comp
+     * @return
+     */
     public int compareTo(NativeArray object, Comparator comp) {
         int a = size();
         int b = object.size();
         int c = compareTo(object, 0, 0, Math.min(a,b), comp);
         return 0 != c ? c : Integer.compare(a, b);
     }
-    
+
+    /**
+     * Compares all corresponding elements in specified range.
+     *
+     * @param object other array
+     * @param src start index of this array
+     * @param dst start index of other array
+     * @param size number of elements to compare
+     * @return int
+     */
     public int compareTo(NativeArray object, int src, int dst, int size) {
         if(size == 0) {
             return 0;
@@ -182,7 +433,17 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         return 0;
     }
-    
+
+    /**
+     * Compares all corresponding elements in specified range using provided comparator.
+     *
+     * @param object other array
+     * @param src start index of this array
+     * @param dst start index of other array
+     * @param size number of elements to compare
+     * @param comp comp
+     * @return int
+     */
     public int compareTo(NativeArray object, int src, int dst, int size, Comparator comp) {
         if(size == 0) {
             return 0;
@@ -199,20 +460,54 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         return 0;
     }
-    
-    
+
+
+    /**
+     * Operator: it compares array element at "index" with some other value.
+     * For example:
+     *      this comparator can contain binded value, which we want to find.
+     *      this comparator can compare array[index] with another list[index]
+     *
+     * The whole idea is to provide optimized comparators which avoid boxing everything to Object
+     */
     public interface NativeComparator {
 
+        /**
+         * Compare array element at "index" with some other value
+         * @param index index
+         * @return int
+         */
         int compare(int index);
         
     }
-    
+
+    /**
+     * Operator: represent assignment operation: array1[target] = array2[source]
+     * Used for moving elements between arrays.
+     *
+     * The whole idea is to provide optimized operators which avoid boxing everything to Object and then unboxing again
+     */
     public interface NativeMove {
-        
+
+        /**
+         * Moves value from one place to another.
+         * "source" and "target" index can point to the different arrays.
+         *
+         * @param target target
+         * @param source source
+         */
         void move(int target, int source);
         
     }
-    
+
+    /**
+     * Allocates new array of provided component type and wraps it into NativeArray.
+     * Primitive component types are supported.
+     *
+     * @param component component
+     * @param size size
+     * @return NativeArray
+     */
     @SuppressWarnings({
         "PMD.NPathComplexity",
         "PMD.CyclomaticComplexity"
@@ -247,7 +542,14 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         throw new UnsupportedOperationException("Not supported type: " + component.getName());
     }
-    
+
+    /**
+     * Creates NativeArray backed by provided array.
+     * Primitive arrays are supported.
+     *
+     * @param array array
+     * @return NativeArray
+     */
 	@SuppressWarnings({
         "PMD.NPathComplexity",
         "PMD.CyclomaticComplexity"
@@ -286,23 +588,58 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         throw new UnsupportedOperationException("Not supported type: " + c.getName());
     }
-    
+
+    /**
+     * Creates NativeArray backed by provided array.
+     * This override is declared to avoid unecessary branching at runtime.
+     *
+     * @param array array
+     * @return  NativeArray
+     */
     public static NativeArray wrap(Object[] array) {
 		return new ObjectArray(array);
     }
-    
+
+    /**
+     * Creates NativeArray backed by provided array.
+     * This override is declared to avoid unecessary branching at runtime.
+     *
+     * @param array array
+     * @return  NativeArray
+     */
     public static NativeArray wrap(int[] array) {
 		return new IntegerArray(array);
     }
-    
+
+    /**
+     * Creates NativeArray backed by provided array.
+     * This override is declared to avoid unecessary branching at runtime.
+     *
+     * @param array array
+     * @return  NativeArray
+     */
     public static NativeArray wrap(char[] array) {
 		return new CharacterArray(array);
     }
-    
+
+    /**
+     * Creates NativeArray backed by provided array.
+     * This override is declared to avoid unecessary branching at runtime.
+     *
+     * @param array array
+     * @return  NativeArray
+     */
     public static NativeArray wrap(byte[] array) {
 		return new ByteArray(array);
     }
-    
+
+    /**
+     * Creates NativeArray backed by provided array.
+     * This override is declared to avoid unecessary branching at runtime.
+     *
+     * @param array array
+     * @return  NativeArray
+     */
     public static NativeArray wrap(boolean[] array) {
 		return new BooleanArray(array);
     }
@@ -355,7 +692,7 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         
         @Override
-        public NativeMove move(NativeArray source) {
+        public NativeMove moveFrom(NativeArray source) {
             byte[] s = source.$array();
             return (a,b) -> array[a]=s[b];
         }
@@ -468,7 +805,7 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         
         @Override
-        public NativeMove move(NativeArray source) {
+        public NativeMove moveFrom(NativeArray source) {
             short[] s = source.$array();
             return (a,b) -> array[a]=s[b];
         }
@@ -581,7 +918,7 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         
         @Override
-        public NativeMove move(NativeArray source) {
+        public NativeMove moveFrom(NativeArray source) {
             int[] s = source.$array();
             return (a,b) -> array[a]=s[b];
         }
@@ -734,7 +1071,7 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         
         @Override
-        public NativeMove move(NativeArray source) {
+        public NativeMove moveFrom(NativeArray source) {
             long[] s = source.$array();
             return (a,b) -> array[a]=s[b];
         }
@@ -847,7 +1184,7 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         
         @Override
-        public NativeMove move(NativeArray source) {
+        public NativeMove moveFrom(NativeArray source) {
             float[] s = source.$array();
             return (a,b)->{ array[a]=s[b]; };
         }
@@ -960,7 +1297,7 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         
         @Override
-        public NativeMove move(NativeArray source) {
+        public NativeMove moveFrom(NativeArray source) {
             double[] s = source.$array();
             return (a,b)->{ array[a]=s[b]; };
         }
@@ -1074,7 +1411,7 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         
         @Override
-        public NativeMove move(NativeArray source) {
+        public NativeMove moveFrom(NativeArray source) {
             char[] s = source.$array();
             return (a,b)->{ array[a]=s[b]; };
         }
@@ -1187,7 +1524,7 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         
         @Override
-        public NativeMove move(NativeArray source) {
+        public NativeMove moveFrom(NativeArray source) {
             boolean[] s = source.$array();
             return (a,b) -> array[a]=s[b];
         }
@@ -1300,7 +1637,7 @@ public abstract class NativeArray implements Swapper, Comparable<NativeArray>, C
         }
         
         @Override
-        public NativeMove move(NativeArray source) {
+        public NativeMove moveFrom(NativeArray source) {
             Object[] s = source.$array();
             return (a,b)->{ array[a]=s[b]; };
         }

assira.core/src/main/java/net/ranides/assira/collection/arrays/NativeArrayAccess.java

@@ -11,6 +11,12 @@ import net.ranides.assira.collection.arrays.NativeArray.*;
 import java.io.Serializable;
 
 /**
+ * This class allows for accessing arrays of unknown type in optimized way.
+ *
+ * If you use {@link java.lang.reflect.Array} then branching takes place at every access.
+ *
+ * Alternatively, you can obtain correct NativeArrayAccess object only once and then use it,
+ * to access data from array without unecessary branching over and over again.
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */
@@ -23,14 +29,24 @@ public abstract class NativeArrayAccess implements Serializable {
     protected NativeArrayAccess(Class<?> component) {
         this.component = component;
     }
-    
+
+    /**
+     * Returns accessor for provided array type.
+     * @param type type
+     * @return accessor
+     */
     public static NativeArrayAccess forType(Class<?> type) {
         if(!type.isArray()) {
             throw new IllegalArgumentException(type + " is not an array");
         }
         return forComponent(type.getComponentType());
     }
-    
+
+    /**
+     * Returns accessor for provided component type.
+     * @param component component
+     * @return accessor
+     */
     @SuppressWarnings({
         "PMD.NPathComplexity",
         "PMD.CyclomaticComplexity"
@@ -65,19 +81,57 @@ public abstract class NativeArrayAccess implements Serializable {
         }
         throw new UnsupportedOperationException("Not supported type: " + component.getName());
     }
-    
+
+    /**
+     * Returns component type supported by this accessor.
+     * For non-primitive arrays returns correct subtype of Object.
+     *
+     * @return type
+     */
     public final Class<?> component() {
         return component;
     }
-    
+
+    /**
+     * Creates new array of type supported by this accessor.
+     *
+     * @param size size
+     * @return array
+     */
     public abstract NativeArray allocate(int size);
-    
+
+    /**
+     * Creates new NativeArray backed by provided array
+     *
+     * @param that that
+     * @return NativeArray
+     */
     public abstract NativeArray bind(Object that);
-    
+
+    /**
+     * Returns length of array
+     *
+     * @param that that
+     * @return int
+     */
     public abstract int size(Object that);
-    
+
+    /**
+     * Changes value at specified "index".
+     *
+     * @param that that
+     * @param index index
+     * @param value value
+     */
     public abstract void set(Object that, int index, Object value);
-    
+
+    /**
+     * Returns value at specified "index"
+     *
+     * @param that that
+     * @param index index
+     * @return value
+     */
     public abstract Object get(Object that, int index);
     
     private static final NativeArrayAccess BYTE_ARRAY = new NativeArrayAccess(byte.class){

assira.core/src/main/java/net/ranides/assira/collection/arrays/NativeArrayAllocator.java

@@ -24,6 +24,13 @@ public final class NativeArrayAllocator {
      */
     private static final int MAX_SIZE = Integer.MAX_VALUE - 8;
 
+    /**
+     * Creates a new array with given component type and size.
+     *
+     * @param component component
+     * @param size size
+     * @return array
+     */
     public static NativeArray forComponent(Class<?> component, int size) {
         return NativeArray.allocate(component, size);
     }
@@ -42,6 +49,19 @@ public final class NativeArrayAllocator {
         return prototype.allocate(length);
     }
 
+    /**
+     * Creates a new array copying values from given list.
+     *
+     * This method returns a new array with length identical as source list.
+     * Type of returned array must be passed as first argument. Type can be array of primitives.
+     * Primitive values are correctly copied from boxed elements from list by unboxing.
+     *
+     * @param type type
+     * @param source source
+     * @param <A> array
+     * @return NativeArray
+     * @throws ClassCastException on invalid assignement
+     */
     public static <A> NativeArray fromList(Class<A> type, List<?> source) throws ClassCastException {
         int size = source.size();
         NativeArray array = NativeArray.allocate(type.getComponentType(), size);

assira.core/src/main/java/net/ranides/assira/collection/arrays/NativeArrayBuilder.java

@@ -6,30 +6,93 @@ import java.util.function.IntFunction;
 import java.util.function.Predicate;
 import java.util.stream.Stream;
 
+/**
+ * Fluent builder for array creation
+ * It supports batch insertions.
+ * It supports optional sorting list at the end
+ *
+ * It can construct arrays of primitive types, if you pass primitive component type.
+ *
+ * Because it supports primitives, it is not generic and you must make correct cast on your own.
+ */
 public class NativeArrayBuilder {
 
+    private static final int INITIAL_SIZE = 8;
+
     private int count;
     private NativeArray array;
     private Comparator<Object> cmp;
 
+    /**
+     * Creates array builder with provided component type.
+     * It allows creating arrays of primitive type.
+     * Other methods will do necessary boxing and unboxing operations.
+     *
+     * It reserves buffer of some default, unspecifed size, but greater than zero.
+     *
+     * @param component component
+     */
     public NativeArrayBuilder(Class<?> component) {
-        this(component, 8);
+        this(component, INITIAL_SIZE);
     }
 
+    /**
+     * Creates array builder with provided generic compoment type.
+     * Generator passed to constructor is used to construct correct array of initial size.
+     *
+     * Please note, that this generator is not used later for reallocation.
+     * Internal buffer is resized by creating new array of detected component.
+     *
+     * It reserves buffer of some default, unspecifed size, but greater than zero.
+     *
+     * @param generator generator
+     * @param <A> component type
+     */
     public <A> NativeArrayBuilder(IntFunction<A[]> generator) {
-        this(generator, 8);
+        this(generator, INITIAL_SIZE);
     }
 
+    /**
+     * Creates array builder with provided component type.
+     * It allows creating arrays of primitive type.
+     * Other methods will do necessary boxing and unboxing operations.
+     *
+     * It reserves buffer of provided size.
+     *
+     * @param component component
+     * @param size
+     */
     public NativeArrayBuilder(Class<?> component, int size) {
         this.array = NativeArray.allocate(component, size);
         this.count = 0;
     }
 
+    /**
+     * Creates array builder with provided generic component type.
+     * Generator passed to constructor is used to construct correct array of initial size.
+     *
+     * Please note, that this generator is not used later for reallocation.
+     * Internal buffer is resized by creating new array of detected component.
+     *
+     * It reserves buffer of provided size.
+     *
+     * @param generator generator
+     * @param size size
+     * @param <A> A
+     */
     public <A> NativeArrayBuilder(IntFunction<A[]> generator, int size) {
         this.array = NativeArray.wrap(generator.apply(size));
         this.count = 0;
     }
 
+    /**
+     * Returns internal buffer used by builder.
+     *
+     * Returned array is sorted, if builder has defined comparator.
+     * Returned array can be filled only partially, please check {@link #size} method.
+     *
+     * @return NativeArray
+     */
     public NativeArray buffer() {
         if(cmp != null) {
             ArraySort.quickSort(array, 0, count, cmp);
@@ -37,6 +100,26 @@ public class NativeArrayBuilder {
         return array.$array();
     }
 
+    /**
+     * Returns number of elements currently inserted into buffer.
+     * Can be used to decide which elements returned by {@link #buffer} are valid.
+     * @return int
+     */
+    public int size() {
+        return count;
+    }
+
+    /**
+     * Returns constructed array.
+     * Optionally it sorts values using comparator provider earlier.
+     *
+     * Please note, that returned array can share data with builder.
+     *
+     * Be carefull, because type of returned array is inferred.
+     *
+     * @param <A> array
+     * @return array
+     */
     public <A> A toArray() {
         if(cmp != null) {
             ArraySort.quickSort(array, 0, count, cmp);
@@ -44,12 +127,25 @@ public class NativeArrayBuilder {
         return NativeArrayAllocator.resize(array, count).$array();
     }
 
+    /**
+     * Inserts new value.
+     *
+     * @param value value
+     * @return this
+     */
     public NativeArrayBuilder value(Object value) {
         array = NativeArrayAllocator.grow(array, count +1);
         array.set(count++, value);
         return this;
     }
 
+    /**
+     * Inserts more than one value at once.
+     *
+     * @param value value
+     * @param values values
+     * @return this
+     */
     public final NativeArrayBuilder values(Object value, Object... values) {
         int ds = values.length;
         array = NativeArrayAllocator.grow(array, count+ ds + 1);
@@ -60,6 +156,12 @@ public class NativeArrayBuilder {
         return this;
     }
 
+    /**
+     * Inserts more than one value at once.
+     *
+     * @param values values
+     * @return this
+     */
     public NativeArrayBuilder values(Object[] values) {
         int ds = values.length;
         array = NativeArrayAllocator.grow(array, count+ ds);
@@ -69,6 +171,12 @@ public class NativeArrayBuilder {
         return this;
     }
 
+    /**
+     * Inserts more than one value at once.
+     *
+     * @param values values
+     * @return this
+     */
     public NativeArrayBuilder values(Collection<?> values) {
         int ds = values.size();
         array = NativeArrayAllocator.grow(array, count+ ds);
@@ -78,6 +186,12 @@ public class NativeArrayBuilder {
         return this;
     }
 
+    /**
+     * Inserts more than one value at once.
+     *
+     * @param values values
+     * @return this
+     */
     public NativeArrayBuilder values(Iterable<?> values) {
         for(Object v : values) {
             array = NativeArrayAllocator.grow(array, count+ 1);
@@ -86,16 +200,25 @@ public class NativeArrayBuilder {
         return this;
     }
 
+    /**
+     * Inserts more than one value at once.
+     *
+     * @param values values
+     * @return this
+     */
     public NativeArrayBuilder values(Stream<?> values) {
-        Object mutex = new Object();
-        values.sequential().forEach(v -> {
-            synchronized (mutex) {
-                value(v);
-            }
-        });
+        values.spliterator().forEachRemaining(this::value);
         return this;
     }
 
+    /**
+     * Inserts value conditionaly (if predicate accepts it).
+     *
+     * @param predicate predicate
+     * @param value value
+     * @param <P> P
+     * @return this
+     */
     public <P> NativeArrayBuilder valueIf(Predicate<P> predicate, P value) {
         if(predicate.test(value)) {
             value(value);
@@ -103,12 +226,29 @@ public class NativeArrayBuilder {
         return this;
     }
 
+    /**
+     * Inserts more than one value conditionaly (if predicate accepts it).
+     *
+     * @param predicate predicate
+     * @param value value
+     * @param values values
+     * @param <P> P
+     * @return this
+     */
     @SafeVarargs
     public final <P> NativeArrayBuilder valuesIf(Predicate<P> predicate, P value, P... values) {
         array = NativeArrayAllocator.grow(array, count + 1 + values.length);
         return valueIf(predicate, value).valuesIf(predicate, values);
     }
 
+    /**
+     * Inserts more than one value conditionaly (if predicate accepts it).
+     *
+     * @param predicate predicate
+     * @param values values
+     * @param <P> P
+     * @return this
+     */
     public <P> NativeArrayBuilder valuesIf(Predicate<P> predicate, P[] values) {
         array = NativeArrayAllocator.grow(array, count + values.length);
         for(P value : values) {
@@ -119,6 +259,14 @@ public class NativeArrayBuilder {
         return this;
     }
 
+    /**
+     * Inserts more than one value conditionaly (if predicate accepts it).
+     *
+     * @param predicate predicate
+     * @param values values
+     * @param <P> P
+     * @return this
+     */
     public <P> NativeArrayBuilder valuesIf(Predicate<P> predicate, Collection<P> values) {
         array = NativeArrayAllocator.grow(array, count + 1 + values.size());
         for(P value : values) {
@@ -129,6 +277,14 @@ public class NativeArrayBuilder {
         return this;
     }
 
+    /**
+     * Inserts more than one value conditionaly (if predicate accepts it).
+     *
+     * @param predicate predicate
+     * @param values values
+     * @param <P> P
+     * @return this
+     */
     public <P> NativeArrayBuilder values(Predicate<P> predicate, Iterable<P> values) {
         for(P value : values) {
             if(predicate.test(value)) {
@@ -138,6 +294,15 @@ public class NativeArrayBuilder {
         return this;
     }
 
+    /**
+     * Defines sorting order.
+     * Builder will sort all inserted values at the end of construction.
+     *
+     * That means, sorting will be done by methods: {@link #toArray()} and {@link #buffer()}
+     *
+     * @param cmp cmp
+     * @return this
+     */
     @SuppressWarnings({"unchecked", "rawtypes"})
     public NativeArrayBuilder sorted(Comparator<?> cmp) {
         if(this.cmp != null) {

assira.core/src/main/java/net/ranides/assira/collection/arrays/NativeArraySearch.java

@@ -10,21 +10,48 @@ import java.util.Comparator;
 import java.util.Optional;
 import java.util.function.IntPredicate;
 import java.util.function.Predicate;
+
+import lombok.experimental.UtilityClass;
 import net.ranides.assira.collection.arrays.NativeArray.NativeComparator;
 
+/**
+ * Utility class for searching inside NativeArray. Primitive values are supported.
+ *
+ * Please note, that many times, methods accepts NativeArray and any type T as component.
+ * It is responsibility of the caller to pass reasonable objects.
+ *
+ * Boxing and unboxing is supported.
+ *
+ * It is quite the same as {@link ArraySearch}, but it takes NativeArray wrapper instead of "just array".
+ */
 @SuppressWarnings({
     "PMD.AvoidReassigningParameters"
 })
-public final class NativeArraySearch {
-    
-    private NativeArraySearch() {
-        // utility class
-    }
-    
+@UtilityClass
+public class NativeArraySearch {
+
+    /**
+     * Returns first element matching predicate.
+     *
+     * @param array array
+     * @param predicate predicate
+     * @param <T> T
+     * @return optional
+     */
     public static <T> Optional<T> first(NativeArray array, Predicate<? super T> predicate) {
         return first(array, 0, array.size(), predicate);
     }
-    
+
+    /**
+     * Returns first element matching predicate. Searches only inside specified range.
+     *
+     * @param array array
+     * @param begin begin
+     * @param end end
+     * @param predicate predicate
+     * @param <T> T
+     * @return optional
+     */
     @SuppressWarnings("unchecked")
     public static <T> Optional<T>  first(NativeArray array, int begin, int end, Predicate<? super T> predicate) {
         for (int i=begin; i<end; i++) {
@@ -35,11 +62,29 @@ public final class NativeArraySearch {
         }
         return Optional.empty();
     }
-    
+
+    /**
+     * Returns last element matching predicate.
+     *
+     * @param array array
+     * @param predicate predicate
+     * @param <T> T
+     * @return optional
+     */
     public static <T> Optional<T> last(NativeArray array, Predicate<? super T> predicate) {
         return last(array, 0, array.size(), predicate);
     }
-    
+
+    /**
+     * Returns last element matching predicate. Searches only inside specified range.
+     *
+     * @param array array
+     * @param begin begin
+     * @param end end
+     * @param predicate predicate
+     * @param <T> T
+     * @return optional
+     */
     @SuppressWarnings("unchecked")
     public static <T> Optional<T> last(NativeArray array, int begin, int end, Predicate<? super T> predicate) {
         for (int i=end-1; i>=begin; i--) {
@@ -50,19 +95,55 @@ public final class NativeArraySearch {
         }
         return Optional.empty();
     }
-    
+
+    /**
+     * Returns true, if array contains value.
+     *
+     * @param array array
+     * @param value value
+     * @param <T> T
+     * @return bool
+     */
     public static <T> boolean contains(NativeArray array, T value) {
         return contains(array, 0, array.size(), value);
     }
-    
+
+    /**
+     * Returns true, if array contains value. Searches only inside specified range.
+     *
+     * @param array array
+     * @param begin begin
+     * @param end end
+     * @param value value
+     * @param <T> T
+     * @return bool
+     */
     public static <T> boolean contains(NativeArray array, int begin, int end, T value) {
         return indexOf(array, begin, end, value) >= 0;
     }
-    
+
+    /**
+     * Finds first element of specified value and returns its position.
+     *
+     * @param array array
+     * @param value value
+     * @param <T> T
+     * @return negative if not found
+     */
     public static <T> int indexOf(NativeArray array, T value) {
         return indexOf(array, 0, array.size(), value);
     }
-    
+
+    /**
+     * Finds first element of specified value and returns its position. Searches only inside specified range.
+     *
+     * @param array array
+     * @param begin begin
+     * @param end end
+     * @param value value
+     * @param <T> T
+     * @return negative if not found
+     */
     public static <T> int indexOf(NativeArray array, int begin, int end, T value) {
         IntPredicate ip = array.cmp(value);
         for (int i=begin; i<end; i++) {
@@ -72,11 +153,29 @@ public final class NativeArraySearch {
         }
         return -1;
     }
-    
+
+    /**
+     * Finds last element of specified value and returns its position.
+     *
+     * @param array array
+     * @param value value
+     * @param <T> T
+     * @return negative if not found
+     */
     public static <T> int lastIndexOf(NativeArray array, T value) {
         return lastIndexOf(array, 0, array.size(), value);
     }
-    
+
+    /**
+     * Finds last element of specified value and returns its position. Searches only inside specified range.
+     *
+     * @param array array
+     * @param begin begin
+     * @param end end
+     * @param value value
+     * @param <T> T
+     * @return negative if not found
+     */
     public static <T> int lastIndexOf(NativeArray array, int begin, int end, T value) {
         IntPredicate ip = array.cmp(value);
         for (int i=end-1; i>=begin; i--) {
@@ -87,22 +186,131 @@ public final class NativeArraySearch {
         return -1;
     }
 
+    /**
+     * Searches an array for the specified value using the binary search
+     * algorithm. The range must be sorted prior to making this call. If it is
+     * not sorted, the results are undefined. If the range contains multiple
+     * elements with the specified value, there is no guarantee which one will
+     * be found.
+     *
+     * @param array the array to be searched.
+     * @param key the value to be searched for.
+     * @param <T> T component
+     * @return index of the search key, if it is contained in the array;
+     * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The <i>insertion
+     * point</i> is defined as the the point at which the value would be
+     * inserted into the array: the index of the first element greater than the
+     * key, or the length of the array, if all elements in the array are less
+     * than the specified key. Note that this guarantees that the return value
+     * will be &gt;= 0 if and only if the key is found.
+     * @see java.util.Arrays
+     */
     public static <T> int binarySearch(NativeArray array, T key) {
         return binarySearch(array.rcmp(key), 0, array.size());
     }
-    
+
+    /**
+     * Searches a range of the specified array for the specified value using the
+     * binary search algorithm. The range must be sorted prior to making this
+     * call. If it is not sorted, the results are undefined. If the range
+     * contains multiple elements with the specified value, there is no
+     * guarantee which one will be found.
+     *
+     * @param array the array to be searched.
+     * @param begin the index of the first element (inclusive) to be searched.
+     * @param end the index of the last element (exclusive) to be searched.
+     * @param key the value to be searched for.
+     * @param <T> T component
+     * @return index of the search key, if it is contained in the array;
+     * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The <i>insertion
+     * point</i> is defined as the the point at which the value would be
+     * inserted into the array: the index of the first element greater than the
+     * key, or the length of the array, if all elements in the array are less
+     * than the specified key. Note that this guarantees that the return value
+     * will be &gt;= 0 if and only if the key is found.
+     * @see java.util.Arrays
+     */
     public static <T> int binarySearch(NativeArray array, int begin, int end, T key) {
         return binarySearch(array.rcmp(key), begin, end);
     }
-    
+
+    /**
+     * Searches an array for the specified value using the binary search
+     * algorithm and a specified comparator. The range must be sorted following
+     * the comparator prior to making this call. If it is not sorted, the
+     * results are undefined. If the range contains multiple elements with the
+     * specified value, there is no guarantee which one will be found.
+     *
+     * @param array the array to be searched.
+     * @param key the value to be searched for.
+     * @param comp a comparator.
+     * @param <T> T component
+     * @return index of the search key, if it is contained in the array;
+     * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The <i>insertion
+     * point</i> is defined as the the point at which the value would be
+     * inserted into the array: the index of the first element greater than the
+     * key, or the length of the array, if all elements in the array are less
+     * than the specified key. Note that this guarantees that the return value
+     * will be &gt;= 0 if and only if the key is found.
+     * @see java.util.Arrays
+     */
     public static <T> int binarySearch(NativeArray array, T key, Comparator<? super T> comp) {
         return binarySearch(array.rcmp(key, comp), 0, array.size());
     }
-    
+
+    /**
+     * Searches a range of the specified array for the specified value using the
+     * binary search algorithm and a specified comparator. The range must be
+     * sorted following the comparator prior to making this call. If it is not
+     * sorted, the results are undefined. If the range contains multiple
+     * elements with the specified value, there is no guarantee which one will
+     * be found.
+     *
+     * @param array the array to be searched.
+     * @param begin the index of the first element (inclusive) to be searched.
+     * @param end the index of the last element (exclusive) to be searched.
+     * @param key the value to be searched for.
+     * @param comp a comparator.
+     * @param <T> T component
+     * @return index of the search key, if it is contained in the array;
+     * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The <i>insertion
+     * point</i> is defined as the the point at which the value would be
+     * inserted into the array: the index of the first element greater than the
+     * key, or the length of the array, if all elements in the array are less
+     * than the specified key. Note that this guarantees that the return value
+     * will be &gt;= 0 if and only if the key is found.
+     * @see java.util.Arrays
+     */
     public static <T> int binarySearch(NativeArray array, int begin, int end, T key, Comparator<? super T> comp) {
         return binarySearch(array.rcmp(key, comp), begin, end);
     }
-    
+
+    /**
+     * Searches specified range for the specified value using the
+     * binary search algorithm and a specified comparator. The range must be
+     * sorted following the comparator prior to making this call. If it is not
+     * sorted, the results are undefined. If the range contains multiple
+     * elements with the specified value, there is no guarantee which one will
+     * be found.
+     *
+     * This method does not take any array or value as arguments.
+     * This method takes {@link NativeComparator} which tells you, what is the result of comparison at "index".
+     *
+     * Essentially, this method can be used as a framework to implement search through any data structure as long
+     * as you can provide NativeComparator which encapsulates information about both structure and searched value.
+     *
+     * @param comp a comparator.
+     * @param begin the index of the first element (inclusive) to be searched.
+     * @param end the index of the last element (exclusive) to be searched.
+     * @return index of the search key, if it is contained in the array;
+     * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The <i>insertion
+     * point</i> is defined as the the point at which the value would be
+     * inserted into the array: the index of the first element greater than the
+     * key, or the length of the array, if all elements in the array are less
+     * than the specified key. Note that this guarantees that the return value
+     * will be &gt;= 0 if and only if the key is found.
+     * @see java.util.Arrays
+     */
     public static int binarySearch(NativeComparator comp, int begin, int end) {
         end--;
         while (begin <= end) {

assira.core/src/main/java/net/ranides/assira/collection/arrays/NativeArraySort.java

@@ -480,13 +480,13 @@ public final class NativeArraySort {
         public MergeArray(NativeArray array, NativeArray supp, Comparator comp) {
             this.array = array;
             this.icmp = array.comparator(comp);
-            this.imov = array.move(supp);
+            this.imov = array.moveFrom(supp);
         }
         
         public MergeArray(NativeArray array, NativeArray supp) {
             this.array = array;
             this.icmp = array.comparator();
-            this.imov = array.move(supp);
+            this.imov = array.moveFrom(supp);
         }
     }
 }

assira.core/src/main/java/net/ranides/assira/collection/arrays/NativeArrayUtils.java

@@ -18,6 +18,9 @@ import java.util.ListIterator;
 import java.util.Random;
 import java.util.function.BiPredicate;
 
+/**
+ * Common utility method for NativeArray wrapper.
+ */
 @SuppressWarnings({
     "PMD.AvoidReassigningParameters"
 })
@@ -26,7 +29,27 @@ public final class NativeArrayUtils {
     private NativeArrayUtils() {
         // utility class
     }
-    
+
+    /**
+     * Unwraps an iterator into an array starting at a given offset for a given
+     * number of elements.
+     *
+     * <P>This method iterates over the given type-specific iterator and stores
+     * the elements returned, up to a maximum of
+     * {@code length}, in the given array starting at
+     * {@code offset}. The number of actually unwrapped elements is
+     * returned (it may be less than
+     * {@code max} if the iterator emits less than
+     * {@code max} elements).
+     *
+     * @param iterator a type-specific iterator.
+     * @param target an array to contain the output of the iterator.
+     * @param begin the first element of the array to be returned.
+     * @param end the maximum number of elements to collect.
+     * @return the number of elements unwrapped.
+     *
+     * @param <T> component
+     */
     public static <T> int collect(Iterator<? extends T> iterator, NativeArray target, int begin, int end) {
         NativeArrayAllocator.ensureFromTo(target, begin, end);
         int j = end;
@@ -36,6 +59,20 @@ public final class NativeArrayUtils {
         return end - j - 1;
     }
 
+    /**
+     * Unwraps an iterator into an array.
+     *
+     * <P>This method iterates over the given type-specific iterator and stores
+     * the elements returned in the given array. The iteration will stop when
+     * the iterator has no more elements or when the end of the array has been
+     * reached.
+     *
+     * @param iterator a type-specific iterator.
+     * @param target an array to contain the output of the iterator.
+     * @return the number of elements unwrapped.
+     *
+     * @param <T> component
+     */
     public static <T> int collect(Iterator<? extends T> iterator, NativeArray target) {
         return collect(iterator, target, 0, target.size());
     }
@@ -48,16 +85,45 @@ public final class NativeArrayUtils {
      *
      * @param array an array.
      * @param value the new value for all elements of the array.
+     * @param <T> T
      */
     public static <T> void fill(NativeArray array, T value) {
         array.set(0, array.size(), value);
     }
 
+    /**
+     * Fills a portion of the given array with the given value.
+     *
+     * <P>If possible (i.e.,
+     * {@code from} is 0) this method uses a backward loop. In this case,
+     * it is significantly faster than the corresponding method in
+     * {@link java.util.Arrays}.
+     *
+     * @param array an array.
+     * @param begin the starting index of the portion to fill (inclusive).
+     * @param end the end index of the portion to fill (exclusive).
+     * @param value the new value for all elements of the specified portion of
+     * the array.
+     *
+     * @param <T> component
+     */
     public static <T> void fill(NativeArray array, int begin, int end, T value) {
         NativeArrayAllocator.ensureFromTo(array, begin, end);
         array.set(begin, end, value);
     }
-    
+
+    /**
+     * Reverses the order of the elements in the specified array, but only inside specified range.
+     *
+     * Please note, that NativeArray implements Swapper - this method can be used in other contexts too.
+     *
+     * @param swapper the array to be reversed.
+     * @param begin begin
+     * @param end end
+     * @return array
+     *
+     * @param <S> array
+     */
     public static <S extends Swapper> S reverse(S swapper, int begin, int end){
         while(begin < --end){
             swapper.swap(begin++, end);
@@ -65,48 +131,132 @@ public final class NativeArrayUtils {
         return swapper;
     }
 
+    /**
+     * Reverses the order of the elements in the specified array, but only inside specified range.
+     *
+     * Please note, that NativeArray implements Swapper - this method can be used in other contexts too.
+     *
+     * @param swapper the array to be reversed.
+     * @param size size
+     * @return array
+     *
+     * @param <S> array
+     */
     public static <S extends Swapper> S reverse(S swapper, int size) {
         return reverse(swapper, 0, size);
     }
-    
+
+    /**
+     * Reverses the order of the elements in the specified array.
+     *
+     * @param array the array to be reversed.
+     * @return array
+     */
     public static NativeArray reverse(NativeArray array) {
         reverse(array, array.size());
         return array;
     }
-    
+
+    /**
+     * Returns true if the two arrays are elementwise equal.
+     *
+     * @param array1 an array.
+     * @param array2 another array.
+     * @return true if the two arrays are of the same length, and their elements are equal.
+     */
     public static boolean equals(NativeArray array1, NativeArray array2) {
         return array1.equals(array2);
     }
-    
+
+    /**
+     * Copies elements before index, and returns as new array
+     *
+     * @param values values
+     * @param index index of last element to copy
+     * @return new array
+     */
     public static NativeArray head(NativeArray values, int index) {
         return slice(values, 0, index);
     }
 
+    /**
+     * Finds position of [value] and copies all elements before it.
+     * It uses cmp function for search.
+     *
+     * @param values values
+     * @param value value
+     * @param cmp cmp
+     * @param <T> T
+     * @return new array
+     */
     public static <T> NativeArray head(NativeArray values, T value, Comparator<? super T> cmp) {
         return slice(values, 0, ifind(values, value, 0, cmp));
     }
-    
-    public static <T> NativeArray tail(NativeArray values, int index) {
+
+    /**
+     * Copies elements from [index] position (including), and returns as new array
+     *
+     * @param values values
+     * @param index index
+     * @return new array
+     */
+    public static NativeArray tail(NativeArray values, int index) {
         return slice(values, index, values.size());
     }
-    
+
+    /**
+     * Finds position of [value] and copies all elements from this position (including).
+     * It uses cmp function for search.
+     *
+     * @param values values
+     * @param value value
+     * @param cmp cmp
+     * @param <T> component
+     * @return new array
+     */
     public static <T> NativeArray tail(NativeArray values, T value, Comparator<? super T> cmp) {
         return slice(values, ifind(values, value, 0, cmp), values.size());
     }
-    
+
+    /**
+     * Finds [begin] and [end] elements and copies content between them, including [begin].
+     * It uses cmp function for search.
+     *
+     * @param values values
+     * @param begin first value (include)
+     * @param end last value (exclude)
+     * @param cmp cmp
+     * @param <T> component
+     * @return new array
+     */
     public static <T> NativeArray slice(NativeArray values, T begin, T end, Comparator<? super T> cmp) {
         int bi = ifind(values, begin, 0, cmp);
         int ei = ifind(values, end, bi, cmp);
         return slice(values, bi, ei);
     }
 
+    /**
+     * Copies elements from begin (including) to end (excluding)
+     *
+     * @param values values
+     * @param begin begin (including)
+     * @param end end (excluding)
+     * @return new array
+     */
     public static NativeArray slice(NativeArray values, int begin, int end) {
         int size = end - begin;
         NativeArray result = values.allocate(size);
         NativeArrayUtils.copy(values, begin, result, 0, size);
         return result;
     }
-    
+
+    /**
+     * Shifts all elements by offset positions. Last elements are moved to begin.
+     *
+     * @param array array
+     * @param offset offset
+     * @return the same array
+     */
     public static NativeArray rotate(NativeArray array, int offset) {
         int n = array.size();
         offset = offset % n;
@@ -130,33 +280,82 @@ public final class NativeArrayUtils {
         }
         return i;
     }
-    
+
+    /**
+     * Shuffles all elements inside array using provided random generator.
+     * It runs in linear time, it makes [length] swaps.
+     *
+     * @param random random
+     * @param array array
+     * @return the same array
+     */
     public static NativeArray shuffle(Random random, NativeArray array) {
         shuffle(random, array.size(), array);
         return array;
     }
-    
+
+    /**
+     * Shuffles all elements inside range [0;size) using provided swapper and random generator.
+     * It runs in linear time, it makes [length] swaps.
+     *
+     * Please note, that NativeArray implements Swapper, so it can be passed to this function, if necessary.
+     *
+     * @param random random
+     * @param size size
+     * @param swapper swapper
+     * @return the same array
+     */
     public static void shuffle(Random random, int size, Swapper swapper) {
         for(int i=size; i>1; i--) {
             swapper.swap(i-1, random.nextInt(i));
         }
     }
 
+    /**
+     * Returns length of array.
+     *
+     * @param array array
+     * @return int
+     */
     public static int size(NativeArray array) {
         return array.size();
     }
-    
+
+    /**
+     * Copies source array into destination array.
+     * It uses System.arraycopy.
+     * The only difference is that is returns destination as result.
+     *
+     * @param src array
+     * @param srcpos srcpos
+     * @param dst array
+     * @param dstpos dstpos
+     * @param size size
+     * @return dst
+     */
     @SuppressWarnings("SuspiciousSystemArraycopy")
-    public static <T> NativeArray copy(NativeArray src, int srcpos, NativeArray dst, int dstpos, int size) {
+    public static NativeArray copy(NativeArray src, int srcpos, NativeArray dst, int dstpos, int size) {
         System.arraycopy(src.array(), srcpos, dst.array(), dstpos, size);
         return dst;
     }
-    
+
+    /**
+     * Copies array.
+     *
+     * @param array array
+     * @return new array
+     */
     public static NativeArray copy(NativeArray array) {
         int n = array.size();
         return copy(array, 0, NativeArrayAllocator.forPrototype(array, n), 0, n);
     }
-    
+
+    /**
+     * Concatenates two arrays.
+     * @param a array
+     * @param b array
+     * @return new array
+     */
     public static NativeArray concat(NativeArray a, NativeArray b) {
         int as = a.size();
         int bs = b.size();
@@ -165,7 +364,15 @@ public final class NativeArrayUtils {
         copy(b, 0, result, as, bs);
         return result;
     }
-    
+
+    /**
+     * Creates new array with value appended at the end of source array.
+     * New array is always one element longer that original.
+     *
+     * @param a array
+     * @param value value
+     * @return new array
+     */
     public static NativeArray append(NativeArray a, Object value) {
         int as = a.size();
         NativeArray result = a.allocate(as + 1);
@@ -173,7 +380,15 @@ public final class NativeArrayUtils {
         result.set(as, value);
         return result;
     }
-    
+
+    /**
+     * Creates new array with value inserted at the begining of source array.
+     * New array is always one element longer that original.
+     *
+     * @param a array
+     * @param value value
+     * @return new array
+     */
     public static NativeArray prepend(NativeArray a, Object value) {
         int as = a.size();
         NativeArray result = a.allocate(as + 1);
@@ -186,6 +401,7 @@ public final class NativeArrayUtils {
      * Removes first element from array and moves all elements to the left.
      * Note that last element in array will be duplicated.
      * @param a a
+     * @param <T> T
      * @return removed value
      */
     @SuppressWarnings("unchecked")
@@ -205,6 +421,7 @@ public final class NativeArrayUtils {
      * Removes last element from array and moves all elements to the right.
      * Note that first element in array will be duplicated.
      * @param a a
+     * @param <T>
      * @return T
      */
     @SuppressWarnings("unchecked")
@@ -219,11 +436,31 @@ public final class NativeArrayUtils {
         }
         return (T)value;
     }
-    
+
+    /**
+     * Creates iterator for specified array.
+     * Iterator supports "set" operation, but not "add" or "remove".
+     * Please note, that component type is inferred
+     *
+     * @param array array
+     * @param <T>
+     * @return iterator
+     */
     public static <T> ListIterator<T> iterator(NativeArray array) {
         return iterator(array, 0, array.size());
     }
 
+    /**
+     * Creates iterator for specified array, but only for specified range.
+     * Iterator supports "set" operation, but not "add" or "remove".
+     * Please note, that component type is inferred
+     *
+     * @param array array
+     * @param begin begin
+     * @param end end
+     * @param <T>
+     * @return iterator
+     */
     @SuppressWarnings("unchecked")
     public static <T> ListIterator<T> iterator(NativeArray array, int begin, int end) {
         return new RandomAccessIterator<T>() {
@@ -244,7 +481,17 @@ public final class NativeArrayUtils {
             
         };
     }
-    
+
+    /**
+     * Compares two arrays using specified comparison function.
+     * Returns true, if arrays are equal.
+     *
+     * @param a array
+     * @param b array
+     * @param cmp comparision function
+     * @param <T> component
+     * @return bool
+     */
     public static <T> boolean equals(NativeArray a, NativeArray b, Comparator<? super T> cmp) {
         if(a.size() != b.size()) {
             return false;
@@ -257,7 +504,17 @@ public final class NativeArrayUtils {
         }
         return true;
     }
-    
+
+    /**
+     * Compares two arrays using specified comparison function.
+     * Returns true, if arrays are equal.
+     *
+     * @param a array
+     * @param b array
+     * @param predicate comparision function
+     * @param <T> component
+     * @return bool
+     */
     public static <T> boolean equals(NativeArray a, NativeArray b, BiPredicate<? super T,? super T> predicate) {
         if(a.size() != b.size()) {
             return false;
@@ -271,11 +528,27 @@ public final class NativeArrayUtils {
         }
         return true;
     }
-    
-    public static <T> int compare(NativeArray a, NativeArray b) {
+
+    /**
+     * Compares two arrays. Elements must be comparable.
+     *
+     * @param a array
+     * @param b array
+     * @return bool
+     */
+    public static int compare(NativeArray a, NativeArray b) {
         return icompare(a.size(), b.size(), a.comparator(b));
     }
-    
+
+    /**
+     * Compares two arrays using specified comparator.
+     *
+     * @param a array
+     * @param b array
+     * @param cmp comparator
+     * @param <T> component
+     * @return int
+     */
     public static <T> int compare(NativeArray a, NativeArray b, Comparator<? super T> cmp) {
         return icompare(a.size(), b.size(), a.comparator(b, cmp));
     }

assira.core/src/main/java/net/ranides/assira/collection/lists/AIntList.java

@@ -204,7 +204,7 @@ public abstract class AIntList extends AIntCollection implements IntList, Compar
     }
 
     @Override
-    public int pop() {
+    public int popInt() {
         if (isEmpty()) {
             throw new NoSuchElementException();
         }
@@ -212,12 +212,12 @@ public abstract class AIntList extends AIntCollection implements IntList, Compar
     }
 
     @Override
-    public int peek() {
-        return peek(0);
+    public int peekInt() {
+        return peekInt(0);
     }
 
     @Override
-    public int peek(int i) {
+    public int peekInt(int i) {
 		int index = size() - 1 - i;
 		if (index<0) {
             throw new NoSuchElementException();

assira.core/src/main/java/net/ranides/assira/collection/lists/IntList.java

@@ -136,7 +136,7 @@ public interface IntList extends IntCollection, List<Integer> {
      * non-generic version of {@link java.util.Stack#peek()}
      * @return int
      */
-    int peek();
+    int peekInt();
 
     /**
      * non-generic generalization of {@link java.util.Stack#peek()}
@@ -146,13 +146,13 @@ public interface IntList extends IntCollection, List<Integer> {
      * @param i i
      * @return int
      */
-    int peek(int i);
+    int peekInt(int i);
 
     /**
      * non-generic version of {@link java.util.Stack#pop()}
      * @return int
      */
-    int pop();
+    int popInt();
 
     /**
      * non-generic version of {@link java.util.Stack#push(Object)}

assira.core/src/main/java/net/ranides/assira/collection/lists/IntVirtualList.java

@@ -48,7 +48,7 @@ public abstract class IntVirtualList extends AIntList implements RandomAccess, S
      * @return virtual
      */
     public static IntList of(int size, IntUnaryOperator function) {
-        return of(() -> size, function);
+        return of((IntSupplier & Serializable)() -> size, function);
     }
 
     /**

assira.core/src/main/java/net/ranides/assira/collection/lists/ListBuilder.java

@@ -28,7 +28,7 @@ public class ListBuilder<T> {
      * Returns constructed list.
      * Optionally it sorts values using comparator provider earlier.
      *
-     * Please note, data returned list shares data with builder.
+     * Please note, that returned list shares data with builder.
      *
      * @return list
      */
@@ -136,12 +136,7 @@ public class ListBuilder<T> {
      * @return this
      */
     public <P extends T> ListBuilder<P> values(Stream<P> values) {
-        Object mutex = new Object();
-        values.sequential().forEach(v -> {
-            synchronized (mutex) {
-                value(v);
-            }
-        });
+        values.spliterator().forEachRemaining(this::value);
         return that();
     }
 

assira.core/src/main/java/net/ranides/assira/collection/lists/VirtualList.java

@@ -54,7 +54,7 @@ public abstract class VirtualList<T> extends AbstractList<T> implements RandomAc
      * @return virtual
      */
     public static <T> List<T> of(int size, IntFunction<? extends T> function) {
-        return of(() -> size, function);
+        return of((IntSupplier & Serializable)() -> size, function);
     }
 
     /**

assira.core/src/main/java/net/ranides/assira/collection/utils/CollectionSort.java

@@ -22,8 +22,8 @@ import java.util.Comparator;
 import java.util.List;
 
 /**
- * Those methods implement "group" sort. Sort provided collections according to order established
- * by comparator and first "leading" collections.
+ * Those methods implement "group" sort.
+ * Methods sort provided collections according to order established by comparator and first "leading" collections.
  */
 @UtilityClass
 public final class CollectionSort {

assira.core/src/test/java/net/ranides/assira/collection/arrays/NativeArrayTester.java

@@ -139,7 +139,7 @@ public class NativeArrayTester<K> {
         
         assertEquals(f.apply(new int[]{3,7,5,7}), target);
         
-        NativeMove imov = target.move(f.apply(new int[]{11,12,13,14}));
+        NativeMove imov = target.moveFrom(f.apply(new int[]{11,12,13,14}));
         imov.move(0, 2);
         imov.move(1, 1);
         imov.move(3, 0);

assira.core/src/test/java/net/ranides/test/contracts/collection/lists/IntListTester.java

@@ -207,14 +207,14 @@ public class IntListTester {
     public void basicStackPop(Function<int[], IntList> f) {
         IntList target = f.apply(V2);
         
-		assertEquals($var.item(9).valueInt(), target.pop());
-		assertEquals($var.item(7).valueInt(), target.pop());
-		assertEquals($var.item(5).valueInt(), target.pop());
-		assertEquals($var.item(3).valueInt(), target.pop());
-		assertEquals($var.item(1).valueInt(), target.pop());
+		assertEquals($var.item(9).valueInt(), target.popInt());
+		assertEquals($var.item(7).valueInt(), target.popInt());
+		assertEquals($var.item(5).valueInt(), target.popInt());
+		assertEquals($var.item(3).valueInt(), target.popInt());
+		assertEquals($var.item(1).valueInt(), target.popInt());
 		
 		assertThrows(NoSuchElementException.class, ()->{ 
-			target.pop();
+			target.popInt();
 		});
     }
 	
@@ -224,12 +224,12 @@ public class IntListTester {
         target.push($var.item(2).valueInt());
         target.push($var.item(3).valueInt());
 		
-		assertEquals($var.item(3).valueInt(), target.pop());
-		assertEquals($var.item(2).valueInt(), target.pop());
-		assertEquals($var.item(1).valueInt(), target.pop());
+		assertEquals($var.item(3).valueInt(), target.popInt());
+		assertEquals($var.item(2).valueInt(), target.popInt());
+		assertEquals($var.item(1).valueInt(), target.popInt());
         
 		assertThrows(NoSuchElementException.class, ()->{ 
-			target.pop();
+			target.popInt();
 		});
     }
 	
@@ -239,26 +239,26 @@ public class IntListTester {
         
 		target.push($var.item(9).valueInt());
 		
-		assertEquals($var.item(9).valueInt(), target.peek());
-		assertEquals($var.item(9).valueInt(), target.pop());
+		assertEquals($var.item(9).valueInt(), target.peekInt());
+		assertEquals($var.item(9).valueInt(), target.popInt());
 		
-		assertEquals($var.item(7).valueInt(), target.peek());
-		assertEquals($var.item(7).valueInt(), target.pop());
+		assertEquals($var.item(7).valueInt(), target.peekInt());
+		assertEquals($var.item(7).valueInt(), target.popInt());
 		
-		assertEquals($var.item(5).valueInt(), target.peek(0));
-		assertEquals($var.item(3).valueInt(), target.peek(1));
-		assertEquals($var.item(1).valueInt(), target.peek(2));
+		assertEquals($var.item(5).valueInt(), target.peekInt(0));
+		assertEquals($var.item(3).valueInt(), target.peekInt(1));
+		assertEquals($var.item(1).valueInt(), target.peekInt(2));
 		
 		assertThrows(NoSuchElementException.class, ()->{
-			target.peek(3);
+			target.peekInt(3);
 		});
 		
 		target.clear();
 		assertThrows(NoSuchElementException.class, ()->{
-			target.peek();
+			target.peekInt();
 		});
 		assertThrows(NoSuchElementException.class, ()->{
-			target.peek(0);
+			target.peekInt(0);
 		});
     }