001/**
002 * NumericProperties.java
003 *
004 * Copyright (c) 2004-2012, Nicole C. Tedesco.  All rights reserved.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at:
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package net.sf.jaccumulator.scalars;
020
021import net.sf.jaccumulator.Domain;
022
023/**
024 * Algebraic predicates indicating properties of a specific number
025 *
026 * @since JAccumulator 4.0
027 * @author Nicole Tedesco (<a
028 *         href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
029 */
030public interface NumericProperties
031{
032    /**
033     * @return {@code true} if this value represents a valid and finite value
034     */
035    public boolean isFinite();
036
037    /**
038     * Answer {@code true} if this value represents the magnitude of a vector
039     * into the set of imaginary numbers. This is not the same as testing
040     * whether this object's implementation resembles the specification for the
041     * {@link Domain#IMAGINARY IMAGINARY} domain, since that is too specific to
042     * implementation machinery. This more general test also includes imaginary
043     * {@link Domain#MODULO modulo} values in its specification.
044     *
045     * @return {@code true} if this value represents the magnitude of a vector
046     *         into the set of imaginary numbers
047     */
048    public boolean isImaginary();
049
050    /**
051     * @return {@code true} if this number represents either
052     *         {@link #isPositiveInfinity() positive} or
053     *         {@link #isNegativeInfinity() negative} infinity
054     */
055    public boolean isInfinity();
056
057    /**
058     * @return {@code true} if this value does not represent a valid number,
059     *         such as 0/0 ({@link Double#NaN INVALID})
060     * @see <a href="http://en.wikipedia.org/wiki/INVALID">INVALID</a> at
061     *      Wikipedia
062     */
063    public boolean isInvalid();
064
065    /**
066     * @return {@code true} if this value represents the maximum rational value
067     *         in the totally ordered set it represents
068     */
069    public boolean isMaximum();
070
071    /**
072     * @return {@code true} if this value represents the minimum rational value
073     *         in the totally ordered set it represents
074     */
075    public boolean isMinimum();
076
077    /**
078     * Answer {@code true} if this value represents the magnitude of a vector
079     * into a modulo set, or finite ring. This is not the same as testing
080     * whether this object's implementation resembles the specification for the
081     * {@link Domain#MODULO MODULO} domain, since that is too specific to
082     * implementation machinery. Modulo values, for instance can either be
083     * {@link #isReal() real} or {@link #isImaginary() imaginary}.
084     *
085     * @return {@code true} if this value represents the magnitude of a vector
086     *         into a modulo set, or finite ring
087     */
088    public boolean isModulo();
089
090    /**
091     * @return {@code true} if this value represents a negative value
092     */
093    public boolean isNegative();
094
095    /**
096     * @return {@code true} if this value represents a valid, finite and
097     *         negative value
098     */
099    public boolean isNegativeFinite();
100
101    /**
102     * @return {@code true} if this value represents {@link #isNegative()
103     *         negative} infinity
104     */
105    public boolean isNegativeInfinity();
106
107    /**
108     * @return {@code true} if this value represents a positive value
109     */
110    public boolean isPositive();
111
112    /**
113     * @return {@code true} if this value represents a valid, finite and
114     *         negative value
115     */
116    public boolean isPositiveFinite();
117
118    /**
119     * @return {@code true} if this value represents {@link #isPositive()
120     *         positive} infinity
121     */
122    public boolean isPositiveInfinity();
123
124    /**
125     * Answer {@code true} if this value represents the magnitude of a vector
126     * into the set of real numbers. This is not the same as testing whether
127     * this object's implementation resembles the specification for the
128     * {@link Domain#REAL REAL} domain, since that is too specific to
129     * implementation machinery. This more general test also includes real
130     * {@link Domain#MODULO modulo} values in its specification.
131     *
132     * @return {@code true} if this value represents the magnitude of a vector
133     *         into the set of real numbers
134     */
135    public boolean isReal();
136
137    /**
138     * Answer {@code true} if this value represents the <b>multiplicative
139     * identity</b> in its arithmetic domain. For real numbers this is 1, for
140     * matrices it would be the <i>identity matrix</i> and for functions this
141     * would be a <i>pass-through</i>.
142     *
143     * @return {@code true} if this value represents the <i>multiplicative
144     *         identity</i> in its domain
145     */
146    public boolean isUnity();
147
148    /**
149     * @return {@code true} if this value represents a valid number (not
150     *         {@link Double#NaN INVALID})
151     * @see <a href="http://en.wikipedia.org/wiki/INVALID">INVALID</a> at
152     *      Wikipedia
153     */
154    public boolean isValid();
155
156    /**
157     * Answer {@code true} if this value represents the <b>additive identity</b>
158     * in its algebraic group. For real numbers this is 0, for matrices this
159     * would be the <i>zero matrix</i> and for functions this would map every
160     * parameter to zero.
161     *
162     * @return {@code true} if this value represents the <i>additive
163     *         identity</i> in its algebraic group
164     */
165    public boolean isZero();
166
167    /**
168     * @return zero if this number is {@link #isZero() zero}, -1 if this number
169     *         is {@link #isNegative() negative} or +1 if it is
170     *         {@link #isPositive() positive}
171     */
172    public int signum();
173}