/**
 * NumericPrecision.java
 *
 * Copyright (c) 2004-2012, Nicole C. Tedesco.  All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at:
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package net.sf.jaccumulator.scalars;

import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.IdentityHashMap;
import java.util.Map;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicLong;

/**
 * Non-UML semantic lemma that define numeric implementation precision, or
 * implied total digits of any radix.<br/>
 * <br/>
 * All computer numbers are implemented using boolean vectors, the number of
 * significant digits representable being roughly dependent upon the
 * <i>known</i> {@link #size() size} of the implementing vector (bit
 * count). Generally, "known" implies that it is more precise to <i>know</i>
 * that zero digits are available than to not know at all which in turn implies
 * that {@link #UNKNOWN} is <i>less</i> precise than {@link #NULL} which is a
 * known precision (vector size of zero). {@link #isUnlimited() Unlimited}
 * numbers however do not have known digit counts at design time but definitely
 * have known digit counts at runtime so are said to be of higher precision than
 * {@code UNKNOWN} and are, in fact, the highest since their <i>possible</i>
 * digit counts are <i>known</i> to be for all practical purposes unlimited.
 *
 * @since JAccumulator 4.0
 * @author Nicole Tedesco (<a
 *         href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
 */
public enum NumericPrecision
{
    /**
     * <b>Unknown</b> precision, which is even less precise than {@link #NULL}
     * (empty set)
     */
    UNKNOWN( String.class, String.class ) { /* 0 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            return -1;
        }

        @Override
        public final int size() {
            return -1;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return false;
        }

        @Override
        public final boolean isFinite() {
            return false;
        }

        @Override
        public final boolean isFloatingPoint() {
            return false;
        }

        @Override
        public final boolean isIeee754() {
            return false;
        }

        @Override
        public final boolean isIntegral() {
            return false;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return prec != this;
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            return false;
        }

        @Override
        public final boolean isNumeric() {
            return false;
        }

        @Override
        public final boolean isSigned() {
            return false;
        }

        @Override
        public final boolean isUnlimited() {
            return false;
        }

        @Override
        public final NumericPrecision promote() {
            return UNKNOWN;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            return prec;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return UNKNOWN;
        }
    },

    /**
     * No numeric domain, or the <b>empty set</b> (no digits, not even {@code 0}
     * , though its field cardinality is 0)
     */
    NULL( Void.class, Void.TYPE ) { /* 1 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            if (prec == this) {
                return 0;
            }
            if (prec == UNKNOWN) {
                return +1;
            }
            return -1;
        }

        @Override
        public final int size() {
            return 0;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return prec == this;
        }

        @Override
        public final boolean isFinite() {
            return true;
        }

        @Override
        public final boolean isFloatingPoint() {
            return false;
        }

        @Override
        public final boolean isIeee754() {
            return false;
        }

        @Override
        public final boolean isIntegral() {
            return false;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return this.ordinal() < prec.ordinal();
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            return prec == UNKNOWN;
        }

        @Override
        public final boolean isNumeric() {
            return false;
        }

        @Override
        public final boolean isSigned() {
            return false;
        }

        @Override
        public final boolean isUnlimited() {
            return false;
        }

        @Override
        public final NumericPrecision promote() {
            return BIT;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            return this.isLessPreciseThan(prec) ? prec : this;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return FLOAT;
        }
    },

    /**
     * <b>Boolean</b> domain which includes {@code 0} and {@link 1} (field
     * cardinality is 2)
     */
    BIT( Boolean.class, boolean.class ) { /* 2 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            if (prec == this) {
                return 0;
            }
            if (this.isLessPreciseThan(prec)) {
                return -1;
            }
            return +1;
        }

        @Override
        public final int size() {
            return 1;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return prec == this;
        }

        @Override
        public final boolean isFinite() {
            return true;
        }

        @Override
        public final boolean isFloatingPoint() {
            return false;
        }

        @Override
        public final boolean isIeee754() {
            return false;
        }

        @Override
        public final boolean isIntegral() {
            return true;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return this.ordinal() < prec.ordinal();
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            return prec.ordinal() < this.ordinal();
        }

        @Override
        public final boolean isNumeric() {
            return true;
        }

        @Override
        public final boolean isSigned() {
            return false;
        }

        @Override
        public final boolean isUnlimited() {
            return false;
        }

        @Override
        public final NumericPrecision promote() {
            return BYTE;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            return this.isLessPreciseThan(prec) ? prec : this;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return FLOAT;
        }
    },

    /**
     * <b>Byte</b> field, or 8 bits, for a total value count (field cardinality)
     * of 2<sup>8</sup> and a <i>signed</i> value range of <span
     * style="white-space=nowrap">-2<sup>7</sup></span> to <span
     * style="white-space=nowrap">2<sup>7</sup>-1</span>
     */
    BYTE( Byte.class, byte.class ) { /* 3 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            if (prec == this) {
                return 0;
            }
            if (this.isLessPreciseThan(prec)) {
                return -1;
            }
            return +1;
        }

        @Override
        public final int size() {
            return Byte.SIZE;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return prec == this;
        }

        @Override
        public final boolean isFinite() {
            return true;
        }

        @Override
        public final boolean isFloatingPoint() {
            return false;
        }

        @Override
        public final boolean isIeee754() {
            return false;
        }

        @Override
        public final boolean isIntegral() {
            return true;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return this.ordinal() < prec.ordinal();
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            return prec.ordinal() < this.ordinal();
        }

        @Override
        public final boolean isNumeric() {
            return true;
        }

        @Override
        public final boolean isSigned() {
            return true;
        }

        @Override
        public final boolean isUnlimited() {
            return false;
        }

        @Override
        public final NumericPrecision promote() {
            return SHORT;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            return this.isLessPreciseThan(prec) ? prec : this;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return FLOAT;
        }
    },

    /**
     * <b>Short</b> field, or two {@link #BYTE bytes}, for a total value count
     * (field cardinality) of 2<sup>16</sup> and a <i>signed</i> value range of
     * <span style="white-space=nowrap">-2<sup>15</sup></span> to <span
     * style="white-space=nowrap">2<sup>15</sup>-1</span>
     */
    SHORT( Short.class, short.class ) { /* 4 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            if (this.isEquallyPreciseAs(prec)) {
                return 0;
            }
            if (this.isLessPreciseThan(prec)) {
                return -1;
            }
            return +1;
        }

        @Override
        public final int size() {
            return Short.SIZE;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return (prec == this) || (prec == CHARACTER);
        }

        @Override
        public final boolean isFinite() {
            return true;
        }

        @Override
        public final boolean isFloatingPoint() {
            return false;
        }

        @Override
        public final boolean isIeee754() {
            return false;
        }

        @Override
        public final boolean isIntegral() {
            return true;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return CHARACTER.ordinal() < prec.ordinal();
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            return prec.ordinal() < this.ordinal();
        }

        @Override
        public final boolean isNumeric() {
            return true;
        }

        @Override
        public final boolean isSigned() {
            return true;
        }

        @Override
        public final boolean isUnlimited() {
            return false;
        }

        @Override
        public final NumericPrecision promote() {
            return INTEGER;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            return this.isLessPreciseThan(prec) ? prec : this;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return FLOAT;
        }
    },

    /**
     * Unsigned <b>character</b> field with the same bit count as {@link #SHORT}
     * , so it shares both its cardinality (2<sup>16</sup>) and precision,
     * though its <i>unsigned</i> value range is <span
     * style="white-space=nowrap">0</span> to <span
     * style="white-space=nowrap">2<sup>16</sup>-1</span>
     */
    CHARACTER( Character.class, char.class ) { /* 5 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            if (this.isEquallyPreciseAs(prec)) {
                return 0;
            }
            if (this.isLessPreciseThan(prec)) {
                return -1;
            }
            return +1;
        }

        @Override
        public final int size() {
            return Character.SIZE;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return (prec == this) || (prec == SHORT);
        }

        @Override
        public final boolean isFinite() {
            return true;
        }

        @Override
        public final boolean isFloatingPoint() {
            return false;
        }

        @Override
        public final boolean isIeee754() {
            return false;
        }

        @Override
        public final boolean isIntegral() {
            return true;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return this.ordinal() < prec.ordinal();
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            return prec.ordinal() < SHORT.ordinal();
        }

        @Override
        public final boolean isNumeric() {
            return true;
        }

        @Override
        public final boolean isSigned() {
            return false;
        }

        @Override
        public final boolean isUnlimited() {
            return false;
        }

        @Override
        public final NumericPrecision promote() {
            return INTEGER;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            return this.isLessPreciseThan(prec) ? prec : this;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return FLOAT;
        }
    },

    /**
     * <b>Integer</b> field, or 4 bytes (32 bits), for a total value count
     * (field cardinality) of 2<sup>32</sup> and a value range of <span
     * style="white-space=nowrap">-2<sup>31</sup></span> to <span
     * style="white-space=nowrap">2<sup>31</sup>-1</span>
     */
    INTEGER( Integer.class, int.class ) { /* 6 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            if (prec == this) {
                return 0;
            }
            if (this.isLessPreciseThan(prec)) {
                return -1;
            }
            return +1;
        }

        @Override
        public final int size() {
            return Integer.SIZE;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return prec == this;
        }

        @Override
        public final boolean isFinite() {
            return true;
        }

        @Override
        public final boolean isFloatingPoint() {
            return false;
        }

        @Override
        public final boolean isIeee754() {
            return false;
        }

        @Override
        public final boolean isIntegral() {
            return true;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return this.ordinal() < prec.ordinal();
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            return prec.ordinal() < this.ordinal();
        }

        @Override
        public final boolean isNumeric() {
            return true;
        }

        @Override
        public final boolean isSigned() {
            return true;
        }

        @Override
        public final boolean isUnlimited() {
            return false;
        }

        @Override
        public final NumericPrecision promote() {
            return LONG;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            return this.isLessPreciseThan(prec) ? prec : this;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return FLOAT;
        }
    },

    /**
     * <b>Integer</b> field, or 8 bytes (64 bits), for a total value count
     * (field cardinality) of 2<sup>64</sup> and a value range of <span
     * style="white-space=nowrap">-2<sup>63</sup></span> to <span
     * style="white-space=nowrap">2<sup>63</sup>-1</span>
     */
    LONG( Long.class, long.class ) { /* 7 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            if (prec == this) {
                return 0;
            }
            if (this.isLessPreciseThan(prec)) {
                return -1;
            }
            return +1;
        }

        @Override
        public final int size() {
            return Long.SIZE;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return prec == this;
        }

        @Override
        public final boolean isFinite() {
            return true;
        }

        @Override
        public final boolean isFloatingPoint() {
            return false;
        }

        @Override
        public final boolean isIeee754() {
            return false;
        }

        @Override
        public final boolean isIntegral() {
            return true;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return this.ordinal() < prec.ordinal();
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            return prec.ordinal() < this.ordinal();
        }

        @Override
        public final boolean isNumeric() {
            return true;
        }

        @Override
        public final boolean isSigned() {
            return true;
        }

        @Override
        public final boolean isUnlimited() {
            return false;
        }

        @Override
        public final NumericPrecision promote() {
            return UNLIMITED_INTEGER;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            if (prec == FLOAT) return DOUBLE;
            return this.isLessPreciseThan(prec) ? prec : this;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return DOUBLE;
        }
    },

    /**
     * IEEE <a href="http://en.wikipedia.org/wiki/Ieee_float">754-2008</a>
     * single precision {@code float} value (32 bits). Though, strictly
     * speaking, the value field size is actually smaller than that of a 32 bit
     * {@link #INTEGER integer} due to the {@code float}'s 23 bit <a
     * href="http://en.wikipedia.org/wiki/Significand">significand</a> size,
     * {@code float} is treated as a <i>more</i> precise value because of its
     * significantly increased minimum-to-maximum value range.
     */
    FLOAT( Float.class, float.class ) { /* 8 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            if (prec == this) {
                return 0;
            }
            if (this.isLessPreciseThan(prec)) {
                return -1;
            }
            return +1;
        }

        @Override
        public final int size() {
            return Float.SIZE;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return prec == this;
        }

        @Override
        public final boolean isFinite() {
            return true;
        }

        @Override
        public final boolean isFloatingPoint() {
            return true;
        }

        @Override
        public final boolean isIeee754() {
            return true;
        }

        @Override
        public final boolean isIntegral() {
            return false;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return this.ordinal() < prec.ordinal();
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            return prec.ordinal() < this.ordinal();
        }

        @Override
        public final boolean isNumeric() {
            return true;
        }

        @Override
        public final boolean isSigned() {
            return true;
        }

        @Override
        public final boolean isUnlimited() {
            return false;
        }

        @Override
        public final NumericPrecision promote() {
            return DOUBLE;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            if (prec == LONG) return DOUBLE;
            if (prec == UNLIMITED_INTEGER) return UNLIMITED_DECIMAL;
            if ((prec == DOUBLE) || (prec == UNLIMITED_DECIMAL)) {
                return prec;
            }
            return this;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return this;
        }
    },

    /**
     * IEEE <a href="http://en.wikipedia.org/wiki/Ieee_float">754-2008</a>
     * single precision {@code float} value (32 bits). Though, strictly
     * speaking, the value field size is actually smaller than that of a 64 bit
     * {@link #LONG long} due to the {@code double}'s 53 bit <a
     * href="http://en.wikipedia.org/wiki/Significand">significand</a> size,
     * {@code double} is treated as a <i>more</i> precise value because of its
     * significantly increased minimum-to-maximum value range.
     */
    DOUBLE( Double.class, double.class ) { /* 9 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            if (prec == this) {
                return 0;
            }
            if (this.isLessPreciseThan(prec)) {
                return -1;
            }
            return +1;
        }

        @Override
        public final int size() {
            return Double.SIZE;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return prec == this;
        }

        @Override
        public final boolean isFinite() {
            return true;
        }

        @Override
        public final boolean isFloatingPoint() {
            return true;
        }

        @Override
        public final boolean isIeee754() {
            return true;
        }

        @Override
        public final boolean isIntegral() {
            return false;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return this.ordinal() < prec.ordinal();
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            return prec.ordinal() < this.ordinal();
        }

        @Override
        public final boolean isNumeric() {
            return true;
        }

        @Override
        public final boolean isSigned() {
            return true;
        }

        @Override
        public final boolean isUnlimited() {
            return false;
        }

        @Override
        public final NumericPrecision promote() {
            return UNLIMITED_DECIMAL;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            if (prec == UNLIMITED_INTEGER) return UNLIMITED_DECIMAL;
            return prec == UNLIMITED_DECIMAL ? UNLIMITED_DECIMAL : this;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return this;
        }
    },

    /**
     * <b>Unlimited integer</b> value of arbitrary precision, which is only less
     * precise than the unlimited {@link #UNLIMITED_DECIMAL decimal} precision
     */
    UNLIMITED_INTEGER( BigInteger.class, BigInteger.class ) { /* 10 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            if (prec == this) {
                return 0;
            }
            if (this.isLessPreciseThan(prec)) {
                return -1;
            }
            return +1;
        }

        @Override
        public final int size() {
            return -1;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return prec == this;
        }

        @Override
        public final boolean isFinite() {
            return false;
        }

        @Override
        public final boolean isFloatingPoint() {
            return false;
        }

        @Override
        public final boolean isIeee754() {
            return false;
        }

        @Override
        public final boolean isIntegral() {
            return true;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return prec == UNLIMITED_DECIMAL;
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            if (prec == this) {
                return false;
            }
            if (prec == UNLIMITED_DECIMAL) {
                return false;
            }
            return true;
        }

        @Override
        public final boolean isNumeric() {
            return true;
        }

        @Override
        public final boolean isSigned() {
            return true;
        }

        @Override
        public final boolean isUnlimited() {
            return true;
        }

        @Override
        public final NumericPrecision promote() {
            return UNLIMITED_DECIMAL;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            return prec.isFloatingPoint() ? UNLIMITED_DECIMAL : this;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return UNLIMITED_DECIMAL;
        }
    },

    /**
     * <b>Unlimited decimal</b> value of arbitrary precision and the highest
     * precision of any specifiable value
     */
    UNLIMITED_DECIMAL( BigDecimal.class, BigDecimal.class ) { /* 11 */
        @Override
        public final int compare( final NumericPrecision prec ) {
            if (prec == this) {
                return 0;
            }
            return +1;
        }

        @Override
        public final int size() {
            return -1;
        }

        @Override
        public final boolean isEquallyPreciseAs( final NumericPrecision prec ) {
            return prec == this;
        }

        @Override
        public final boolean isFinite() {
            return false;
        }

        @Override
        public final boolean isFloatingPoint() {
            return true;
        }

        @Override
        public final boolean isIeee754() {
            return false;
        }

        @Override
        public final boolean isIntegral() {
            return false;
        }

        @Override
        public final boolean isLessPreciseThan( final NumericPrecision prec ) {
            return false;
        }

        @Override
        public final boolean isMorePreciseThan( final NumericPrecision prec ) {
            return prec != this;
        }

        @Override
        public final boolean isNumeric() {
            return true;
        }

        @Override
        public final boolean isSigned() {
            return true;
        }

        @Override
        public final boolean isUnlimited() {
            return true;
        }

        @Override
        public final NumericPrecision promote() {
            return this;
        }

        @Override
        public final NumericPrecision promoteAgainst(
            final NumericPrecision prec )
        {
            return this;
        }

        @Override
        public final NumericPrecision toFloatingPoint() {
            return this;
        }
    },

    ;

    private final static Map<Class<?>,NumericPrecision> _theClassPrecisionMap = new IdentityHashMap<Class<?>,NumericPrecision>();

    public static NumericPrecision MAXIMUM = UNLIMITED_DECIMAL;
    public static NumericPrecision MINIMUM = UNKNOWN;

    static {
        for (final NumericPrecision prec : NumericPrecision.values()) {
            _theClassPrecisionMap.put(prec.getNumberClass(), prec);
            _theClassPrecisionMap.put(prec.getPrimitiveClass(), prec);
        }
        _theClassPrecisionMap.put(null, NULL);
        _theClassPrecisionMap.put(AtomicBoolean.class, BIT);
        _theClassPrecisionMap.put(AtomicInteger.class, INTEGER);
        _theClassPrecisionMap.put(AtomicLong.class, LONG);
        _theClassPrecisionMap.put(Appendable.class, UNKNOWN);
        _theClassPrecisionMap.put(StringBuilder.class, UNKNOWN);
        _theClassPrecisionMap.put(StringBuffer.class, UNKNOWN);
        _theClassPrecisionMap.put(CharSequence.class, UNKNOWN);
    }

    private final Class<?> _theNumberClass;
    private final Class<?> _thePrimitiveClass;

    private NumericPrecision(
        final Class<?> aNumberClass,
        final Class<?> aPrimitiveClass )
    {
        this._theNumberClass = aNumberClass;
        this._thePrimitiveClass = aPrimitiveClass;
    }

    /**
     * {@link Comparable#compareTo(Object) Primitive1} this precision against
     * another. This method is included, and named what it is because
     * {@link Enum} implements {@code compareTo} to simply compare the
     * {@link Enum#ordinal() ordinal} values of any two compatible enumerations.
     *
     * @param prec
     *        another precision
     * @return 0 if this precision and the specified one are the same precision,
     *         -1 if this precision is less precise, or +1 if this precision is
     *         more precise
     * @see Comparable#compareTo(Object)
     */
    public abstract int compare( final NumericPrecision prec );

    public final Class<?> getNumberClass() {
        return this._theNumberClass;
    }

    public final Class<?> getPrimitiveClass() {
        return this._thePrimitiveClass;
    }

    /**
     * @param prec
     *        another precision enumeration
     * @return {@code true} if this precision is as precise as the specified
     *         precision
     */
    public abstract boolean isEquallyPreciseAs( NumericPrecision prec );

    /**
     * @return {@code true} if this precision is known and finite
     */
    public abstract boolean isFinite();

    /**
     * @return {@code true} if this precision represents a floating point value
     */
    public abstract boolean isFloatingPoint();

    /**
     * @return {@code true} if this precision represents an IEEE 754 floating
     *         point value
     * @see <a href="http://en.wikipedia.org/wiki/IEEE_754">IEEE 754</a>
     *      (Wikipedia)
     */
    public abstract boolean isIeee754();

    /**
     * @return {@code true} if this precision represents an integral (no decimal
     *         point) value
     */
    public abstract boolean isIntegral();

    /**
     * @param prec
     *        another precision enumeration
     * @return {@code true} if this precision is less precise or as equally
     *         precise as the specified precision
     */
    public final boolean isLessOrEquallyPreciseAs( final NumericPrecision prec )
    {
        if (this.isEquallyPreciseAs(prec)) {
            return true;
        }
        if (this.isLessPreciseThan(prec)) {
            return true;
        }
        return false;
    }

    /**
     * @param prec
     *        another precision enumeration
     * @return {@code true} if this precision is less precise than the specified
     *         precision
     */
    public abstract boolean isLessPreciseThan( NumericPrecision prec );

    /**
     * @param prec
     *        another precision enumeration
     * @return {@code true} if this precision is more precise or as equally
     *         precise as the specified precision
     */
    public final boolean isMoreOrEquallyPreciseAs( final NumericPrecision prec )
    {
        if (this.isEquallyPreciseAs(prec)) {
            return true;
        }
        if (this.isMorePreciseThan(prec)) {
            return true;
        }
        return false;
    }

    /**
     * @param prec
     *        another precision enumeration
     * @return {@code true} if this precision is more precise than the specified
     *         precision
     */
    public abstract boolean isMorePreciseThan( final NumericPrecision prec );

    /**
     * @return {@code true} if this is a valid numeric precision
     */
    public abstract boolean isNumeric();

    /**
     * @return {@code true} if this precision is known and signed
     */
    public abstract boolean isSigned();

    /**
     * @return {@code true} if objects with this precision are implemented using
     *         unlimited precision (e.g., {@link BigInteger} or
     *         {@link BigDecimal})
     */
    public abstract boolean isUnlimited();

    public final NumericPrecision maximumOf( final NumericPrecision prec ) {
        if (this.isMoreOrEquallyPreciseAs(prec)) {
            return this;
        }
        return prec;
    }

    public final NumericPrecision maximumOfAll(
        final NumericPrecision... precisions )
    {
        NumericPrecision max = this;
        for (final NumericPrecision prec : precisions) {
            max = max.maximumOf(prec);
        }
        return max;
    }

    /**
     * @return a minimally more, or the "next" more, numerically precise
     *         enumeration value
     */
    public abstract NumericPrecision promote();

    /**
     * Answer a precision value such that any mathematical operation between
     * values of this precision and those of the specified one will not result
     * in a loss of information. The dynamics of this promotion are such that
     * all primitive promotions will rapidly converge upon {@link #DOUBLE}
     * unless precisions smaller than {@link #LONG} are explicitly promoted
     * against {@link #FLOAT}. {@link #isIntegral() Integral} numbers are always
     * promoted to floating points (rational real numbers when compared against
     * them. The {@link #isUnlimited() unlimited} precision types (e.g.,
     * {@link BigInteger} and {@link BigDecimal}) will always force a promotion
     * to themselves.<br>
     * <br>
     * Note that this algorithm may not be recommended under all circumstances,
     * for instance under division where it may be desirable to promote to a
     * floating point precision under all circumstances. Therefore treat this
     * promotion behavior as a default behavior which remains agnostic to
     * specific operations.
     *
     * @param prec
     *        a precision to test against
     * @return a precision such that any mathematical operation between values
     *         of this precision and those of the specified one will not result
     *         in a loss of information
     */
    public abstract NumericPrecision promoteAgainst( final NumericPrecision prec );

    /**
     * @return the number of bits used to represent values of this type in this
     *         system or -1 for {@link #UNKNOWN} or {@link #isUnlimited()
     *         unlimited}
     */
    public abstract int size();

    /**
     * @return a minimally more, or the "next" more, precise <i>floating
     *         point</i> enumeration value if this was integral or otherwise
     *         answer itself
     */
    public abstract NumericPrecision toFloatingPoint();

    public final static NumericPrecision getPrecisionFor( final Class<?> aClass )
    {
        final NumericPrecision prec = _theClassPrecisionMap.get(aClass);
        if ( prec == null ) {
            return UNKNOWN;
        }
        return prec;
    }

    public final static NumericPrecision getPrecisionFor( final Object aValue )
    {
        final Class<?> aClass = aValue.getClass();
        final NumericPrecision prec = _theClassPrecisionMap.get(aClass);
        if (prec != null) {
            return prec;
        }
        if (aValue instanceof SealedScalarDomain) {
            final SealedScalarDomain aDomain = (SealedScalarDomain)aValue;
            return aDomain.getPrecision();
        }
        return UNKNOWN;
    }
}