CHANGELOG.txt

################################################################################
Jafama 2.3.2, 2020/08/18

- Added Automatic-Module-Name attribute to the manifest,
  for Java Platform Module System (request from AndreasWBartels).

- Build: corrected an issue in JfmJavacHelper, which was always using ';'
  as classpath separator, instead of ':' by default and ';' only on Windows.

- Little code cleanups.

- Removed AllTests class (instead just launch tests from the IDE project).

- Changed README to use Markdown.

################################################################################
Jafama 2.3.1, 2017/12/09

- Removed empty-name entry from jar generation, which was taking the name of
  the jar (jafama) in the result, and was causing issues with some software,
  cf. JDK 8182377.

- Refactored build code, creating a new JfmJavacHelper class.

################################################################################
Jafama 2.3, 2017/11/22

- Moved change log from README.txt to the new CHANGELOG.txt file
  (pull request from rogersachan).
  Moved most overall description from (Strict)FastMath Javadoc to README.txt.
  Added TODOLIST.txt.

- Added src/build to git. The main builds the jar with JavaCompiler and
  JarOutputStream (was previously built using JDK5 javac and jar executables).
  Also now compiled with "-g:vars" option, for proper arguments names instead
  of arg0, arg1, etc., and the manifest contains the implementation version.

- (Strict)FastMath:
  - Little optimization of round(float) and round(double), by replacing
    an "if" with a multiplication (JDK team didn't see it as an improvement,
    so in the JDK the "if" stays, and you can choose which you prefer).
  - Added methods:
    - floorToInt(double)
    - ceilToInt(double)
    - roundToInt(double)
    - roundEvenToInt(double)
    The point of these methods is that wanting to floor/ceil/round a double
    into an int is a very common use case, and that Math methods don't make it
    easy:
    - Math.floor/ceil(double) return a double, which requires a cast to int.
    - Math.round(double) returns a long, which people often cast carelessly
      into an int, ending with completely wrong result if the long is out of
      int range.
    - Math.rint(double) returns a double, which requires a cast to int,
      it doesn't round the same way, and most users might not know it even
      exists.
    Also, it can be faster to compute the int directly than to first compute
    an intermediary long or double.
    The names of these methods should make them easily discoverable with
    auto completion.
    We don't provide similar methods for returning shorts or bytes, for these
    use cases should be much less frequent, and it's easy to implement them
    without much overhead by taking the resulting int back into short or byte
    range.
    We also don't provide a rintToInt(double) method, for it would behave
    the same as roundEvenToInt(double).
    NB: Since (Strict)FastMath look-up tables are now lazily created, there is
    no strong need to also have these low level methods in NumbersUtils.
  - Added comment in round(double) to indicate why it never delegates to JDK
    (pull request from kno10).

