#37 javadoc: math

assira.core/src/main/java/net/ranides/assira/math/Bitwise.java

@@ -7,14 +7,15 @@
 
 package net.ranides.assira.math;
 
+import lombok.experimental.UtilityClass;
+
 /**
  * Klasa pomocnicza realizująca częste operacje bitowe.
  * @author ranides
  */
+@UtilityClass
 public final class Bitwise {
 
-    private Bitwise() { }
-
     /**
      * Sprawdza, czy wartość {@code value} ma ustawione wszystkie bity podane
      * w masce {@code mask}, lub na odwrót: czy {@code mask} ma ustawione bity

assira.core/src/main/java/net/ranides/assira/math/MathUtils.java

@@ -8,120 +8,235 @@ package net.ranides.assira.math;
 
 import lombok.experimental.UtilityClass;
 
+/**
+ * Math methods, obviously.
+ */
 @UtilityClass
 public final class MathUtils {
 
-    private static double EPSILON = Math.pow(2, -52);
-    private static double MAX_VALUE = (2 - EPSILON) * Math.pow(2, 1023);
-    private static double MIN_VALUE = Math.pow(2, -1022);
-
+    /**
+     * Returns true if {@code min <= value <= max}
+     *
+     * @param value value
+     * @param min min
+     * @param max max
+     * @return boolean
+     */
     public static boolean between(int value, int min, int max) {
         return value >= min && value <= max;
     }
 
+    /**
+     * Returns true if {@code min <= value <= max}
+     *
+     * @param value value
+     * @param min min
+     * @param max max
+     * @return boolean
+     */
     public static boolean between(byte value, byte min, byte max) {
         return value >= min && value <= max;
     }
 
+    /**
+     * Returns true if {@code min <= value <= max}
+     *
+     * @param value value
+     * @param min min
+     * @param max max
+     * @return boolean
+     */
     public static boolean between(long value, long min, long max) {
         return value >= min && value <= max;
     }
 
+    /**
+     * Returns value if {@code min <= value <= max}.
+     * Returns min for smaller values, returns max for greater values.
+     *
+     * @param value value
+     * @param min min
+     * @param max max
+     * @return number
+     */
     public static int clip(int value, int min, int max) {
         assert min <= max;
         return value < min ? min : value > max ? max : value;
     }
-    
+
+    /**
+     * Returns value if {@code min <= value <= max}.
+     * Returns min for smaller values, returns max for greater values.
+     *
+     * @param value value
+     * @param min min
+     * @param max max
+     * @return number
+     */
     public static long clip(long value, long min, long max) {
         assert min <= max;
         return value < min ? min : value > max ? max : value;
     }
 
+    /**
+     * Returns value if {@code min <= value <= max}.
+     * Returns min for smaller values, returns max for greater values.
+     *
+     * @param value value
+     * @param min min
+     * @param max max
+     * @return number
+     */
     public static double clip(double value, double min, double max) {
         assert min <= max;
         return value < min ? min : value > max ? max : value;
     }
 
+    /**
+     * Returns value if {@code min <= value <= max}.
+     * Returns min for smaller values, returns max for greater values.
+     *
+     * @param value value
+     * @param min min
+     * @param max max
+     * @return number
+     */
     public static float clip(float value, float min, float max) {
         assert min <= max;
         return value < min ? min : value > max ? max : value;
     }
 
+    /**
+     * Returns rounded value if {@code min <= value <= max}.
+     * Returns min for smaller values, returns max for greater values.
+     *
+     * @param value value
+     * @param min min
+     * @param max max
+     * @return number
+     */
     public static int round(double value, int min, int max) {
         assert min <= max;
         return (int)Math.round(value < min ? min : value > max ? max : value);
     }
 
+    /**
+     * Returns rounded value if {@code min <= value <= max}.
+     * Returns min for smaller values, returns max for greater values.
+     *
+     * @param value value
+     * @param min min
+     * @param max max
+     * @return number
+     */
     public static long round(double value, long min, long max) {
         assert min <= max;
         return Math.round(value < min ? min : value > max ? max : value);
     }
-    
+
+    /**
+     * Returns true signum: +1 for positives, -1 for negatives, 0 for zero.
+     *
+     * @param diff diff
+     * @return int
+     */
     public static int signum(int diff) {
         return Integer.signum(diff);
     }
 
+
     /**
-     * Alternate to signum for use in compare. Not a true signum, since it
-     * returns ints other than +/-1. Where there is any possibility of overflow,
-     * you should compare two longs with &lt; rather than subtraction.
-     * <p>
-     * In Pentium assembler you could implement this algorthm with following code:
-     * <pre>
-     *  # diff = edx:eax
-     *  # result = eax
-     *  mov ebx,eax
-     *  shl eax,1
-     *  or  eax,ebx
-     *  slr eax,1
-     *  or  eax,edx
-     * </pre>
-     * which would take 5 cycles, 2 more that lohi.  However, JET did even better,
-     * with code essentially this using a clever trick to implement piotr.
-     * <pre>
-     *   lea    ecx,0(eax,eax)  ; shifts lo left by doubling, keeps copy of
-     *   lo
-     *   or     eax,ecx
-     *   shr    eax,1
-     *   or     eax,edx
-     * </pre>
-     * This is 4 cycles, still one more than lohi. Why was Piotr so much
-     * faster on JET? Peter has no pipeline-confounding jumps. Further, the lo
-     * then high operands actually come from the ram-based stack. Piotr nicely
-     * separates the accesses giving plenty of for pre-emptive fetch of hi.
-     * lohi insists on having them both upfront, so it has to wait for memory
-     * access. Piotr does not have to wait. Modern CPUS hurry up and wait for
-     * RAM most of the time.
-     *
-     * @param diff number to be collapsed to an int preserving sign and
-     * zeroness. usually represents the difference of two long.
-     *
-     * @return sign of {@code diff}, some {@code int < 0}, 0 or some {@code int > 0}.
-     * @author Peter Kobzda
+     * Returns pseduo-signum.
+     * Returns some positive int for diff &gt; 0
+     * Returns some negative int for diff &lt; 0
+     *
+     * @param diff diff
+     * @return int
      */
     public static int signum(long diff) {
+        /*
+         * Alternative to signum for use in compare. Not a true signum, since it
+         * returns ints other than +/-1. Where there is any possibility of overflow,
+         * you should compare two longs with &lt; rather than subtraction.
+         * <p>
+         * In Pentium assembler you could implement this algorthm with following code:
+         * <pre>
+         *  # diff = edx:eax
+         *  # result = eax
+         *  mov ebx,eax
+         *  shl eax,1
+         *  or  eax,ebx
+         *  slr eax,1
+         *  or  eax,edx
+         * </pre>
+         * which would take 5 cycles, 2 more that lohi.  However, JET did even better,
+         * with code essentially this using a clever trick to implement piotr.
+         * <pre>
+         *   lea    ecx,0(eax,eax)  ; shifts lo left by doubling, keeps copy of
+         *   lo
+         *   or     eax,ecx
+         *   shr    eax,1
+         *   or     eax,edx
+         * </pre>
+         * This is 4 cycles, still one more than lohi. Why was Piotr so much
+         * faster on JET? Peter has no pipeline-confounding jumps. Further, the lo
+         * then high operands actually come from the ram-based stack. Piotr nicely
+         * separates the accesses giving plenty of for pre-emptive fetch of hi.
+         * lohi insists on having them both upfront, so it has to wait for memory
+         * access. Piotr does not have to wait. Modern CPUS hurry up and wait for
+         * RAM most of the time.
+         *
+         * @param diff number to be collapsed to an int preserving sign and
+         * zeroness. usually represents the difference of two long.
+         *
+         * @return sign of {@code diff}, some {@code int < 0}, 0 or some {@code int > 0}.
+         * @author Peter Kobzda
+         */
         return (int) (diff >>> 32) | ((int) diff | (int) diff << 1) >>> 1;
     }
 
+    /**
+     * Calculates floor( log2(x) )
+     *
+     * @param x x
+     * @return int
+     */
     public static int log2floor(int x) {
         return 31 - Integer.numberOfLeadingZeros(x);
     }
-    
+
+    /**
+     * Calculates floor( log2(x) )
+     *
+     * @param x x
+     * @return int
+     */
     public static int log2floor(long x) {
         return 63 - Long.numberOfLeadingZeros(x);
     }
 
+    /**
+     * Calculates ceil( log2(x) )
+     *
+     * @param x x
+     * @return int
+     */
     public static int log2ceil(int x) {
         return 32 - Integer.numberOfLeadingZeros(x - 1);
     }
-    
+
+    /**
+     * Calculates ceil( log2(x) )
+     *
+     * @param x x
+     * @return int
+     */
     public static int log2ceil(long x) {
         return 64 - Long.numberOfLeadingZeros(x - 1);
     }
     
     /**
-     * Return the least power of two greater than or equal to the specified
-     * value.
+     * Return the least power of two greater than or equal to the specified value.
      *
      * <p>Note that this function will return 1 when the argument is 0.
      *
@@ -145,8 +260,7 @@ public final class MathUtils {
     }
 
     /**
-     * Return the least power of two greater than or equal to the specified
-     * value.
+     * Return the least power of two greater than or equal to the specified value.
      *
      * <p>Note that this function will return 1 when the argument is 0.
      *
@@ -170,14 +284,33 @@ public final class MathUtils {
         return (x | x >> 32) + 1;
     }
 
+    /**
+     * Calculates a * a
+     *
+     * @param a a
+     * @return double
+     */
     public static double square(double a) {
         return a * a;
     }
-    
-    public static int gcd(int a, int b) { 
+
+    /**
+     * Calculates greates common divisor
+     *
+     * @param a a
+     * @param b b
+     * @return int
+     */
+    public static int gcd(int a, int b) {
         return b==0 ? a : gcd(b, a % b); 
     }
-    
+
+    /**
+     * Calculates greates common divisor
+     *
+     * @param values values
+     * @return int
+     */
     public static int gcd(int... values) {
         int ret = gcd(values[0], values[1]);
         for(int i=2; i<values.length; i++) {
@@ -185,11 +318,24 @@ public final class MathUtils {
         }
         return ret;
     }
-    
-    public static long gcd(long a, long b) { 
+
+    /**
+     * Calculates greates common divisor
+     *
+     * @param a a
+     * @param b b
+     * @return long
+     */
+    public static long gcd(long a, long b) {
         return b==0 ? a : gcd(b, a % b); 
     }
-    
+
+    /**
+     * Calculates greates common divisor
+     *
+     * @param values values
+     * @return long
+     */
     public static long gcd(long... values) {
         long ret = gcd(values[0], values[1]);
         for(int i=2; i<values.length; i++) {
@@ -197,11 +343,24 @@ public final class MathUtils {
         }
         return ret;
     }
-    
+
+    /**
+     * Calculates least common multiple
+     *
+     * @param a a
+     * @param b a
+     * @return int
+     */
     public static int lcm(int a, int b) {
         return (a / gcd(a,b)) * b;
     }
-    
+
+    /**
+     * Calculates least common multiple
+     *
+     * @param values values
+     * @return int
+     */
     public static int lcm(int... values) {
         int ret = lcm(values[0], values[1]);
         for(int i=2; i<values.length; i++) {
@@ -209,11 +368,24 @@ public final class MathUtils {
         }
         return ret;
     }
-    
+
+    /**
+     * Calculates least common multiple
+     *
+     * @param a a
+     * @param b b
+     * @return long
+     */
     public static long lcm(long a, long b) {
         return (a/ gcd(a,b) ) * b;
     }
-    
+
+    /**
+     * Calculates least common multiple
+     *
+     * @param values values
+     * @return long
+     */
     public static long lcm(long... values) {
         long ret = lcm(values[0], values[1]);
         for(int i=2; i<values.length; i++) {
@@ -278,43 +450,5 @@ public final class MathUtils {
         return clip(adds(x,y), min, max);
     }
 
-    public static double ulp(double x) {
-        return x < 0 ? nextUp(x) - x : x - nextDown(x);
-    }
-
-    public static double nextDown(double x) {
-        return -nextUp(-x);
-    }
-
-    public static double nextUp(double x) {
-        if (x != x) {
-            return x;
-        }
-        if (x == -1 / 0) {
-            return -MAX_VALUE;
-        }
-        if (x == +1 / 0) {
-            return +1 / 0;
-        }
-        if (x == +MAX_VALUE) {
-            return +1 / 0;
-        }
-        double y = x * (x < 0 ? 1 - EPSILON / 2 : 1 + EPSILON);
-        if (y == x) {
-            y = MIN_VALUE * EPSILON > 0 ? x + MIN_VALUE * EPSILON : x + MIN_VALUE;
-        }
-        if (y == +1 / 0) {
-            y = +MAX_VALUE;
-        }
-        double b = x + (y - x) / 2;
-        if (x < b && b < y) {
-            y = b;
-        }
-        double c = (y + x) / 2;
-        if (x < c && c < y) {
-            y = c;
-        }
-        return y == 0 ? -0 : y;
-    }
 }
 

assira.core/src/main/java/net/ranides/assira/math/MutableBoolean.java

@@ -2,25 +2,45 @@ package net.ranides.assira.math;
 
 import java.io.Serializable;
 
+/**
+ * Mutable boolean wrapper class
+ */
 public class MutableBoolean implements Comparable<MutableBoolean>, Serializable {
 
     private static final long serialVersionUID = 2L;
 
     private boolean value;
 
+    /**
+     * Create new instance of MutableBoolean
+     *
+     * @param value value
+     */
     public MutableBoolean(boolean value) {
         this.value = value;
     }
 
+    /**
+     * Changes current value
+     * @param value value
+     */
     public void set(boolean value) {
         this.value = value;
     }
 
 
+    /**
+     * Changes current value to negated one
+     */
     public void negate() {
         this.value = !value;
     }
 
+    /**
+     * Returns current value
+     *
+     * @return boolean
+     */
     public boolean get() {
         return this.value;
     }

assira.core/src/main/java/net/ranides/assira/math/MutableNumber.java

@@ -2,46 +2,118 @@ package net.ranides.assira.math;
 
 import java.math.BigInteger;
 
+/**
+ * This abstract class is, obviously, base class for all mutable numbers
+ */
 public abstract class MutableNumber extends Number {
 
+    /**
+     * Mutable operation: this = value
+     *
+     * @param value value
+     */
     public abstract void set(Number value);
 
+    /**
+     * Mutable operation: this++
+     */
     public abstract void increment();
 
+    /**
+     * Mutable operation: this--
+     */
     public abstract void decrement();
 
+    /**
+     * Mutable operation: this += value
+     *
+     * @param value value
+     */
     public abstract void add(Number value);
 
+    /**
+     * Mutable operation: this -= value
+     *
+     * @param value value
+     */
     public abstract void subtract(Number value);
 
+    /**
+     * Mutable operation: this /= value
+     *
+     * @param value value
+     */
     public abstract void divide(Number value);
 
+    /**
+     * Mutable operation: this *= value
+     *
+     * @param value value
+     */
     public abstract void multiply(Number value);
 
+    /**
+     * Mutable operation: this = pow(this, value)
+     *
+     * @param value value
+     */
     public abstract void pow(Number value);
 
+    /**
+     * Mutable operation: this = -this
+     */
     public abstract void negate();
 
+    /**
+     * Mutable operation: this = abs(this)
+     */
     public abstract void abs();
 
+    /**
+     * Creates new MutableInteger
+     *
+     * @param value value
+     * @return MutableNumber
+     */
     public static MutableInteger of(int value) {
         return new MutableInteger(value);
     }
 
+    /**
+     * Creates new MutableLong
+     *
+     * @param value value
+     * @return MutableNumber
+     */
     public static MutableLong of(long value) {
         return new MutableLong(value);
     }
 
+    /**
+     * Creates new MutableDouble
+     *
+     * @param value value
+     * @return MutableNumber
+     */
     public static MutableDouble of(double value) {
         return new MutableDouble(value);
     }
 
+    /**
+     * This class is, obviously, mutable integer
+     */
     public static class MutableInteger extends MutableNumber implements Comparable<MutableInteger> {
 
         private static final long serialVersionUID = 2L;
 
         private int value;
 
+        /**
+         * Default constructor.
+         * Factory method "MutableNumber.of" is preffered over calling constructors.
+         *
+         * @param value value
+         */
         public MutableInteger(int value) {
             this.value = value;
         }
@@ -76,6 +148,11 @@ public abstract class MutableNumber extends Number {
             this.value = value.intValue();
         }
 
+        /**
+         * Mutable operation:  this = value
+         *
+         * @param value value
+         */
         public void set(int value) {
             this.value = value;
         }
@@ -90,18 +167,38 @@ public abstract class MutableNumber extends Number {
             this.value--;
         }
 
+        /**
+         * Mutable operation: this++
+         *
+         * @return value before increment
+         */
         public int getAndIncrement() {
             return this.value++;
         }
 
+        /**
+         * Mutable operation: ++this
+         *
+         * @return value atfer increment
+         */
         public int incrementAndGet() {
             return ++this.value;
         }
 
+        /**
+         * Mutable operation: this--
+         *
+         * @return value before decrement
+         */
         public int getAndDecrement() {
             return this.value--;
         }
 
+        /**
+         * Mutable operation: --this
+         *
+         * @return value after decrement
+         */
         public int decrementAndGet() {
             return --this.value;
         }
@@ -143,12 +240,21 @@ public abstract class MutableNumber extends Number {
 
     }
 
+    /**
+     * This class is, obviously, mutable long
+     */
     public static class MutableLong extends MutableNumber implements Comparable<MutableLong> {
 
         private static final long serialVersionUID = 2L;
 
         private long value;
 
+        /**
+         * Default constructor.
+         * Factory method "MutableNumber.of" is preffered over calling constructors.
+         *
+         * @param value value
+         */
         public MutableLong(long value) {
             this.value = value;
         }
@@ -183,6 +289,11 @@ public abstract class MutableNumber extends Number {
             this.value = value.longValue();
         }
 
+        /**
+         * Mutable operation:  this = value
+         *
+         * @param value value
+         */
         public void set(long value) {
             this.value = value;
         }
@@ -197,18 +308,38 @@ public abstract class MutableNumber extends Number {
             this.value--;
         }
 
+        /**
+         * Mutable operation: this++
+         *
+         * @return value before increment
+         */
         public long getAndIncrement() {
             return this.value++;
         }
 
+        /**
+         * Mutable operation: ++this
+         *
+         * @return value atfer increment
+         */
         public long incrementAndGet() {
             return ++this.value;
         }
 
+        /**
+         * Mutable operation: this--
+         *
+         * @return value before decrement
+         */
         public long getAndDecrement() {
             return this.value--;
         }
 
+        /**
+         * Mutable operation: --this
+         *
+         * @return value after decrement
+         */
         public long decrementAndGet() {
             return --this.value;
         }
@@ -250,12 +381,21 @@ public abstract class MutableNumber extends Number {
 
     }
 
+    /**
+     * This class is, obviously, mutable double
+     */
     public static class MutableDouble extends MutableNumber implements Comparable<MutableDouble> {
 
         private static final long serialVersionUID = 2L;
 
         private double value;
 
+        /**
+         * Default constructor.
+         * Factory method "MutableNumber.of" is preffered over calling constructors.
+         *
+         * @param value value
+         */
         public MutableDouble(double value) {
             this.value = value;
         }
@@ -290,6 +430,11 @@ public abstract class MutableNumber extends Number {
             this.value = value.doubleValue();
         }
 
+        /**
+         * Mutable operation:  this = value
+         *
+         * @param value value
+         */
         public void set(double value) {
             this.value = value;
         }
@@ -304,18 +449,38 @@ public abstract class MutableNumber extends Number {
             this.value--;
         }
 
+        /**
+         * Mutable operation: this++
+         *
+         * @return value before increment
+         */
         public double getAndIncrement() {
             return this.value++;
         }
 
+        /**
+         * Mutable operation: ++this
+         *
+         * @return value atfer increment
+         */
         public double incrementAndGet() {
             return ++this.value;
         }
 
+        /**
+         * Mutable operation: this--
+         *
+         * @return value before decrement
+         */
         public double getAndDecrement() {
             return this.value--;
         }
 
+        /**
+         * Mutable operation: --this
+         *
+         * @return value after decrement
+         */
         public double decrementAndGet() {
             return --this.value;
         }

assira.core/src/main/java/net/ranides/assira/math/NumberTraits.java

@@ -2,13 +2,28 @@ package net.ranides.assira.math;
 
 import lombok.experimental.UtilityClass;
 
+/**
+ * Some utility methods for checking number characterictics
+ */
 @UtilityClass
 public class NumberTraits {
 
+    /**
+     * Returns true if value is odd (not multiple of 2)
+     *
+     * @param value value
+     * @return boolean
+     */
     public static boolean isOdd(int value) {
         return value % 2 == 1;
     }
 
+    /**
+     * Returns true if value is even (multiple of 2)
+     *
+     * @param value value
+     * @return boolean
+     */
     public static boolean isEven(int value) {
         return value % 2 == 0;
     }