Author: aherbert
Date: Tue Apr 21 14:22:40 2026
New Revision: 1092800
Log:
Use prettyprint for code sections
Modified:
websites/production/commons/content/proper/commons-numbers/userguide/index.html
Modified:
websites/production/commons/content/proper/commons-numbers/userguide/index.html
==============================================================================
---
websites/production/commons/content/proper/commons-numbers/userguide/index.html
Tue Apr 21 14:19:42 2026 (r1092799)
+++
websites/production/commons/content/proper/commons-numbers/userguide/index.html
Tue Apr 21 14:22:40 2026 (r1092800)
@@ -19,7 +19,7 @@
<script type="text/javascript" src="../js/site.js"></script>
<script
id="MathJax-script" async
src="https://commons.apache.org/js/mathjax/tex-mml-chtml.js";></script>
-<link rel="stylesheet" href="../style/module.css" type="text/css" />
+<link rel="stylesheet" href="../style/module.css" type="text/css" />
</head>
<body class="composite">
@@ -37,7 +37,7 @@
<div class="navbar-inner">
<div class="container-fluid">
<a class="brand"
href="http://commons.apache.org/proper/commons-numbers/";>Apache Commons Numbers
™</a>
- <ul class="nav">
+ <ul class="nav">
<li id="publishDate">Last Published: 15 Apr 2026</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.3</li>
</ul>
@@ -265,16 +265,16 @@
<h1>Angle</h1>
<p>The <a href="../commons-numbers-angle/index.html">commons-numbers-angle</a>
module provides utilities related to the concept of angle (<a
href="../commons-numbers-angle/apidocs/org/apache/commons/numbers/angle/package-summary.html">angle
API</a>).</p>
<p>The <code>Angle</code> class can be used to convert angles between common
units. Sub-classes are used to represent the angle units of degrees, radians
and turn.</p>
-<pre><code>Angle.Deg a = Angle.Turn.of(0.5).toDeg();
+<pre class="prettyprint"><code>Angle.Deg a = Angle.Turn.of(0.5).toDeg();
Angle.Rad b = a.toRad();
Angle.Turn c = b.toTurn();
// c.getAsDouble() == 0.5</code></pre>
<p>A normalizer can be used to map any value to the natural interval of the
angle unit around a provided lower bound, for example <code>[lo, lo +
360)</code> for degrees:</p>
-<pre><code>// Range: [-180, 180)
+<pre class="prettyprint"><code>// Range: [-180, 180)
double angle = Angle.Deg.normalizer(-180).applyAsDouble(270);
// angle == -90.0</code></pre>
<p>The normalizer makes use of the <code>Reduce</code> class which can be
applied to any interval:</p>
-<pre><code>Reduce reduce = new Reduce(0, 24);
+<pre class="prettyprint"><code>Reduce reduce = new Reduce(0, 24);
double hours1 = reduce.applyAsDouble(173.5);
double hours2 = reduce.applyAsDouble(23.5);
double hours3 = reduce.applyAsDouble(-10);
@@ -285,7 +285,7 @@ double hours3 = reduce.applyAsDouble(-10
<p>The <code>CosAngle</code> class computes the cosine of the angle between
two vectors using the dot product of two vectors and their magnitudes:</p>
<p>\( \cos\theta = \frac{\mathbf{a}\cdot\mathbf{b}}{
|\mathbf{a}| |\mathbf{b}| } \)</p>
<p>The computation uses extended precision methods to increase the overall
accuracy of the result at the cost of a moderate increase in the number of
computations.</p>
-<pre><code>double[] v1 = {1, 0};
+<pre class="prettyprint"><code>double[] v1 = {1, 0};
double[] v2 = {0, 1};
double[] v3 = {7, 7};
double cosAngle1 = CosAngle.value(v1, v1);
@@ -298,7 +298,7 @@ double cosAngle3 = CosAngle.value(v1, v3
<h1>Arrays</h1>
<p>The <a
href="../commons-numbers-arrays/index.html">commons-numbers-arrays</a> module
provides array utilities (<a
href="../commons-numbers-arrays/apidocs/org/apache/commons/numbers/arrays/package-summary.html">arrays
API</a>).</p>
<p>The <code>SortInPlace</code> class can sort a number of arrays using the
order imposed by a specified array:</p>
-<pre><code>double[] x = {3, 1, 2};
+<pre class="prettyprint"><code>double[] x = {3, 1, 2};
double[] y = {1, 2, 3};
double[] z = {0, 5, 7};
SortInPlace.ASCENDING.apply(x, y, z);
@@ -306,7 +306,7 @@ SortInPlace.ASCENDING.apply(x, y, z);
// y == [2, 3, 1]
// z == [5, 7, 0]</code></pre>
<p>The <code>MultidimensionalCounter</code> provides a mapping between a
unidimensional storage and a multidimensional conceptual structure. Note that
successive values for the unidimensional index are used for successive values
of the <i>last</i> index in the indices of the multidimensional structure. When
the dimension size is reached the values roll-over to the next dimension. The
class ensures a 1-to-1 mapping from any index within the size to a
multidimensional position.</p>
-<pre><code>MultidimensionalCounter c = MultidimensionalCounter.of(100, 50);
+<pre class="prettyprint"><code>MultidimensionalCounter c =
MultidimensionalCounter.of(100, 50);
int size = c.getSize();
// size == 5000
@@ -325,7 +325,7 @@ c.toMulti(50) // [ 1, 0]
c.toMulti(4999) // [99, 49]</code></pre>
<p>The <code>Selection</code> class provides partial sorting of an array.
Selection arranges elements such that indices <code>k</code> correspond to
their correctly sorted value in the equivalent fully sorted array. Selection is
the same as performing a sort and stopping early when all the desired positions
are correctly ordered. In most cases of unordered data, selection will perform
faster than a full sort when only some indices from a sorted array are
required.</p>
<p>The following example shows how partial ordering of the elements occurs for
selection of indices <code>4</code> or <code>[4, 8]</code> from an array:</p>
-<pre><code>data [0, 1, 2, 1, 2, 5, 2, 3, 3, 6, 7, 7, 7, 7]
+<pre class="prettyprint"><code>data [0, 1, 2, 1, 2, 5, 2, 3, 3, 6, 7, 7, 7,
7]
k=4 : [0, 2, 1, 1], [2], [6, 3, 2, 3, 5, 7, 7, 7, 7]
k=4,8 : [0, 1, 2, 1], [2], [3, 3, 2], [5], [7, 7, 6, 7, 7]</code></pre>
@@ -336,7 +336,7 @@ k=4,8 : [0, 1, 2, 1], [2], [3, 3, 2], [5
<li>Correct usage for multiple target indices should <b>not</b> call multiple
times with each index but instead call selection only once with all indices.
Use of consecutive calls can reorder previously selected indices.</li>
<li>Calls with multiple indices are more efficient if the indices are ordered
but the method will accept unordered and duplicate indices.</li></ul>
<p>The equivalent in code is:</p>
-<pre><code>int[] data = {0, 1, 2, 1, 2, 5, 2, 3, 3, 6, 7, 7, 7, 7};
+<pre class="prettyprint"><code>int[] data = {0, 1, 2, 1, 2, 5, 2, 3, 3, 6, 7,
7, 7, 7};
Selection.select(data, 4); // data[4] == 2
Selection.select(data, new int[] {4, 8}); // data[4] == 2, data[8] ==
5</code></pre>
@@ -344,14 +344,14 @@ Selection.select(data, new int[] {4, 8})
<h1>Combinatorics</h1>
<p>The <a
href="../commons-numbers-combinatorics/index.html">commons-numbers-combinatorics</a>
module provides combinatorics utilities such as factorial and binomial
coefficients (<a
href="../commons-numbers-combinatorics/apidocs/org/apache/commons/numbers/combinatorics/package-summary.html">combinatorics
API</a>).</p>
<p>The binomial coefficient \( \binom{n}{k} \) can be evaluated as a
<code>long</code>, <code>double</code> or using the natural logarithm.</p>
-<pre><code>long bc1 = BinomialCoefficient.value(63, 33);
+<pre class="prettyprint"><code>long bc1 = BinomialCoefficient.value(63, 33);
double bc2 = BinomialCoefficientDouble.value(1029, 514);
double bc3 = LogBinomialCoefficient.value(152635712, 125636);
// bc1 == 7219428434016265740
// bc2 ~ 1.429820686498904e308
// bc3 ~ 1017897.199659759</code></pre>
<p>The factorial \( n! \) can be evaluated as a <code>long</code>,
<code>double</code> or using the natural logarithm.</p>
-<pre><code>long f1 = Factorial.value(15);
+<pre class="prettyprint"><code>long f1 = Factorial.value(15);
double f2 = Factorial.doubleValue(170);
double f3 = LogFactorial.create().value(Integer.MAX_VALUE);
// f1 == 1307674368000
@@ -359,19 +359,19 @@ double f3 = LogFactorial.create().value(
// f3 == 4.3996705655378525e10</code></pre>
<p>Note that if the binomial coefficient or factorial cannot be represented
the methods will throw an <code>ArithmeticException</code> in-place of a
<code>long</code> value or return infinity in-place of a <code>double</code>
value. The logarithm methods will always compute a valid result given the
bounds imposed by the <code>int</code> arguments.</p>
<p>The <code>LogFactorial</code> class can be created with a cache size. All
values up to this size are computed upon creation. This functionality can be
used when a range of values may be repeatedly required.</p>
-<pre><code>LogFactorial lf = LogFactorial.create().withCache(50);</code></pre>
+<pre class="prettyprint"><code>LogFactorial lf =
LogFactorial.create().withCache(50);</code></pre>
<p>Values outside the cache are computed using <code>LogGamma.value(n +
1.0)</code> from the <a href="#Gamma">Gamma</a> module; this can be used to
avoid the object creation of a single-use instance of LogFactorial.</p>
<p>The combinations defined by the binomial coefficient \( \binom{n}{k} \) can
be iterated using the <code>Combinations</code> class:</p>
-<pre><code>Combinations.of(4, 2).iterator().forEachRemaining(c ->
System.out.println(Arrays.toString(c)));</code></pre>
+<pre class="prettyprint"><code>Combinations.of(4,
2).iterator().forEachRemaining(c ->
System.out.println(Arrays.toString(c)));</code></pre>
<p>Outputs:</p>
-<pre><code>[0, 1]
+<pre class="prettyprint"><code>[0, 1]
[0, 2]
[1, 2]
[0, 3]
[1, 3]
[2, 3]</code></pre>
<p>The lexigraphical order is based on the values in the input array in
reverse order. This ordering can be imposed on arbitrary sets using the
<code>Comparator<int[]></code> provided by an appropriate
<code>Combination</code>:</p>
-<pre><code>List<int[]> list = Arrays.asList(new int[][] {
+<pre class="prettyprint"><code>List<int[]> list = Arrays.asList(new
int[][] {
{3, 4, 5},
{3, 1, 5},
{3, 2, 5},
@@ -380,12 +380,12 @@ double f3 = LogFactorial.create().value(
list.sort(Combinations.of(6, 3).comparator());
list.forEach(c -> System.out.println(Arrays.toString(c)));</code></pre>
<p>Outputs:</p>
-<pre><code>[4, 2, 4]
+<pre class="prettyprint"><code>[4, 2, 4]
[3, 1, 5]
[3, 2, 5]
[3, 4, 5]</code></pre>
<p>The <code>Stirling</code> class can evaluate Stirling numbers of the first
kind and second kind. The Stirling numbers of the first kind \( s(n, k) \)
arise in the study of permutations, particularly counting the permutations of a
set according to their number of cycles. The Stirling number of the second kind
\( S(n, k) \) is the number of ways of partitioning a set of \( n \) elements
into \( k \) non-empty subsets. For example a set of 3 elements may be
partitioned into:</p>
-<pre><code>Stirling.stirlingS2(3, 3) // 1 : {{1}, {2}, {3}}
+<pre class="prettyprint"><code>Stirling.stirlingS2(3, 3) // 1 : {{1}, {2},
{3}}
Stirling.stirlingS2(3, 2) // 3 : {{1, 2}, {3}}, {{1, 3}, {2}} and {{1},
{2, 3}}
Stirling.stirlingS2(3, 1) // 1 : {{1, 2, 3}}</code></pre>
<p>The evaluation is limited by the <code>long</code> datatype and the method
will raise an <code>ArithmeticException</code> if the result cannot be
represented.</p></section><section><a id="Complex"></a>
@@ -393,7 +393,7 @@ Stirling.stirlingS2(3, 1) // 1 : {{1
<p>The <a
href="../commons-numbers-complex/index.html">commons-numbers-complex</a> module
provides utilities for working with complex numbers (<a
href="../commons-numbers-complex/apidocs/org/apache/commons/numbers/complex/package-summary.html">complex
API</a>).</p>
<p>The <code>Complex</code> class is a Cartesian representation of a complex
number. The complex number is expressed in the form \( a + ib \) where \( a \)
and \( b \) are real numbers and \( i \) is the imaginary unit which satisfies
the equation \( i^2 = -1 \). For the complex number \( a + ib \), \( a \) is
called the <i>real part</i> and \( b \) is called the <i>imaginary part</i>.
Arithmetic in this class conforms to the C99 standard for complex numbers
defined in <a class="externalLink"
href="https://www.open-std.org/JTC1/SC22/WG14/www/standards";>ISO/IEC 9899</a>,
Annex G.</p>
<p>The <code>Complex</code> class is immutable. Instances are constructed with
factory methods:</p>
-<pre><code>double x = 3;
+<pre class="prettyprint"><code>double x = 3;
double y = 4;
Complex c1 = Complex.ofCartesian(x, y);
// c1 == x + iy
@@ -403,7 +403,7 @@ double rho = 1.23;
double theta = Math.PI / 2;
Complex c2 = Complex.ofPolar(rho, theta);</code></pre>
<p>Arithmetic operations, elementary functions and trigonometric functions are
provided that return new instances of <code>Complex</code> or primitive data
types:</p>
-<pre><code>Complex c1 = Complex.ofCartesian(3, 4);
+<pre class="prettyprint"><code>Complex c1 = Complex.ofCartesian(3, 4);
Complex c2 = Complex.ofCartesian(5, 6);
Complex c3 = c1.multiply(c2).sqrt();
@@ -416,7 +416,7 @@ boolean finite = c3.isFinite();</code></
<p>The interfaces <code>Addition</code> and <code>Multiplication</code>
provide generic typed definitions of the arithmetic <i>add</i> and
<i>multiply</i> operations. These are extended by <code>NativeOperators</code>
that adds operators that can be implemented in a more performant way. These
interfaces are used by the <a href="#Field">Field</a> module.</p>
<p>The <code>ArithmeticUtils</code> class provides arithmetic utilities such
as integer power, unsigned divide and remainder functions; greatest common
divisor; and least common multiple. These functions are used by the <a
href="#Fraction">Fraction</a> module.</p>
<p>The <code>Norm</code> class provides implementations of <a
class="externalLink"
href="https://en.wikipedia.org/wiki/Norm_(mathematics)">norm</a> functions. The
implementations may use extended precision methods to increase the overall
accuracy of the result at the cost of a moderate increase in the number of
computations. The Euclidean implementation handles possible under and overflow
of intermediates using scaling.</p>
-<pre><code>double x = Norm.EUCLIDEAN.of(3, -4);
// 5
+<pre class="prettyprint"><code>double x = Norm.EUCLIDEAN.of(3, -4);
// 5
double y = Norm.MANHATTAN.of(3, -4, 5); // 12
double z = Norm.MAXIMUM.of(new double[]{3, -4, 5, -6, -7, -8}); // 8
@@ -424,7 +424,7 @@ double big = Double.MAX_VALUE * 0.5;
double length = Norm.EUCLIDEAN.of(big, big, big);
// length == Math.sqrt(0.5 * 0.5 * 3) * Double.MAX_VALUE</code></pre>
<p>The <code>Sum</code> class provides accurate floating-point sums and linear
combinations. The class uses techniques to mitigate round off errors resulting
from standard floating-point operations, increasing the overall accuracy of
results at the cost of a moderate increase in the number of computations. The
<code>Sum</code> can add numbers and products of numbers. The result is
returned as the high-precision value if it is finite, or the standard IEEE754
result otherwise.</p>
-<pre><code>double sum1 = Sum.create().add(1)
+<pre class="prettyprint"><code>double sum1 = Sum.create().add(1)
.addProduct(3, 4)
.getAsDouble();
double sum2 = Sum.of(1).addProduct(3, 4)
@@ -437,13 +437,13 @@ double sum3 = Sum.ofProducts(new double[
Sum.of(1, 2, Double.NaN).getAsDouble() // NaN
Sum.of(1, 2, Double.NEGATIVE_INFINITY).getAsDouble() // -inf</code></pre>
<p>The implementation provides up to a 106 bit floating point significand.
However the significand is split into two <code>double</code> values which may
be separated by more than <code>2^53</code> by using the exponent of the second
<code>double</code>. This provides protection against cancellation in
situations that would not be handled by an IEEE754 binary 128 format with a 113
bit significand:</p>
-<pre><code>double x1 = 1e100 + 1 - 2 - 1e100;
+<pre class="prettyprint"><code>double x1 = 1e100 + 1 - 2 - 1e100;
double x2 = Sum.of(1e100, 1, -2, -1e100).getAsDouble();
// x1 == 0.0
// x2 == -1.0</code></pre>
<p>Note that the first part of the sum is maintained as the IEEE754 result.
The <code>Sum</code> is therefore not a full <code>double-double</code>
implementation, which would maintain the sum as the current total and a
round-off term. This difference makes the <code>Sum</code> class faster at the
cost of some accuracy during addition of terms that cancel.</p>
<p>If the terms to be subtracted are known then the summation can be split
into the positive and negative terms, summed in two parts and the result
computed by a final subtraction of the <code>Sum</code> of negative parts.</p>
-<pre><code>double x1 = 1e100 + 1 - 2 - 1e100;
+<pre class="prettyprint"><code>double x1 = 1e100 + 1 - 2 - 1e100;
Sum s1 = Sum.of(1e100, 1);
Sum s2 = Sum.of(2, 1e100);
double x2 = s1.subtract(s2).getAsDouble();
@@ -459,7 +459,7 @@ double x2 = s1.subtract(s2).getAsDouble(
<p>\( \frac{|a - b|}{\operatorname{max}(|a|, |b|)} \le \epsilon \)</p>
<p>Comparisons using the ULP argument specifies the allowed distance
<i>between</i> two numbers. Numbers are equal if they have <code>(ulp -
1)</code> representable numbers or fewer <i>between</i> <code>a</code> and
<code>b</code>. Use <code>ulp = 0</code> for binary equality.</p>
<p>Note: The default implementation for equality allows no numbers
<i>between</i> <code>a</code> and <code>b</code>. It is equivalent to
<code>Precision.equals(a, b, 1)</code>. Thus using a floating-point delta of
<code>0.0</code> may indicate numbers are equal when they are not <i>binary</i>
equal (see example below).</p>
-<pre><code>// Default allows no numbers between
+<pre class="prettyprint"><code>// Default allows no numbers between
Precision.equals(1000.0, 1000.0) // true
Precision.equals(1000.0, 1000.0 + Math.ulp(1000.0)) // true
Precision.equals(1000.0, 1000.0 + 2 * Math.ulp(1000.0)) // false
@@ -480,7 +480,7 @@ Precision.equals(1000.0, 1000.0 + 3 * Ma
Precision.equalsWithRelativeTolerance(1000.0, 1001.0, 1e-6) // false
Precision.equalsWithRelativeTolerance(1000.0, 1001.0, 1e-3) //
true</code></pre>
<p>Equality using <code>NaN</code> values will be <code>false</code>. To allow
two <code>NaN</code> values to be equal requires the use of the method
<code>equalsIncludingNaN</code>. Special handling of <code>NaN</code> values
allows the default implementation to be optimized for the typical use case
comparing finite numbers. Note that infinity values are equal.</p>
-<pre><code>Precision.equals(Double.NaN, 1000.0)
// false
+<pre class="prettyprint"><code>Precision.equals(Double.NaN, 1000.0)
// false
Precision.equals(Double.NaN, Double.NaN) // false
Precision.equalsIncludingNaN(Double.NaN, Double.NaN) // true
@@ -488,19 +488,19 @@ Precision.equals(Double.POSITIVE_INFINIT
Precision.equals(Double.NEGATIVE_INFINITY, Double.NEGATIVE_INFINITY) // true
Precision.equals(Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY) //
false</code></pre>
<p><code>Precision</code> provides a <code>compareTo</code> method to provide
ordering of numbers that are not considered equal using the tolerance:</p>
-<pre><code>Precision.compareTo(100, 100, 0.0) // 0
+<pre class="prettyprint"><code>Precision.compareTo(100, 100, 0.0) // 0
Precision.compareTo(100, 101, 1.0) // 0
Precision.compareTo(100, 102, 1.0) // -1
Precision.compareTo(102, 100, 1.0) // 1</code></pre>
<p>The comparison uses the natural ordering and is symmetric with regard to
<code>NaN</code> values. The comparison using <code><, ==, ></code> is
extended in the <code>DoubleEquivalence</code> interface that supports
<code><=, >=</code> and signum.</p>
-<pre><code>Precision.DoubleEquivalence eq =
Precision.doubleEquivalenceOfEpsilon(1.0);
+<pre class="prettyprint"><code>Precision.DoubleEquivalence eq =
Precision.doubleEquivalenceOfEpsilon(1.0);
eq.lt(100, 100) // false
eq.lte(100, 100) // true
eq.eq(100, 100) // true
eq.gte(100, 100) // true
eq.gt(100, 100) // false</code></pre>
<p><code>Precision</code> also provides methods for other floating-point
operations such as rounding and computing a representable delta from a number
and an ideal delta.</p>
-<pre><code>// Round to a number of digits to the right of the decimal point
+<pre class="prettyprint"><code>// Round to a number of digits to the right of
the decimal point
Precision.round(678.125, 4) // 678.125
Precision.round(678.125, 3) // 678.125
Precision.round(678.125, 2) // 678.13
@@ -512,13 +512,13 @@ Precision.round(678.125, -2)
Precision.representableDelta(1.0, 0.1) //
0.10000000000000009</code></pre></section><section><a
id="DD.3A_double-double"></a>
<h2>DD: double-double</h2>
<p>The <code>DD</code> class provides an extended precision floating-point
number. A double-double is an unevaluated sum of two IEEE <code>double</code>
precision numbers capable of representing at least 106 bits of significand. A
normalized double-double number \( (x, xx) \) satisfies the condition that the
parts are non-overlapping in magnitude such that:</p>
-<pre><code>|x| > |xx|
+<pre class="prettyprint"><code>|x| > |xx|
x == x + xx</code></pre>
<p>The implementation assumes a normalized representation during operations on
a <code>DD</code> number and computes results as a normalized representation.
The number is limited to the same exponent range as a <code>double</code>. Thus
the number can be considered as a standard IEEE <code>double</code> with
additional information that would be lost to rounding. This information can be
used in arithmetic operations so that compound calculation can reduce the error
present in the final result returned as a <code>double</code>.</p>
<p>The number \( (x, xx) \) may also be referred to using the labels
<i>high</i> and <i>low</i> to indicate the magnitude of the parts as \( (
x_{hi}, x_{lo} ) \), or using a numerical suffix for the parts as \( ( x_0, x_1
) \). The numerical suffix is typically used when the extended floating-point
number has an arbitrary number of parts, for example a quad-double is \( ( x_0,
x_1, x_2, x_3 ) \). The parts of the <code>DD</code> can be accessed using the
<code>hi()</code> and <code>lo()</code> methods and the evaluated sum \( x + xx
\) as <code>doubleValue()</code>.</p>
<p>The <code>DD</code> class is immutable. Instances are constructed with
factory methods. Methods to create a <code>DD</code> that are exact use the
prefix <code>of</code>. Methods that create the closest possible representation
use the prefix <code>from</code>. These methods may suffer a possible loss of
precision during conversion.</p>
<p>A <code>DD</code> can be constructed from a <code>double</code>,
<code>int</code> or <code>long</code> primitive. In the case of a
<code>long</code> this maintains the full 64-bits of information; this is not
possible when using implicit type conversion to a <code>double</code>. These
conversions can be reversed as the <code>DD</code> provides type conversions
using the <code>java.lang.Number</code> methods.</p>
-<pre><code>double x = Math.PI;
+<pre class="prettyprint"><code>double x = Math.PI;
int y = 42;
long z = -8564728970587006436L;
DD.of(x).doubleValue() // = x
@@ -526,12 +526,12 @@ DD.of(y).intValue() // = y
DD.of(z).longValue() // = z
// (long) (double) z != z</code></pre>
<p>A <code>DD</code> can be constructed from an <b>unsigned</b>
<code>int</code> or <code>long</code> primitive. These conversions use the low
order 31 or 63 bits of the number and the sign bit is used to represent 2 to
the power of 31 or 63 respectively. The operations are <i>not</i> the same as
using the <i>absolute</i> value of the primitive. Note that these operations
cannot be reversed to the original <b>signed</b> primitive.</p>
-<pre><code>int x = -42;
+<pre class="prettyprint"><code>int x = -42;
long y = -8564728970587006436L;
DD.ofUnsigned(x).longValue() // = Integer.toUnsignedLong(x)
DD.ofUnsigned(y).doubleValue() // = (double) (y & Long.MAX_VALUE) +
Math.pow(2, 63)</code></pre>
<p>The <code>DD</code> class can be created as the result of a
<code>double</code> operation and the round-off error. In the case of addition
and multiplication the result is exact. For division the result will have the
closest 106-bit representation to the exact result. Note that use of the
factory constructors for <code>double</code> arithmetic is preferred over
constructing the arguments as a <code>DD</code> from a <code>double</code> and
performing the equivalent operation in <code>DD</code> arithmetic:</p>
-<pre><code>double a = 1.2345678901234567;
+<pre class="prettyprint"><code>double a = 1.2345678901234567;
double b = 123.45678901234567;
DD w = DD.ofProduct(a, b); // (152.41578753238835,-1.0325951435749745E-14)
DD x = DD.ofSum(a, b); // (124.69135690246912,-1.1102230246251565E-15)
@@ -546,7 +546,7 @@ DD z = DD.fromQuotient(1, 3); // (0.333
DD zz = DD.of(1).divide(DD.of(3));
z.equals(zz) // true</code></pre>
<p>The <code>DD</code> can also be converted from and to a
<code>BigDecimal</code>. The conversion <b>from</b> may lose precision. The
conversion <b>to</b> is exact but only supported for finite numbers as
BigDecimal does not support infinity and NaN. The method
<code>isFinite()</code> can be used to verify that the evaluated sum \( x + xx
\) is finite; this is only true when both parts are finite and conversion to
<code>BigDecimal</code> is possible. Note that <code>BigDecimal</code> can be
used for numerical equality and ranking operations as the <code>DD</code> class
does not support <code>java.lang.Comparable</code>, and the
<code>equals(Object)</code> method is true for numerical equality of the
<i>parts</i>, not numerical equality of their <i>evaluated sum</i>. The
following demonstrates a round trip of \( \pi \) to 50 decimal places. The
<code>DD</code> is limited to approximately 34 decimal places and this is split
into the <code>double</code> value for \( \pi \) and a <code
>double</code> representing the rounding error.</p>
-<pre><code>BigDecimal pi = new
BigDecimal("3.14159265358979323846264338327950288419716939937510");
+<pre class="prettyprint"><code>BigDecimal pi = new
BigDecimal("3.14159265358979323846264338327950288419716939937510");
DD x = DD.from(pi); // (3.141592653589793,1.2246467991473532E-16)
pi.compareTo(x.bigDecimalValue()) // != 0
// x.hi() = Math.PI
@@ -557,18 +557,18 @@ nan.isFinite() // false
nan.bigDecimalValue() // throws NumberFormatException</code></pre>
<p>Note: It is not possible to directly specify the two parts of the
<code>DD</code> number. The two parts must be added using a sum to ensure the
<code>DD</code> maintains a normalized representation. If the two parts already
represent a number \( (x, xx) \) such that \( x == x + xx \) then the
magnitudes of the parts will be unchanged; any signed zeros may be subject to a
sign change.</p>
<p>The <code>DD</code> class provides the arithmetic operations add, subtract,
multiply, and divide for a <code>double</code> or <code>DD</code> argument.
<code>int</code> and <code>long</code> arguments can be used as a
<code>double</code> due to implicit type conversion. However if the
<code>long</code> value has more than 53-bits of precision then it should first
be converted to a <code>DD</code>.</p>
-<pre><code>long x = -8564728970587006436L;
+<pre class="prettyprint"><code>long x = -8564728970587006436L;
DD.ONE.add(x).longValue() // != x + 1
DD.ONE.add(DD.of(x)).longValue() // == x + 1</code></pre>
<p>The arithmetic methods are not intended to provide an exactly rounded
result to 106-bit precision. A compromise has been made between accuracy and
performance so that the <code>DD</code> class is a viable alternative to using
<code>BigDecimal</code> for high accuracy arithmetic when the ultimate result
is required as a <code>double</code>. The approximate error bounds of
operations are supplied in the class javadoc. Typical errors bounds are within
a relative error of 1-4 <i>eps</i> of the exact result where <i>eps</i> is \(
2^{-106} \).</p>
<p>The following demonstrates a simple sum where the <code>double</code>
representation of a fraction is inexact and results in a rounding error. This
is removed by extending the fraction to a double-double representation:</p>
-<pre><code>1.0 / 2 + 1.0 / 3 + 1.0 / 6 // = 0.9999999999999999
+<pre class="prettyprint"><code>1.0 / 2 + 1.0 / 3 + 1.0 / 6 // =
0.9999999999999999
DD z = DD.fromQuotient(1, 2)
.add(DD.fromQuotient(1, 3))
.add(DD.fromQuotient(1, 6)); // (1.0,-4.622231866529366E-33)
z.doubleValue() // = 1.0</code></pre>
<p>Note that the error on the final result is influenced by the calculation.
For summation of terms of the same sign a very large number of operations would
be required to observe a 1 ULP error in the final <code>double</code> result.
If terms of the opposite sign are summed then smaller magnitude intermediate
terms can be lost due to the limited 106-bit precision. In this case almost
total cancellation will produce the incorrect result.</p>
-<pre><code>double a = 1;
+<pre class="prettyprint"><code>double a = 1;
double b = Math.pow(2, 53);
double c = Math.pow(2, 106);
DD.of(a).add(b).add(c).subtract(c).subtract(b) // (0, 0)
@@ -581,7 +581,7 @@ DD.of(a).add(b).add(c).subtract(c).subtr
<p>Operations that involve splitting a double (multiply, divide) are safe when
the base 2 exponent is below 996. This puts an upper limit of approximately
+/-6.7e299 on any values to be split; in practice the arguments to multiply and
divide operations are further constrained by the expected finite value of the
product or quotient.</p>
<p>Likewise the smallest value that can be represented is \( 2^{-1074} \). The
full 106-bit accuracy will be lost when intermediates are within \( 2^{53} \)
of the minimum normalized <code>double</code> \( 2^{-1022} \).</p>
<p>The <code>DD</code> result can be verified by checking it is a finite
evaluated sum using <code>isFinite()</code>. Computations expecting to approach
over or underflow must use scaling of intermediate terms using
<code>frexp(int[])</code> and <code>scalb(int)</code> and appropriate
management of the current base 2 scale. The <code>frexp(int[])</code> method
creates a number with a fractional part \( f \) in the range \( [0.5, 1) \) and
an exponent part \( 2^b \) such that \( x = f \times 2^b \). The following
example demonstrates scaling and rescaling:</p>
-<pre><code>double a = 1.5 * Math.pow(2, 1023);
+<pre class="prettyprint"><code>double a = 1.5 * Math.pow(2, 1023);
double b = 4 * Math.pow(2, -1022);
DD x = DD.of(a);
DD y = DD.of(b);
@@ -602,10 +602,10 @@ z.scalb(xb[0] + yb[0]).doubleValue() //
<h3>Comparison to Math.fma</h3>
<p>The fused multiply-add method <code>Math.fma(double, double, double)</code>
added in Java 9 returns the exact product of the first two arguments summed
with the third argument and then rounded once to the nearest
<code>double</code>. This avoids the two rounding operations that would occur
using <code>a * b + c</code> as a regular floating-point expression. The result
is returned as a <code>double</code>.</p>
<p>The <code>DD</code> class can represent the exact 106-bit product <code>a *
b</code> as \( (x, xx) \). Unlike <code>Math.fma</code>, which uses effectively
unlimited precision arithmetic, the addend <code>c</code> can only be used if
it overlaps either the upper part \( x \) or the lower part \( xx \) of the
number. If too small then it will not change \(x, xx \); if too large then the
final result will be \( (c, x) \). However the result will be returned with
information that can be used in further computation. Also note that
<code>Math.fma</code> will compute the correct IEEE result if the value is
non-finite. It will also be protected from over and underflow for the
intermediate result, for example:</p>
-<pre><code>Math.fma(Double.MAX_VALUE, 2.0, -Double.MAX_VALUE) // =
Double.MAX_VALUE
+<pre class="prettyprint"><code>Math.fma(Double.MAX_VALUE, 2.0,
-Double.MAX_VALUE) // = Double.MAX_VALUE
Math.fma(Double.MIN_VALUE, 0.5, Double.MIN_VALUE) // = Double.MIN_VALUE *
1.5</code></pre>
<p>The round-off from a standard floating-point expression <code>x * y</code>
can be computed using FMA:</p>
-<pre><code>double x = ...
+<pre class="prettyprint"><code>double x = ...
double y = ...
DD z = DD.ofProduct(x, y);
z.hi() // = x * y;
@@ -618,7 +618,7 @@ z.lo() // = Math.fma(x, y, -x * y)</cod
<h1>Field</h1>
<p>The <a href="../commons-numbers-field/index.html">commons-numbers-field</a>
module provides utilities related to the concept of field (<a
href="../commons-numbers-field/apidocs/org/apache/commons/numbers/field/package-summary.html">field
API</a>).</p>
<p>A field is any set of elements that satisfies the field axioms for both
addition and multiplication and is a commutative division algebra. The
<code>Field</code> interface defines the operations of a field. Implementations
are provided for rational numbers as <code>FractionField</code> and
<code>BigFractionField</code>; and real numbers as <code>FP64Field</code>.</p>
-<pre><code>Field<FP64> field = FP64Field.get();
+<pre class="prettyprint"><code>Field<FP64> field = FP64Field.get();
FP64 result = field.one().multiply(3).divide(field.one().multiply(4));
double value = result.doubleValue();
// value = 0.75</code></pre>
@@ -628,12 +628,12 @@ double value = result.doubleValue();
<h2>Rational Numbers</h2>
<p>The <code>Fraction</code> class is a representation of a rational number
<code>p / q</code> using <code>int</code> values for the numerator
<code>p</code> and denominator <code>q</code>.</p>
<p>Instances are constructed with factory methods:</p>
-<pre><code>int p = 3;
+<pre class="prettyprint"><code>int p = 3;
int q = 4;
Fraction f = Fraction.of(p, q);
// f == 3 / 4</code></pre>
<p><code>Fraction</code> can be created using a <code>double</code>. The
floating-point number may not be exactly representable; a continued fraction is
used to converge on a rational representation within a specified absolute
tolerance, or a maximum denominator. An <code>ArithmeticException</code> is
thrown if the algorithm fails to converge or the number is not
representable.</p>
-<pre><code>int maxIterations = 100;
+<pre class="prettyprint"><code>int maxIterations = 100;
// tolerance
Fraction a = Fraction.from(0.6152, 0.02, maxIterations);
Fraction b = Fraction.from(0.6152, 1.0e-7, maxIterations);
@@ -652,7 +652,7 @@ Fraction e = Fraction.from(Math.pow(2, 3
// *** Throws an ArithmeticException ***
Fraction.from(Math.pow(2, 32));</code></pre>
<p>The fraction is represented in reduced form using the greatest common
divisor. For example <code>240 / 256</code> is reduced to <code>15 / 16</code>.
The sign can be either in the numerator or the denominator; the sign of the
fraction is accessed using the <code>signum()</code> method. Fraction equality
can be evaluated using <code>equals()</code>. The class implements
<code>Comparable<Fraction></code> to allow sorting using the natural
order imposed by the fraction's sign and magnitude.</p>
-<pre><code>Fraction f1 = Fraction.of(-240, 256);
+<pre class="prettyprint"><code>Fraction f1 = Fraction.of(-240, 256);
Fraction f2 = Fraction.of(15, -16);
f1.signum() == -1
@@ -662,12 +662,12 @@ f1.compareTo(Fraction.ZERO) == -1
Fraction.of(Integer.MIN_VALUE, Integer.MIN_VALUE).compareTo(Fraction.ONE) ==
0</code></pre>
<p>Arithmetic operations are provided that return new instances of
<code>Fraction</code>. Note that fraction operations are <i>exact</i>.</p>
-<pre><code>Fraction result = Fraction.of(1, 2).add(Fraction.of(1, 3))
+<pre class="prettyprint"><code>Fraction result = Fraction.of(1,
2).add(Fraction.of(1, 3))
.add(Fraction.of(1, 6));
// result == 1 / 1
// Note: 1.0 / 2 + 1.0 / 3 + 1.0 / 6 == 0.9999999999999999
(inexact)</code></pre>
<p><code>Fraction</code> extends <code>java.lang.Number</code> and can be
converted to other primitive numbers with possible loss of precision:</p>
-<pre><code>double a = Fraction.of(1, 8).doubleValue();
+<pre class="prettyprint"><code>double a = Fraction.of(1, 8).doubleValue();
double b = Fraction.of(1, 3).doubleValue();
int c = Fraction.of(8, 3).intValue();
// a == 0.125 (exact)
@@ -677,10 +677,10 @@ int c = Fraction.of(8, 3).intValue();
<p>The <code>BigFraction</code> class uses <code>BigInteger</code> for the
numerator and denominator and can provide exact arithmetic up to the
limitations of <code>BigInteger</code>. This is documented as at least
<code>+/- 2^Integer.MAX_VALUE</code> (exclusive) and may support values outside
of that range.</p>
<p>The <code>BigFraction</code> class provides all the arithmetic operations
of <code>Fraction</code> and can be used when <code>Fraction</code> cannot
represent the rational numbers; there will be a performance cost to using
<code>BigFraction</code> due to the switch from primitive values to
<code>BigInteger</code> for computations.</p>
<p><code>BigFraction</code> can be constructed from <code>int</code>,
<code>long</code> or <code>BigInteger</code> numerator and denominators.</p>
-<pre><code>BigFraction a = BigFraction.of(1, 3);
+<pre class="prettyprint"><code>BigFraction a = BigFraction.of(1, 3);
// a == 1 / 3</code></pre>
<p>The <code>BigFraction</code> conversion of <code>double</code> values can
be exact, or adjusted to be within a provided tolerance. Note that exact
conversion may create an unexpected rational number as it is limited by the
precision of the input <code>double</code> value which may be inexact:</p>
-<pre><code>BigFraction a = BigFraction.from(1.0 / 3);
+<pre class="prettyprint"><code>BigFraction a = BigFraction.from(1.0 / 3);
// a == 6004799503160661 / 18014398509481984
// max denominator
@@ -693,7 +693,7 @@ BigFraction b = BigFraction.from(1.0 / 3
<p>The <code>ContinuedFraction</code> class requires a function to supply the
<i>n</i>th coefficients; the API allows the fraction function to be evaluated
for different arguments. This is useful when the coefficients can be computed
using a formula based on the index and the argument. The class is abstract and
must be extended to provide the coefficients \( a \) and \( b \). For example
the following fraction:</p>
<p>\( \tan(z) = \cfrac{z}{1 - \cfrac{z^2}{3 - \cfrac{z^2}{5 - \ddots\,}}}
\)</p>
<p>Can be computed using:</p>
-<pre><code>ContinuedFraction cf = new ContinuedFraction() {
+<pre class="prettyprint"><code>ContinuedFraction cf = new ContinuedFraction() {
@Override
public double getA(int n, double x) {
return n < 2 ? x : -x * x;
@@ -713,13 +713,13 @@ double result = cf.evaluate(z, eps);
<p>For example the golden ratio:</p>
<p>\( x = 1 + \cfrac{1}{1 + \cfrac{1}{1 + \cfrac{1}{1 + \ddots\,}}} \)</p>
<p>Can be computed as:</p>
-<pre><code>double eps = 1e-10;
+<pre class="prettyprint"><code>double eps = 1e-10;
double gr1 = GeneralizedContinuedFraction.value(() -> Coefficient.of(1, 1),
eps);
double gr2 = GeneralizedContinuedFraction.value(1, () -> Coefficient.of(1,
1), eps);
// gr1 ~ gr2 ~ 1.6180339887498948...</code></pre>
<p>Whether to separate the term \( b_0 \) depends on the fraction and the
algorithm convergence. See the <a
href="../commons-numbers-fraction/apidocs/org/apache/commons/numbers/fraction/GeneralizedContinuedFraction.html">GeneralizedContinuedFraction</a>
documentation for details. Note that it is also possible to evaluate part of
the fraction using only later terms and then computing the final result by
including the early terms.</p>
<p>An example using a recursive generator for the evaluation of \( \tan(z) \)
is computed using:</p>
-<pre><code>static class Tan implements Supplier<Coefficient> {
+<pre class="prettyprint"><code>static class Tan implements
Supplier<Coefficient> {
private double a;
private double b = -1;
@@ -759,7 +759,7 @@ double tan2 = c.getA() / GeneralizedCont
<p>A simple continued fraction will have an \( a \) coefficient of 1. For
example the following fraction:</p>
<p>\( \frac{415}{93} = 4 + \cfrac{1}{2 + \cfrac{1}{6 + \cfrac{1}{7}}} \)</p>
<p>can be evaluated as a simple continued fraction using:</p>
-<pre><code>private static Supplier<Coefficient>
simpleContinuedFraction(double... coefficients) {
+<pre class="prettyprint"><code>private static Supplier<Coefficient>
simpleContinuedFraction(double... coefficients) {
return new Supplier<Coefficient>() {
/* iteration. */
private int n;
@@ -829,7 +829,7 @@ double result2 = GeneralizedContinuedFra
<td style="text-align: left;">Inverse error functions</td>
<td style="text-align: left;"></td></tr></table>
<p>Functions are provided using static class methods. These may be optionally
parameterized if the method uses an iterative computation to control the
function evaluation. For example:</p>
-<pre><code>double result = Erfc.value(1.23);
+<pre class="prettyprint"><code>double result = Erfc.value(1.23);
// Default function evaluation
double a = 1.23;
@@ -845,7 +845,7 @@ double result2 = IncompleteGamma.Lower.v
<h1>Primes</h1>
<p>The <a
href="../commons-numbers-primes/index.html">commons-numbers-primes</a> module
provides utilities related to prime numbers (<a
href="../commons-numbers-primes/apidocs/org/apache/commons/numbers/primes/package-summary.html">primes
API</a>).</p>
<p>The <code>Primes</code> class provides static methods for working with
prime numbers in the range of an <code>int</code>. Methods are provided to
determine if a value is prime, compute the next prime after a value and the
prime factors of a number.</p>
-<pre><code>int n = 51237173;
+<pre class="prettyprint"><code>int n = 51237173;
boolean prime = Primes.isPrime(n);
int m = Primes.nextPrime(n);
// prime == false
@@ -860,7 +860,7 @@ List<Integer> f2 = Primes.primeFac
<p>The <a
href="../commons-numbers-quaternion/index.html">commons-numbers-quaternion</a>
module provides utilities for working with quarternion numbers (<a
href="../commons-numbers-quaternion/apidocs/org/apache/commons/numbers/quaternion/package-summary.html">quaternion
API</a>).</p>
<p>The <code>Quaternion</code> class represents Hamilton's hypecomplex number
in the form \( H = w + x\,i + y\,j + z\,k \), where \( w \) is the scalar
component and \( [x, y, z] \) is the vector component.</p>
<p>The class is immutable and instances are constructed with factory methods.
Getters are provided for access to the components:</p>
-<pre><code>double w = 2;
+<pre class="prettyprint"><code>double w = 2;
double x = 3;
double y = 4;
double z = 5;
@@ -871,25 +871,25 @@ h1.getScalarPart(); // w
h1.getVectorPart(); // [x, y, z]
// h1 == h2</code></pre>
<p>Methods are provided for arithmetic (add, subtract, multiply) and other
quaternion operations such as scaling, dot product, negation, conjugation and
normalization.</p>
-<pre><code>Quaternion h = Quaternion.of(1, 2, 3, 4);
+<pre class="prettyprint"><code>Quaternion h = Quaternion.of(1, 2, 3, 4);
Quaternion h1 = h.add(Quaternion.ONE); // [2, 2, 3, 4]
Quaternion hi = h.add(Quaternion.I); // [1, 3, 3, 4]
Quaternion hj = h.add(Quaternion.J); // [1, 2, 4, 4]
Quaternion hk = h.add(Quaternion.K); // [1, 2, 3, 5]</code></pre>
<p>The binary operations acting on two <code>Quaternion</code> instances are
provided as instance methods and static methods for convenience when using
method references as lambda functions:</p>
-<pre><code>Quaternion h1 = Quaternion.of(1, 2, 3, 4);
+<pre class="prettyprint"><code>Quaternion h1 = Quaternion.of(1, 2, 3, 4);
Quaternion h2 = Quaternion.of(5, 6, 7, 8);
Quaternion result1 = h1.multiply(h2);
Quaternion result2 = Quaternion.multiply(h1, h2);
// result1 == result2</code></pre>
<p>The class evaluates binary equality using <code>equals(Object)</code> and
provides a helper method to evaluate equality within an absolute tolerance:</p>
-<pre><code>Quaternion q1 = Quaternion.of(1, 2, 3, 4);
+<pre class="prettyprint"><code>Quaternion q1 = Quaternion.of(1, 2, 3, 4);
Quaternion q2 = Quaternion.of(1, 2, 3, 4 + 1e-10);
q1.equals(q2); // false
q1.equals(q2, 1e-9); // true</code></pre>
<p>Quaternions are used to apply rotations in 3-dimensional Euclidean space in
the <a class="externalLink"
href="https://commons.apache.org/proper/commons-geometry/";>commons-geometry</a>
project.</p>
<p>The <code>Slerp</code> class performs spherical linear interpolation (<a
class="externalLink" href="https://en.wikipedia.org/wiki/Slerp";>Slerp</a>). The
algorithm is designed to interpolate smoothly between two
rotations/orientations, producing a constant-speed motion along an arc.</p>
-<pre><code>static Quaternion createZRotation(final double theta) {
+<pre class="prettyprint"><code>static Quaternion createZRotation(final double
theta) {
double halfAngle = theta * 0.5;
return Quaternion.of(Math.cos(halfAngle), 0, 0, Math.sin(halfAngle));
}
@@ -907,7 +907,7 @@ slerp.apply(1.0) // ~ q2</code></pre>
<h1>Root Finder</h1>
<p>The <a
href="../commons-numbers-rootfinder/index.html">commons-numbers-rootfinder</a>
module provides utilities for finding the zero of a function (<a
href="../commons-numbers-rootfinder/apidocs/org/apache/commons/numbers/rootfinder/package-summary.html">rootfinder
API</a>).</p>
<p>The <code>BrentSolver</code> class implements the Brent algorithm for
finding the zeros of real univariate functions. The solver requires an interval
that brackets a root and will raise an exception if there is no sign change
between the bounds \( [a, b] \). The relative \( \epsilon \) and absolute \(
\delta \) accuracy specify the convergence tolerance for the function value \(
x \) to zero as: \( 2\,\epsilon\,|x| + \delta \). The function accuracy is used
to return the initial bracket bounds, or initial guess, if the function value
is within the specified accuracy of zero.</p>
-<pre><code>double relAccuracy = 1e-6;
+<pre class="prettyprint"><code>double relAccuracy = 1e-6;
double absAccuracy = 1e-14;
double functionAccuracy = 1e-15;
BrentSolver solver = new BrentSolver(relAccuracy,
@@ -930,7 +930,7 @@ solver.findRoot(Math::sin, 2, 3);</code>
<p>Copyright © 2017-2026
<a href="https://www.apache.org/";>The Apache Software
Foundation</a>.
All Rights Reserved.</p>
-
+
<div class="center">Apache Commons, Apache Commons Numbers, Apache, the Apache
logo, and the Apache Commons project logos are trademarks of The Apache
Software Foundation.
All other marks mentioned may be trademarks or registered trademarks of
their respective owners.</div>
</div>