- Replaced incorrect section sign (0xA7) in comment, with proper dollar sign
  (found out while looking at
  https://github.com/Trugath/Jafama/commit/746ad1e87aca273ae5fe558a846b6edc8a8634aa).

- floor/ceil/round benches:
  - Separate positive and negative values ranges.
  - Changed or added reference treatments.

################################################################################
Jafama 2.2, 2015/12/13

- Using a more standard layout for files.

- Renamed AbstractFastMath into CmnFastMath, and factored non floating point
  methods common to FastMath and StrictFastMath here, as well as E and PI
  constants.
  Also factored out corresponding tests in a new test class.
  As a result, abs(int) and abs(long) now delegate to Math (and not StrictMath,
  which usually delegates to Math for non floating point methods) when EITHER
  FastMath or StrictFastMath delegation options are activated.

- (Strict)FastMath:
  - Look-up tables are now (by default) lazily initialized, per method type
    (i.e. calling sin(double) won't initialize look-up tables for exp(double)).
    As a result, methods of (Strict)FastMath that don't use tables can now
    safely be called from code that don't want to trigger tables initialization.
  - Added a static initTables() method, which ensures their initialization to
    avoid related slow-down later at runtime (one call from either FastMath or
    StrictFastMath inits tables for both classes).
  - Reordered "ifs" in nextAfter(float,double) and nextAfter(double,double),
    for faster worse case (as I should already have done when submitting
    JDK-8032016).
  - In powFast(double,int), reworked "ifs" to reduce the amount of code
    while preserving special cases for small powers. Is now also a tad faster.
  - Added methods:
    - From JDK-8023217:
      - multiplyExact(long,int)
      - floorDiv(long,int)
      - floorMod(long,int)
    - From JDK-5100935:
      - multiplyFull(int,int)
      - multiplyHigh(long,long)
    - That were not added previously, for Math versions being preferable due to
      eventual JVM intrinsics, but that I finally decided to add for the sake of
      completeness:
      - incrementExact(int)
      - incrementExact(long)
      - decrementExact(int)
      - decrementExact(long)
      - negateExact(int)
      - negateExact(long)
    - And finally, since we mirror each xxxExact method with a xxxBounded
      version:
      - multiplyBounded(long,int)
      - incrementBounded(int)
      - incrementBounded(long)
      - decrementBounded(int)
      - decrementBounded(long)
      - negateBounded(int)
      - negateBounded(long)

- NumbersUtils:
  - Added methods:
    - From (Strict)FastMath, so that they can be used to depart +0.0(f)
      from -0.0(f) (which is a quite low-level need) without having to depend
      on (Strict)FastMath:
      - signFromBit(float)
      - signFromBit(double)
    - Following request from P. Wendykier:
      - twoPowAsIntExact(int)
      - twoPowAsIntBounded(int)
      - twoPowAsLongExact(int)
      - twoPowAsLongBounded(int)

################################################################################
Jafama 2.1, 2014/04/30

- FastMath:
  - Added hypot(double,double,double), which computes sqrt(x^2+y^2+z^2) without
    intermediate overflow or underflow.
  - Made reduction more accurate for angles of large magnitudes, by using
    reduction in [-PI/4,PI/4] and quadrant information stored in two useless
    bits of exponent, rather than reduction in [-PI,PI].
  - Added use of TWOPI_LO and TWOPI_HI in some normalization methods, to make
    them more accurate for results near quadrants limits.
  - Corrected the spec about range of reliable accuracy for sinQuick(double).
  - Little optimization for large angles reduction for tan(double).
  - For round(float) and round(double), now using algorithm by Dmitry Nadezhin
    (http://mail.openjdk.java.net/pipermail/core-libs-dev/2013-August/020247.html).
  - scalb(double) is now faster for non-huge values of scale factor
    (the same optimization, didn't seem to be worth it for float case).

- Added StrictFastMath, a strict version of FastMath (and not a fast version of
  StrictMath!), and related versions of FastMath properties:
  - jafama.strict.usejdk,
  - jafama.strict.fastlog,
  - jafama.strict.fastsqrt.
  Note that now, to avoid look-up tables and their initialization overhead,
  you must set both jafama.usejdk (which only applies to FastMath) and
  jafama.strict.usejdk to true.

- NumbersUtils:
  - Added DOUBLE_MIN_NORMAL and FLOAT_MIN_NORMAL constants (Double.MIN_NORMAL
    and Float.MIN_NORMAL being available only from Java 6).
  - Added methods:
    - absNeg(int) (returns -abs(value), exact even for Integer.MIN_VALUE)
    - absNeg(long) (returns -abs(value), exact even for Long.MIN_VALUE)
    - pow2_strict(float)
    - pow2_strict(double)
    - pow3_strict(float)
    - pow3_strict(double)
    - plus2PI(double)
    - plus2PI_strict(double)
    - minus2PI(double)
    - minus2PI_strict(double)
    - plusPI(double)
    - plusPI_strict(double)
    - minusPI(double)
    - minusPI_strict(double)
    - plusPIO2(double)
    - plusPIO2_strict(double)
    - minusPIO2(double)
    - minusPIO2_strict(double)
    - toStringCSN(double) (to get "1.5E1" or "1.0E-1", instead of "15.0" or
      "0.1")
    - toStringNoCSN(double) (to get "123456789.0" or "0.0001", instead of
      "1.23456789E8" or "1.0E-4")
  - Optimized floorPowerOfTwo(int) and ceilingPowerOfTwo(int).

################################################################################
Jafama 2.0, 2013/02/20

- Changed license from GNU LGPL V3 to Apache V2.

- Is now Java 5 compatible (but some unit tests require Java 6).

- Renamed package from odk.lang into net.jafama.

- Renamed properties from odk.fastmath.xxx into jafama.xxx.

- To match upcoming JDK8's new Math methods, renamed:
  - toIntSafe into toIntExact (and asInt in NumbersUtils)
  - plusNoModulo into addBounded (and plusBounded in NumbersUtils)
  - plusNoModuloSafe into addExact (and plusExact in NumbersUtils)
  - minusNoModulo into subtractBounded (and minusBounded in NumbersUtils)
  - minusNoModuloSafe into subtractExact (and minusExact in NumbersUtils)
  - timesNoModulo into multiplyBounded (and timesBounded in NumbersUtils)
  - timesNoModuloSafe into multiplyExact (and timesExact in NumbersUtils)

- Corrected Javadoc (accuracy claims) for some xxxQuick methods.

- Removed usage of strictfp, which can cause an overhead.
  As a result, behavior might change depending on architecture,
  as well as dynamically due to JIT (ex.: pow2(double)).

- Minor typos, refactorings and doc enhancements.

- NumbersUtils:
  - Renamed mask methods, such as leftBit0LongMask into longMaskMSBits0.
  - Added methods:
    - isMathematicalInteger(float)
    - isMathematicalInteger(double)
    - isEquidistant(float)
    - isEquidistant(double)
    - isNaNOrInfinite(float)
  - Upgraded some implementations.

- FastMath:
  - In spec., added warning about possible FastMath slowness and
    initialization overhead.
  - FastMath now only depends on Java 5, and therefore, when delegating to
    Math, only does so for Math methods that exist in Java 5 and have the
    same semantics (except for accuracy).
  - Modified some treatments for JVM crash after JIT-optimization to
    (hopefully) not occur (crashes observed with Java 6u29, with which
    workarounds were tested).
  - Removed usage of StrictMath, and related property, which is allowed due
    to spec. relaxation by strictfp removal, to make things both simpler,
    and possibly faster.
    As a result, for FastMath.log(double), we now use Math.log(double) by
    default instead of our redefined method, which was used before due to
    StrictMath.log(double) being possibly very slow. This makes log10(double),
    log1p(double), logQuick(double), pow(double,double) and
    powQuick(double,double) more accurate.
  - Changed sinAndCos(double,DoubleWrapper,DoubleWrapper) into
    sinAndCos(double,DoubleWrapper), and
    sinhAndCosh(double,DoubleWrapper,DoubleWrapper) into
    sinhAndCosh(double,DoubleWrapper).
  - exp(double) is now more accurate (removed special handling for subnormals,
    which is useless with proper multiplications order).
    This makes hyperbolic trigonometry functions, expm1(double),
    pow(double,double) and powQuick(double,double) more accurate.
  - round(float) and round(double) now no longer follow Math class, which
    spec. and behavior changed over time, but just round-up properly.
  - For asinInRange and acosInRange, replaced < and > with <= and >=,
    for quick return in case input is a bound.
  - Removed internal usage of look-up table to compute double powers of two,
    for it doesn't speed things up much, and to avoid possible cache-misses
    for methods that are now table-free.
  - Added methods:
    - coshm1(double)
    - asinh(double)
    - acosh(double)
    - acosh1p(double)
    - atanh(double)
    - log10(double)
    - sqrtQuick(double)
    - invSqrtQuick(double)
    - roundEven(float)
    - roundEven(double)
    - rint(float)
    - rint(double)
    - abs(long)
    - floorDiv(int,int)
    - floorDiv(long,long)
    - floorMod(int,int)
    - floorMod(long,long)
    - isNaNOrInfinite(float)
    - signum(float)
    - signum(double)
    - signFromBit(float)
    - signFromBit(double)
    - copySign(float,float)
    - copySign(double,double)
    - ulp(float)
    - ulp(double)
    - nextAfter(float,double)
    - nextAfter(double,double)
    - nextDown(float)
    - nextDown(double)
    - nextUp(float)
    - nextUp(double)
    - scalb(float,int)
    - scalb(double,int)
  - Separated accuracy/correctness tests from benches, and
    improved/simplified both.

################################################################################
Jafama 1.2, 2011/03/19

- Now using StrictMath to compute constants and look-up tables, to ensure
  consistency across various architectures.

- Now using Math.abs(double) directly instead of FastMath.abs(double), since
  this method is not redefined.

- Added PI_SUP constant, the closest upper approximation of Pi as double,
  especially useful to define a span that covers full angular range
  (2*Math.PI doesn't).

- Added log2(long), log2(int).

- Added odk.fastmath.strict, odk.fastmath.usejdk, odk.fastmath.fastlog and
  odk.fastmath.fastsqrt properties. See FastMath Javadoc for details.
  NB: As a consequence, by default, a redefined log(double) is now used instead
      of Math.log(double), for non-redefined treatments now use StrictMath by
      default, and StrictMath.log(double) seems usually slow.

- Simplified toString() implementation for IntWrapper and DoubleWrapper classes.

- Completed Javadoc and updated tests for FastMath.remainder(double,double)
  method, which does not behave as Math.IEEEremainder(double,double).

- Moved some basic numbers related treatments, into a new class (NumbersUtils),
  since they are very low-level and can be used in many places where a
  dependency to the heavy (look-up tables) FastMath class could be considered
  inappropriate.
  These treatments are still available from FastMath class.

- In benches, made sure dummy variables are used, to avoid treatments to be
  optimized away (has not been observed, but might have been with some JVMs).

################################################################################
Jafama 1.1, 2009/12/05

- for asin pow tabs, use of powFast(double,int) instead of pow(double,double),

- added expQuick(double), logQuick(double), powQuick(double),

- changed random numbers computation for tests.

################################################################################
Jafama 1.0, 2009/07/25

- Placed under the GNU Lesser General Public License, version 3.

- Requires Java 1.6 or later.

- src folder contains the code.

- test folder contains some tests (some of which require JUnit).

- The odk.lang package is due to this code being a core part of ODK
  library (Optimized Development Kit, of which only this code is
  open source).

- Copy/paste of FastMath class comments:

 * Class providing math treatments that:
 * - are meant to be faster than those of java.lang.Math class (depending on
 *   JVM or JVM options, they might be slower),
 * - are still somehow accurate and robust (handling of NaN and such),
 * - do not (or not directly) generate objects at run time (no "new").
 * 
 * Other than optimized treatments, a valuable feature of this class is the
 * presence of angles normalization methods, derived from those used in
 * java.lang.Math (for which, sadly, no API is provided, letting everyone
 * with the terrible responsibility to write their own ones).
 * 
 * Non-redefined methods of java.lang.Math class are also available,
 * for easy replacement.
 
################################################################################