summaryrefslogtreecommitdiff
path: root/src/org/unitConverter/math
diff options
context:
space:
mode:
Diffstat (limited to 'src/org/unitConverter/math')
-rw-r--r--src/org/unitConverter/math/ConditionalExistenceCollections.java295
-rw-r--r--src/org/unitConverter/math/DecimalComparison.java207
-rw-r--r--src/org/unitConverter/math/UncertainDouble.java419
3 files changed, 738 insertions, 183 deletions
diff --git a/src/org/unitConverter/math/ConditionalExistenceCollections.java b/src/org/unitConverter/math/ConditionalExistenceCollections.java
index 9522885..ac1c0cf 100644
--- a/src/org/unitConverter/math/ConditionalExistenceCollections.java
+++ b/src/org/unitConverter/math/ConditionalExistenceCollections.java
@@ -30,20 +30,25 @@ import java.util.function.Predicate;
/**
* Elements in these wrapper collections only exist if they pass a condition.
* <p>
- * All of the collections in this class are "views" of the provided collections. They are mutable if the provided
- * collections are mutable, they allow null if the provided collections allow null, they will reflect changes in the
+ * All of the collections in this class are "views" of the provided collections.
+ * They are mutable if the provided collections are mutable, they allow null if
+ * the provided collections allow null, they will reflect changes in the
* provided collection, etc.
* <p>
- * The modification operations will always run the corresponding operations, even if the conditional existence
- * collection doesn't change. For example, if you have a set that ignores even numbers, add(2) will still add a 2 to the
+ * The modification operations will always run the corresponding operations,
+ * even if the conditional existence collection doesn't change. For example, if
+ * you have a set that ignores even numbers, add(2) will still add a 2 to the
* backing set (but the conditional existence set will say it doesn't exist).
* <p>
- * The returned collections do <i>not</i> pass the hashCode and equals operations through to the backing collections,
- * but rely on {@code Object}'s {@code equals} and {@code hashCode} methods. This is necessary to preserve the contracts
- * of these operations in the case that the backing collections are sets or lists.
+ * The returned collections do <i>not</i> pass the hashCode and equals
+ * operations through to the backing collections, but rely on {@code Object}'s
+ * {@code equals} and {@code hashCode} methods. This is necessary to preserve
+ * the contracts of these operations in the case that the backing collections
+ * are sets or lists.
* <p>
- * Other than that, <i>the only difference between the provided collections and the returned collections are that
- * elements don't exist if they don't pass the provided condition</i>.
+ * Other than that, <i>the only difference between the provided collections and
+ * the returned collections are that elements don't exist if they don't pass the
+ * provided condition</i>.
*
*
* @author Adrien Hopkins
@@ -56,13 +61,13 @@ public final class ConditionalExistenceCollections {
*
* @author Adrien Hopkins
* @since 2019-10-17
- * @param <E>
- * type of element in collection
+ * @param <E> type of element in collection
*/
- static final class ConditionalExistenceCollection<E> extends AbstractCollection<E> {
+ static final class ConditionalExistenceCollection<E>
+ extends AbstractCollection<E> {
final Collection<E> collection;
final Predicate<E> existenceCondition;
-
+
/**
* Creates the {@code ConditionalExistenceCollection}.
*
@@ -70,67 +75,89 @@ public final class ConditionalExistenceCollections {
* @param existenceCondition
* @since 2019-10-17
*/
- private ConditionalExistenceCollection(final Collection<E> collection, final Predicate<E> existenceCondition) {
+ private ConditionalExistenceCollection(final Collection<E> collection,
+ final Predicate<E> existenceCondition) {
this.collection = collection;
this.existenceCondition = existenceCondition;
}
-
+
@Override
public boolean add(final E e) {
return this.collection.add(e) && this.existenceCondition.test(e);
}
-
+
@Override
public void clear() {
this.collection.clear();
}
-
+
@Override
public boolean contains(final Object o) {
if (!this.collection.contains(o))
return false;
-
+
// this collection can only contain instances of E
- // since the object is in the collection, we know that it must be an instance of E
+ // since the object is in the collection, we know that it must be an
+ // instance of E
// therefore this cast will always work
@SuppressWarnings("unchecked")
final E e = (E) o;
-
+
return this.existenceCondition.test(e);
}
-
+
@Override
public Iterator<E> iterator() {
- return conditionalExistenceIterator(this.collection.iterator(), this.existenceCondition);
+ return conditionalExistenceIterator(this.collection.iterator(),
+ this.existenceCondition);
}
-
+
@Override
public boolean remove(final Object o) {
- // remove() must be first in the && statement, otherwise it may not execute
+ // remove() must be first in the && statement, otherwise it may not
+ // execute
final boolean containedObject = this.contains(o);
return this.collection.remove(o) && containedObject;
}
-
+
@Override
public int size() {
- return (int) this.collection.stream().filter(this.existenceCondition).count();
+ return (int) this.collection.stream().filter(this.existenceCondition)
+ .count();
+ }
+
+ @Override
+ public Object[] toArray() {
+ // ensure the toArray operation is supported
+ this.collection.toArray();
+
+ // if it works, do it for real
+ return super.toArray();
+ }
+
+ @Override
+ public <T> T[] toArray(T[] a) {
+ // ensure the toArray operation is supported
+ this.collection.toArray();
+
+ // if it works, do it for real
+ return super.toArray(a);
}
}
-
+
/**
* Elements in this wrapper iterator only exist if they pass a condition.
*
* @author Adrien Hopkins
* @since 2019-10-17
- * @param <E>
- * type of elements in iterator
+ * @param <E> type of elements in iterator
*/
static final class ConditionalExistenceIterator<E> implements Iterator<E> {
final Iterator<E> iterator;
final Predicate<E> existenceCondition;
E nextElement;
boolean hasNext;
-
+
/**
* Creates the {@code ConditionalExistenceIterator}.
*
@@ -138,12 +165,13 @@ public final class ConditionalExistenceCollections {
* @param condition
* @since 2019-10-17
*/
- private ConditionalExistenceIterator(final Iterator<E> iterator, final Predicate<E> condition) {
+ private ConditionalExistenceIterator(final Iterator<E> iterator,
+ final Predicate<E> condition) {
this.iterator = iterator;
this.existenceCondition = condition;
this.getAndSetNextElement();
}
-
+
/**
* Gets the next element, and sets nextElement and hasNext accordingly.
*
@@ -160,12 +188,12 @@ public final class ConditionalExistenceCollections {
} while (!this.existenceCondition.test(this.nextElement));
this.hasNext = true;
}
-
+
@Override
public boolean hasNext() {
return this.hasNext;
}
-
+
@Override
public E next() {
if (this.hasNext()) {
@@ -175,27 +203,25 @@ public final class ConditionalExistenceCollections {
} else
throw new NoSuchElementException();
}
-
+
@Override
public void remove() {
this.iterator.remove();
}
}
-
+
/**
* Mappings in this map only exist if the entry passes some condition.
*
* @author Adrien Hopkins
* @since 2019-10-17
- * @param <K>
- * key type
- * @param <V>
- * value type
+ * @param <K> key type
+ * @param <V> value type
*/
static final class ConditionalExistenceMap<K, V> extends AbstractMap<K, V> {
Map<K, V> map;
Predicate<Entry<K, V>> entryExistenceCondition;
-
+
/**
* Creates the {@code ConditionalExistenceMap}.
*
@@ -203,205 +229,240 @@ public final class ConditionalExistenceCollections {
* @param entryExistenceCondition
* @since 2019-10-17
*/
- private ConditionalExistenceMap(final Map<K, V> map, final Predicate<Entry<K, V>> entryExistenceCondition) {
+ private ConditionalExistenceMap(final Map<K, V> map,
+ final Predicate<Entry<K, V>> entryExistenceCondition) {
this.map = map;
this.entryExistenceCondition = entryExistenceCondition;
}
-
+
@Override
public boolean containsKey(final Object key) {
if (!this.map.containsKey(key))
return false;
-
+
// only instances of K have mappings in the backing map
// since we know that key is a valid key, it must be an instance of K
@SuppressWarnings("unchecked")
final K keyAsK = (K) key;
-
+
// get and test entry
final V value = this.map.get(key);
final Entry<K, V> entry = new SimpleEntry<>(keyAsK, value);
return this.entryExistenceCondition.test(entry);
}
-
+
@Override
public Set<Entry<K, V>> entrySet() {
- return conditionalExistenceSet(this.map.entrySet(), this.entryExistenceCondition);
+ return conditionalExistenceSet(this.map.entrySet(),
+ this.entryExistenceCondition);
}
-
+
@Override
public V get(final Object key) {
return this.containsKey(key) ? this.map.get(key) : null;
}
-
+
+ private final Entry<K, V> getEntry(K key) {
+ return new Entry<K, V>() {
+ @Override
+ public K getKey() {
+ return key;
+ }
+
+ @Override
+ public V getValue() {
+ return ConditionalExistenceMap.this.map.get(key);
+ }
+
+ @Override
+ public V setValue(V value) {
+ return ConditionalExistenceMap.this.map.put(key, value);
+ }
+ };
+ }
+
@Override
public Set<K> keySet() {
- // maybe change this to use ConditionalExistenceSet
- return super.keySet();
+ return conditionalExistenceSet(super.keySet(),
+ k -> this.entryExistenceCondition.test(this.getEntry(k)));
}
-
+
@Override
public V put(final K key, final V value) {
final V oldValue = this.map.put(key, value);
-
+
// get and test entry
final Entry<K, V> entry = new SimpleEntry<>(key, oldValue);
return this.entryExistenceCondition.test(entry) ? oldValue : null;
}
-
+
@Override
public V remove(final Object key) {
final V oldValue = this.map.remove(key);
return this.containsKey(key) ? oldValue : null;
}
-
+
@Override
public Collection<V> values() {
// maybe change this to use ConditionalExistenceCollection
return super.values();
}
-
}
-
+
/**
* Elements in this set only exist if a certain condition is true.
*
* @author Adrien Hopkins
* @since 2019-10-17
- * @param <E>
- * type of element in set
+ * @param <E> type of element in set
*/
static final class ConditionalExistenceSet<E> extends AbstractSet<E> {
private final Set<E> set;
private final Predicate<E> existenceCondition;
-
+
/**
* Creates the {@code ConditionalNonexistenceSet}.
*
- * @param set
- * set to use
- * @param existenceCondition
- * condition where element exists
+ * @param set set to use
+ * @param existenceCondition condition where element exists
* @since 2019-10-17
*/
- private ConditionalExistenceSet(final Set<E> set, final Predicate<E> existenceCondition) {
+ private ConditionalExistenceSet(final Set<E> set,
+ final Predicate<E> existenceCondition) {
this.set = set;
this.existenceCondition = existenceCondition;
}
-
+
/**
* {@inheritDoc}
* <p>
- * Note that this method returns {@code false} if {@code e} does not pass the existence condition.
+ * Note that this method returns {@code false} if {@code e} does not pass
+ * the existence condition.
*/
@Override
public boolean add(final E e) {
return this.set.add(e) && this.existenceCondition.test(e);
}
-
+
@Override
public void clear() {
this.set.clear();
}
-
+
@Override
public boolean contains(final Object o) {
if (!this.set.contains(o))
return false;
-
+
// this set can only contain instances of E
- // since the object is in the set, we know that it must be an instance of E
+ // since the object is in the set, we know that it must be an instance
+ // of E
// therefore this cast will always work
@SuppressWarnings("unchecked")
final E e = (E) o;
-
+
return this.existenceCondition.test(e);
}
-
+
@Override
public Iterator<E> iterator() {
- return conditionalExistenceIterator(this.set.iterator(), this.existenceCondition);
+ return conditionalExistenceIterator(this.set.iterator(),
+ this.existenceCondition);
}
-
+
@Override
public boolean remove(final Object o) {
- // remove() must be first in the && statement, otherwise it may not execute
+ // remove() must be first in the && statement, otherwise it may not
+ // execute
final boolean containedObject = this.contains(o);
return this.set.remove(o) && containedObject;
}
-
+
@Override
public int size() {
return (int) this.set.stream().filter(this.existenceCondition).count();
}
+
+ @Override
+ public Object[] toArray() {
+ // ensure the toArray operation is supported
+ this.set.toArray();
+
+ // if it works, do it for real
+ return super.toArray();
+ }
+
+ @Override
+ public <T> T[] toArray(T[] a) {
+ // ensure the toArray operation is supported
+ this.set.toArray();
+
+ // if it works, do it for real
+ return super.toArray(a);
+ }
}
-
+
/**
- * Elements in the returned wrapper collection are ignored if they don't pass a condition.
+ * Elements in the returned wrapper collection are ignored if they don't pass
+ * a condition.
*
- * @param <E>
- * type of elements in collection
- * @param collection
- * collection to wrap
- * @param existenceCondition
- * elements only exist if this returns true
+ * @param <E> type of elements in collection
+ * @param collection collection to wrap
+ * @param existenceCondition elements only exist if this returns true
* @return wrapper collection
* @since 2019-10-17
*/
- public static final <E> Collection<E> conditionalExistenceCollection(final Collection<E> collection,
+ public static final <E> Collection<E> conditionalExistenceCollection(
+ final Collection<E> collection,
final Predicate<E> existenceCondition) {
- return new ConditionalExistenceCollection<>(collection, existenceCondition);
+ return new ConditionalExistenceCollection<>(collection,
+ existenceCondition);
}
-
+
/**
- * Elements in the returned wrapper iterator are ignored if they don't pass a condition.
+ * Elements in the returned wrapper iterator are ignored if they don't pass a
+ * condition.
*
- * @param <E>
- * type of elements in iterator
- * @param iterator
- * iterator to wrap
- * @param existenceCondition
- * elements only exist if this returns true
+ * @param <E> type of elements in iterator
+ * @param iterator iterator to wrap
+ * @param existenceCondition elements only exist if this returns true
* @return wrapper iterator
* @since 2019-10-17
*/
- public static final <E> Iterator<E> conditionalExistenceIterator(final Iterator<E> iterator,
- final Predicate<E> existenceCondition) {
+ public static final <E> Iterator<E> conditionalExistenceIterator(
+ final Iterator<E> iterator, final Predicate<E> existenceCondition) {
return new ConditionalExistenceIterator<>(iterator, existenceCondition);
}
-
+
/**
- * Mappings in the returned wrapper map are ignored if the corresponding entry doesn't pass a condition
+ * Mappings in the returned wrapper map are ignored if the corresponding
+ * entry doesn't pass a condition
*
- * @param <K>
- * type of key in map
- * @param <V>
- * type of value in map
- * @param map
- * map to wrap
- * @param entryExistenceCondition
- * mappings only exist if this returns true
+ * @param <K> type of key in map
+ * @param <V> type of value in map
+ * @param map map to wrap
+ * @param entryExistenceCondition mappings only exist if this returns true
* @return wrapper map
* @since 2019-10-17
*/
- public static final <K, V> Map<K, V> conditionalExistenceMap(final Map<K, V> map,
+ public static final <K, V> Map<K, V> conditionalExistenceMap(
+ final Map<K, V> map,
final Predicate<Entry<K, V>> entryExistenceCondition) {
return new ConditionalExistenceMap<>(map, entryExistenceCondition);
}
-
+
/**
- * Elements in the returned wrapper set are ignored if they don't pass a condition.
+ * Elements in the returned wrapper set are ignored if they don't pass a
+ * condition.
*
- * @param <E>
- * type of elements in set
- * @param set
- * set to wrap
- * @param existenceCondition
- * elements only exist if this returns true
+ * @param <E> type of elements in set
+ * @param set set to wrap
+ * @param existenceCondition elements only exist if this returns true
* @return wrapper set
* @since 2019-10-17
*/
- public static final <E> Set<E> conditionalExistenceSet(final Set<E> set, final Predicate<E> existenceCondition) {
+ public static final <E> Set<E> conditionalExistenceSet(final Set<E> set,
+ final Predicate<E> existenceCondition) {
return new ConditionalExistenceSet<>(set, existenceCondition);
}
}
diff --git a/src/org/unitConverter/math/DecimalComparison.java b/src/org/unitConverter/math/DecimalComparison.java
index 859e8da..0f5b91e 100644
--- a/src/org/unitConverter/math/DecimalComparison.java
+++ b/src/org/unitConverter/math/DecimalComparison.java
@@ -27,42 +27,45 @@ import java.math.BigDecimal;
*/
public final class DecimalComparison {
/**
- * The value used for double comparison. If two double values are within this value multiplied by the larger value,
- * they are considered equal.
+ * The value used for double comparison. If two double values are within this
+ * value multiplied by the larger value, they are considered equal.
*
* @since 2019-03-18
* @since v0.2.0
*/
public static final double DOUBLE_EPSILON = 1.0e-15;
-
+
/**
- * The value used for float comparison. If two float values are within this value multiplied by the larger value,
- * they are considered equal.
+ * The value used for float comparison. If two float values are within this
+ * value multiplied by the larger value, they are considered equal.
*
* @since 2019-03-18
* @since v0.2.0
*/
public static final float FLOAT_EPSILON = 1.0e-6f;
-
+
/**
* Tests for equality of double values using {@link #DOUBLE_EPSILON}.
* <p>
- * <strong>WARNING: </strong>this method is not technically transitive. If a and b are off by slightly less than
- * {@code epsilon * max(abs(a), abs(b))}, and b and c are off by slightly less than
- * {@code epsilon * max(abs(b), abs(c))}, then equals(a, b) and equals(b, c) will both return true, but equals(a, c)
- * will return false. However, this situation is very unlikely to ever happen in a real programming situation.
+ * <strong>WARNING: </strong>this method is not technically transitive. If a
+ * and b are off by slightly less than {@code epsilon * max(abs(a), abs(b))},
+ * and b and c are off by slightly less than
+ * {@code epsilon * max(abs(b), abs(c))}, then equals(a, b) and equals(b, c)
+ * will both return true, but equals(a, c) will return false. However, this
+ * situation is very unlikely to ever happen in a real programming situation.
* <p>
* If this does become a concern, some ways to solve this problem:
* <ol>
- * <li>Raise the value of epsilon using {@link #equals(double, double, double)} (this does not make a violation of
- * transitivity impossible, it just significantly reduces the chances of it happening)
- * <li>Use {@link BigDecimal} instead of {@code double} (this will make a violation of transitivity 100% impossible)
+ * <li>Raise the value of epsilon using
+ * {@link #equals(double, double, double)} (this does not make a violation of
+ * transitivity impossible, it just significantly reduces the chances of it
+ * happening)
+ * <li>Use {@link BigDecimal} instead of {@code double} (this will make a
+ * violation of transitivity 100% impossible)
* </ol>
*
- * @param a
- * first value to test
- * @param b
- * second value to test
+ * @param a first value to test
+ * @param b second value to test
* @return whether they are equal
* @since 2019-03-18
* @since v0.2.0
@@ -71,57 +74,61 @@ public final class DecimalComparison {
public static final boolean equals(final double a, final double b) {
return DecimalComparison.equals(a, b, DOUBLE_EPSILON);
}
-
+
/**
* Tests for double equality using a custom epsilon value.
*
* <p>
- * <strong>WARNING: </strong>this method is not technically transitive. If a and b are off by slightly less than
- * {@code epsilon * max(abs(a), abs(b))}, and b and c are off by slightly less than
- * {@code epsilon * max(abs(b), abs(c))}, then equals(a, b) and equals(b, c) will both return true, but equals(a, c)
- * will return false. However, this situation is very unlikely to ever happen in a real programming situation.
+ * <strong>WARNING: </strong>this method is not technically transitive. If a
+ * and b are off by slightly less than {@code epsilon * max(abs(a), abs(b))},
+ * and b and c are off by slightly less than
+ * {@code epsilon * max(abs(b), abs(c))}, then equals(a, b) and equals(b, c)
+ * will both return true, but equals(a, c) will return false. However, this
+ * situation is very unlikely to ever happen in a real programming situation.
* <p>
* If this does become a concern, some ways to solve this problem:
* <ol>
- * <li>Raise the value of epsilon (this does not make a violation of transitivity impossible, it just significantly
- * reduces the chances of it happening)
- * <li>Use {@link BigDecimal} instead of {@code double} (this will make a violation of transitivity 100% impossible)
+ * <li>Raise the value of epsilon (this does not make a violation of
+ * transitivity impossible, it just significantly reduces the chances of it
+ * happening)
+ * <li>Use {@link BigDecimal} instead of {@code double} (this will make a
+ * violation of transitivity 100% impossible)
* </ol>
*
- * @param a
- * first value to test
- * @param b
- * second value to test
- * @param epsilon
- * allowed difference
+ * @param a first value to test
+ * @param b second value to test
+ * @param epsilon allowed difference
* @return whether they are equal
* @since 2019-03-18
* @since v0.2.0
*/
- public static final boolean equals(final double a, final double b, final double epsilon) {
+ public static final boolean equals(final double a, final double b,
+ final double epsilon) {
return Math.abs(a - b) <= epsilon * Math.max(Math.abs(a), Math.abs(b));
}
-
+
/**
* Tests for equality of float values using {@link #FLOAT_EPSILON}.
*
* <p>
- * <strong>WARNING: </strong>this method is not technically transitive. If a and b are off by slightly less than
- * {@code epsilon * max(abs(a), abs(b))}, and b and c are off by slightly less than
- * {@code epsilon * max(abs(b), abs(c))}, then equals(a, b) and equals(b, c) will both return true, but equals(a, c)
- * will return false. However, this situation is very unlikely to ever happen in a real programming situation.
+ * <strong>WARNING: </strong>this method is not technically transitive. If a
+ * and b are off by slightly less than {@code epsilon * max(abs(a), abs(b))},
+ * and b and c are off by slightly less than
+ * {@code epsilon * max(abs(b), abs(c))}, then equals(a, b) and equals(b, c)
+ * will both return true, but equals(a, c) will return false. However, this
+ * situation is very unlikely to ever happen in a real programming situation.
* <p>
* If this does become a concern, some ways to solve this problem:
* <ol>
- * <li>Raise the value of epsilon using {@link #equals(float, float, float)} (this does not make a violation of
- * transitivity impossible, it just significantly reduces the chances of it happening)
- * <li>Use {@link BigDecimal} instead of {@code float} (this will make a violation of transitivity 100% impossible)
+ * <li>Raise the value of epsilon using {@link #equals(float, float, float)}
+ * (this does not make a violation of transitivity impossible, it just
+ * significantly reduces the chances of it happening)
+ * <li>Use {@link BigDecimal} instead of {@code float} (this will make a
+ * violation of transitivity 100% impossible)
* </ol>
*
- * @param a
- * first value to test
- * @param b
- * second value to test
+ * @param a first value to test
+ * @param b second value to test
* @return whether they are equal
* @since 2019-03-18
* @since v0.2.0
@@ -129,53 +136,121 @@ public final class DecimalComparison {
public static final boolean equals(final float a, final float b) {
return DecimalComparison.equals(a, b, FLOAT_EPSILON);
}
-
+
/**
* Tests for float equality using a custom epsilon value.
*
* <p>
- * <strong>WARNING: </strong>this method is not technically transitive. If a and b are off by slightly less than
- * {@code epsilon * max(abs(a), abs(b))}, and b and c are off by slightly less than
- * {@code epsilon * max(abs(b), abs(c))}, then equals(a, b) and equals(b, c) will both return true, but equals(a, c)
- * will return false. However, this situation is very unlikely to ever happen in a real programming situation.
+ * <strong>WARNING: </strong>this method is not technically transitive. If a
+ * and b are off by slightly less than {@code epsilon * max(abs(a), abs(b))},
+ * and b and c are off by slightly less than
+ * {@code epsilon * max(abs(b), abs(c))}, then equals(a, b) and equals(b, c)
+ * will both return true, but equals(a, c) will return false. However, this
+ * situation is very unlikely to ever happen in a real programming situation.
* <p>
* If this does become a concern, some ways to solve this problem:
* <ol>
- * <li>Raise the value of epsilon (this does not make a violation of transitivity impossible, it just significantly
- * reduces the chances of it happening)
- * <li>Use {@link BigDecimal} instead of {@code float} (this will make a violation of transitivity 100% impossible)
+ * <li>Raise the value of epsilon (this does not make a violation of
+ * transitivity impossible, it just significantly reduces the chances of it
+ * happening)
+ * <li>Use {@link BigDecimal} instead of {@code float} (this will make a
+ * violation of transitivity 100% impossible)
* </ol>
*
- * @param a
- * first value to test
- * @param b
- * second value to test
- * @param epsilon
- * allowed difference
+ * @param a first value to test
+ * @param b second value to test
+ * @param epsilon allowed difference
* @return whether they are equal
* @since 2019-03-18
* @since v0.2.0
*/
- public static final boolean equals(final float a, final float b, final float epsilon) {
+ public static final boolean equals(final float a, final float b,
+ final float epsilon) {
return Math.abs(a - b) <= epsilon * Math.max(Math.abs(a), Math.abs(b));
}
-
+
+ /**
+ * Tests for equality of {@code UncertainDouble} values using
+ * {@link #DOUBLE_EPSILON}.
+ * <p>
+ * <strong>WARNING: </strong>this method is not technically transitive. If a
+ * and b are off by slightly less than {@code epsilon * max(abs(a), abs(b))},
+ * and b and c are off by slightly less than
+ * {@code epsilon * max(abs(b), abs(c))}, then equals(a, b) and equals(b, c)
+ * will both return true, but equals(a, c) will return false. However, this
+ * situation is very unlikely to ever happen in a real programming situation.
+ * <p>
+ * If this does become a concern, some ways to solve this problem:
+ * <ol>
+ * <li>Raise the value of epsilon using
+ * {@link #equals(UncertainDouble, UncertainDouble, double)} (this does not
+ * make a violation of transitivity impossible, it just significantly reduces
+ * the chances of it happening)
+ * <li>Use {@link BigDecimal} instead of {@code double} (this will make a
+ * violation of transitivity 100% impossible)
+ * </ol>
+ *
+ * @param a first value to test
+ * @param b second value to test
+ * @return whether they are equal
+ * @since 2020-09-07
+ * @see #hashCode(double)
+ */
+ public static final boolean equals(final UncertainDouble a,
+ final UncertainDouble b) {
+ return DecimalComparison.equals(a.value(), b.value())
+ && DecimalComparison.equals(a.uncertainty(), b.uncertainty());
+ }
+
+ /**
+ * Tests for {@code UncertainDouble} equality using a custom epsilon value.
+ *
+ * <p>
+ * <strong>WARNING: </strong>this method is not technically transitive. If a
+ * and b are off by slightly less than {@code epsilon * max(abs(a), abs(b))},
+ * and b and c are off by slightly less than
+ * {@code epsilon * max(abs(b), abs(c))}, then equals(a, b) and equals(b, c)
+ * will both return true, but equals(a, c) will return false. However, this
+ * situation is very unlikely to ever happen in a real programming situation.
+ * <p>
+ * If this does become a concern, some ways to solve this problem:
+ * <ol>
+ * <li>Raise the value of epsilon (this does not make a violation of
+ * transitivity impossible, it just significantly reduces the chances of it
+ * happening)
+ * <li>Use {@link BigDecimal} instead of {@code double} (this will make a
+ * violation of transitivity 100% impossible)
+ * </ol>
+ *
+ * @param a first value to test
+ * @param b second value to test
+ * @param epsilon allowed difference
+ * @return whether they are equal
+ * @since 2019-03-18
+ * @since v0.2.0
+ */
+ public static final boolean equals(final UncertainDouble a,
+ final UncertainDouble b, final double epsilon) {
+ return DecimalComparison.equals(a.value(), b.value(), epsilon)
+ && DecimalComparison.equals(a.uncertainty(), b.uncertainty(),
+ epsilon);
+ }
+
/**
- * Takes the hash code of doubles. Values that are equal according to {@link #equals(double, double)} will have the
- * same hash code.
+ * Takes the hash code of doubles. Values that are equal according to
+ * {@link #equals(double, double)} will have the same hash code.
*
- * @param d
- * double to hash
+ * @param d double to hash
* @return hash code of double
* @since 2019-10-16
*/
public static final int hash(final double d) {
return Float.hashCode((float) d);
}
-
+
// You may NOT get any DecimalComparison instances
private DecimalComparison() {
throw new AssertionError();
}
-
+
}
diff --git a/src/org/unitConverter/math/UncertainDouble.java b/src/org/unitConverter/math/UncertainDouble.java
new file mode 100644
index 0000000..3651bd5
--- /dev/null
+++ b/src/org/unitConverter/math/UncertainDouble.java
@@ -0,0 +1,419 @@
+/**
+ * Copyright (C) 2020 Adrien Hopkins
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.unitConverter.math;
+
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+import java.util.Objects;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * A double with an associated uncertainty value. For example, 3.2 ± 0.2.
+ * <p>
+ * All methods in this class throw a NullPointerException if any of their
+ * arguments is null.
+ *
+ * @since 2020-09-07
+ */
+public final class UncertainDouble implements Comparable<UncertainDouble> {
+ /**
+ * The exact value 0
+ */
+ public static final UncertainDouble ZERO = UncertainDouble.of(0, 0);
+
+ /**
+ * A regular expression that can recognize toString forms
+ */
+ private static final Pattern TO_STRING = Pattern
+ .compile("([a-zA-Z_0-9\\.\\,]+)" // a number
+ // optional "± [number]"
+ + "(?:\\s*(?:±|\\+-)\\s*([a-zA-Z_0-9\\.\\,]+))?");
+
+ /**
+ * Parses a string in the form of {@link UncertainDouble#toString(boolean)}
+ * and returns the corresponding {@code UncertainDouble} instance.
+ * <p>
+ * This method allows some alternative forms of the string representation,
+ * such as using "+-" instead of "±".
+ *
+ * @param s string to parse
+ * @return {@code UncertainDouble} instance
+ * @throws IllegalArgumentException if the string is invalid
+ * @since 2020-09-07
+ */
+ public static final UncertainDouble fromString(String s) {
+ Objects.requireNonNull(s, "s may not be null");
+ final Matcher matcher = TO_STRING.matcher(s);
+
+ double value, uncertainty;
+ try {
+ value = Double.parseDouble(matcher.group(1));
+ } catch (IllegalStateException | NumberFormatException e) {
+ throw new IllegalArgumentException(
+ "String " + s + " not in correct format.");
+ }
+
+ final String uncertaintyString = matcher.group(2);
+ if (uncertaintyString == null) {
+ uncertainty = 0;
+ } else {
+ try {
+ uncertainty = Double.parseDouble(uncertaintyString);
+ } catch (final NumberFormatException e) {
+ throw new IllegalArgumentException(
+ "String " + s + " not in correct format.");
+ }
+ }
+
+ return UncertainDouble.of(value, uncertainty);
+ }
+
+ /**
+ * Gets an {@code UncertainDouble} from its value and <b>absolute</b>
+ * uncertainty.
+ *
+ * @since 2020-09-07
+ */
+ public static final UncertainDouble of(double value, double uncertainty) {
+ return new UncertainDouble(value, uncertainty);
+ }
+
+ /**
+ * Gets an {@code UncertainDouble} from its value and <b>relative</b>
+ * uncertainty.
+ *
+ * @since 2020-09-07
+ */
+ public static final UncertainDouble ofRelative(double value,
+ double relativeUncertainty) {
+ return new UncertainDouble(value, value * relativeUncertainty);
+ }
+
+ private final double value;
+
+ private final double uncertainty;
+
+ /**
+ * @param value
+ * @param uncertainty
+ * @since 2020-09-07
+ */
+ private UncertainDouble(double value, double uncertainty) {
+ this.value = value;
+ // uncertainty should only ever be positive
+ this.uncertainty = Math.abs(uncertainty);
+ }
+
+ /**
+ * Compares this {@code UncertainDouble} with another
+ * {@code UncertainDouble}.
+ * <p>
+ * This method only compares the values, not the uncertainties. So 3.1 ± 0.5
+ * is considered less than 3.2 ± 0.5, even though they are equivalent.
+ * <p>
+ * <b>Note:</b> The natural ordering of this class is inconsistent with
+ * equals. Specifically, if two {@code UncertainDouble} instances {@code a}
+ * and {@code b} have the same value but different uncertainties,
+ * {@code a.compareTo(b)} will return 0 but {@code a.equals(b)} will return
+ * {@code false}.
+ */
+ @Override
+ public final int compareTo(UncertainDouble o) {
+ return Double.compare(this.value, o.value);
+ }
+
+ /**
+ * Returns the quotient of {@code this} and {@code other}.
+ *
+ * @since 2020-09-07
+ */
+ public final UncertainDouble dividedBy(UncertainDouble other) {
+ Objects.requireNonNull(other, "other may not be null");
+ return UncertainDouble.ofRelative(this.value / other.value, Math
+ .hypot(this.relativeUncertainty(), other.relativeUncertainty()));
+ }
+
+ /**
+ * Returns the quotient of {@code this} and the exact value {@code other}.
+ *
+ * @since 2020-09-07
+ */
+ public final UncertainDouble dividedByExact(double other) {
+ return UncertainDouble.of(this.value / other, this.uncertainty / other);
+ }
+
+ @Override
+ public final boolean equals(Object obj) {
+ if (this == obj)
+ return true;
+ if (!(obj instanceof UncertainDouble))
+ return false;
+ final UncertainDouble other = (UncertainDouble) obj;
+ if (Double.compare(this.value, other.value) != 0)
+ return false;
+ if (Double.compare(this.uncertainty, other.uncertainty) != 0)
+ return false;
+ return true;
+ }
+
+ /**
+ * @param other another {@code UncertainDouble}
+ * @return true iff this and {@code other} are within each other's
+ * uncertainty range.
+ * @since 2020-09-07
+ */
+ public final boolean equivalent(UncertainDouble other) {
+ Objects.requireNonNull(other, "other may not be null");
+ return Math.abs(this.value - other.value) <= Math.min(this.uncertainty,
+ other.uncertainty);
+ }
+
+ /**
+ * Gets the preferred scale for rounding a value for toString.
+ *
+ * @since 2020-09-07
+ */
+ private final int getDisplayScale() {
+ // round based on uncertainty
+ // if uncertainty starts with 1 (ignoring zeroes and the decimal
+ // point), rounds
+ // so that uncertainty has 2 significant digits.
+ // otherwise, rounds so that uncertainty has 1 significant digits.
+ // the value is rounded to the same number of decimal places as the
+ // uncertainty.
+ final BigDecimal bigUncertainty = BigDecimal.valueOf(this.uncertainty);
+
+ // the scale that will give the uncertainty two decimal places
+ final int twoDecimalPlacesScale = bigUncertainty.scale()
+ - bigUncertainty.precision() + 2;
+ final BigDecimal roundedUncertainty = bigUncertainty
+ .setScale(twoDecimalPlacesScale, RoundingMode.HALF_EVEN);
+
+ if (roundedUncertainty.unscaledValue().intValue() >= 20)
+ return twoDecimalPlacesScale - 1; // one decimal place
+ else
+ return twoDecimalPlacesScale;
+ }
+
+ @Override
+ public final int hashCode() {
+ final int prime = 31;
+ int result = 1;
+ result = prime * result + Double.hashCode(this.value);
+ result = prime * result + Double.hashCode(this.uncertainty);
+ return result;
+ }
+
+ /**
+ * @return true iff the value has no uncertainty
+ *
+ * @since 2020-09-07
+ */
+ public final boolean isExact() {
+ return this.uncertainty == 0;
+ }
+
+ /**
+ * Returns the difference of {@code this} and {@code other}.
+ *
+ * @since 2020-09-07
+ */
+ public final UncertainDouble minus(UncertainDouble other) {
+ Objects.requireNonNull(other, "other may not be null");
+ return UncertainDouble.of(this.value - other.value,
+ Math.hypot(this.uncertainty, other.uncertainty));
+ }
+
+ /**
+ * Returns the difference of {@code this} and the exact value {@code other}.
+ *
+ * @since 2020-09-07
+ */
+ public final UncertainDouble minusExact(double other) {
+ return UncertainDouble.of(this.value - other, this.uncertainty);
+ }
+
+ /**
+ * Returns the sum of {@code this} and {@code other}.
+ *
+ * @since 2020-09-07
+ */
+ public final UncertainDouble plus(UncertainDouble other) {
+ Objects.requireNonNull(other, "other may not be null");
+ return UncertainDouble.of(this.value + other.value,
+ Math.hypot(this.uncertainty, other.uncertainty));
+ }
+
+ /**
+ * Returns the sum of {@code this} and the exact value {@code other}.
+ *
+ * @since 2020-09-07
+ */
+ public final UncertainDouble plusExact(double other) {
+ return UncertainDouble.of(this.value + other, this.uncertainty);
+ }
+
+ /**
+ * @return relative uncertainty
+ * @since 2020-09-07
+ */
+ public final double relativeUncertainty() {
+ return this.uncertainty / this.value;
+ }
+
+ /**
+ * Returns the product of {@code this} and {@code other}.
+ *
+ * @since 2020-09-07
+ */
+ public final UncertainDouble times(UncertainDouble other) {
+ Objects.requireNonNull(other, "other may not be null");
+ return UncertainDouble.ofRelative(this.value * other.value, Math
+ .hypot(this.relativeUncertainty(), other.relativeUncertainty()));
+ }
+
+ /**
+ * Returns the product of {@code this} and the exact value {@code other}.
+ *
+ * @since 2020-09-07
+ */
+ public final UncertainDouble timesExact(double other) {
+ return UncertainDouble.of(this.value * other, this.uncertainty * other);
+ }
+
+ /**
+ * Returns the result of {@code this} raised to the exponent {@code other}.
+ *
+ * @since 2020-09-07
+ */
+ public final UncertainDouble toExponent(UncertainDouble other) {
+ Objects.requireNonNull(other, "other may not be null");
+
+ final double result = Math.pow(this.value, other.value);
+ final double relativeUncertainty = Math.hypot(
+ other.value * this.relativeUncertainty(),
+ Math.log(this.value) * other.uncertainty);
+
+ return UncertainDouble.ofRelative(result, relativeUncertainty);
+ }
+
+ /**
+ * Returns the result of {@code this} raised the exact exponent
+ * {@code other}.
+ *
+ * @since 2020-09-07
+ */
+ public final UncertainDouble toExponentExact(double other) {
+ return UncertainDouble.ofRelative(Math.pow(this.value, other),
+ this.relativeUncertainty() * other);
+ }
+
+ /**
+ * Returns a string representation of this {@code UncertainDouble}.
+ * <p>
+ * This method returns the same value as {@link #toString(boolean)}, but
+ * {@code showUncertainty} is true if and only if the uncertainty is
+ * non-zero.
+ *
+ * <p>
+ * Examples:
+ *
+ * <pre>
+ * UncertainDouble.of(3.27, 0.22).toString() = "3.3 ± 0.2"
+ * UncertainDouble.of(3.27, 0.13).toString() = "3.27 ± 0.13"
+ * UncertainDouble.of(-5.01, 0).toString() = "-5.01"
+ * </pre>
+ *
+ * @since 2020-09-07
+ */
+ @Override
+ public final String toString() {
+ return this.toString(!this.isExact());
+ }
+
+ /**
+ * Returns a string representation of this {@code UncertainDouble}.
+ * <p>
+ * If {@code showUncertainty} is true, the string will be of the form "VALUE
+ * ± UNCERTAINTY", and if it is false the string will be of the form "VALUE"
+ * <p>
+ * VALUE represents a string representation of this {@code UncertainDouble}'s
+ * value. If the uncertainty is non-zero, the string will be rounded to the
+ * same precision as the uncertainty, otherwise it will not be rounded. The
+ * string is still rounded if {@code showUncertainty} is false.<br>
+ * UNCERTAINTY represents a string representation of this
+ * {@code UncertainDouble}'s uncertainty. If the uncertainty ends in 1X
+ * (where X represents any digit) it will be rounded to two significant
+ * digits otherwise it will be rounded to one significant digit.
+ * <p>
+ * Examples:
+ *
+ * <pre>
+ * UncertainDouble.of(3.27, 0.22).toString(false) = "3.3"
+ * UncertainDouble.of(3.27, 0.22).toString(true) = "3.3 ± 0.2"
+ * UncertainDouble.of(3.27, 0.13).toString(false) = "3.27"
+ * UncertainDouble.of(3.27, 0.13).toString(true) = "3.27 ± 0.13"
+ * UncertainDouble.of(-5.01, 0).toString(false) = "-5.01"
+ * UncertainDouble.of(-5.01, 0).toString(true) = "-5.01 ± 0.0"
+ * </pre>
+ *
+ * @since 2020-09-07
+ */
+ public final String toString(boolean showUncertainty) {
+ String valueString, uncertaintyString;
+
+ // generate the string representation of value and uncertainty
+ if (this.isExact()) {
+ uncertaintyString = "0.0";
+ valueString = Double.toString(this.value);
+
+ } else {
+ // round the value and uncertainty according to getDisplayScale()
+ final BigDecimal bigValue = BigDecimal.valueOf(this.value);
+ final BigDecimal bigUncertainty = BigDecimal.valueOf(this.uncertainty);
+
+ final int displayScale = this.getDisplayScale();
+ final BigDecimal roundedUncertainty = bigUncertainty
+ .setScale(displayScale, RoundingMode.HALF_EVEN);
+ final BigDecimal roundedValue = bigValue.setScale(displayScale,
+ RoundingMode.HALF_EVEN);
+
+ valueString = roundedValue.toString();
+ uncertaintyString = roundedUncertainty.toString();
+ }
+
+ // return "value" or "value ± uncertainty" depending on showUncertainty
+ return valueString + (showUncertainty ? " ± " + uncertaintyString : "");
+ }
+
+ /**
+ * @return absolute uncertainty
+ * @since 2020-09-07
+ */
+ public final double uncertainty() {
+ return this.uncertainty;
+ }
+
+ /**
+ * @return value without uncertainty
+ * @since 2020-09-07
+ */
+ public final double value() {
+ return this.value;
+ }
+}
generated by cgit v1.2.3 (git 2.46.0) at 2025-10-03 15:49:19 +0000