001/**
002 * SealedScalar.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"); you may not
007 * use this file except in compliance with the License. You may obtain a copy of
008 * 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, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations under
016 * the License.
017 */
018
019package net.sf.jaccumulator.scalars;
020
021import net.sf.jaccumulator.SealedKernel;
022import net.sf.jaccumulator.booleans.SealedBooleanValue;
023import net.sf.jaccumulator.bytes.SealedByteValue;
024import net.sf.jaccumulator.characters.SealedCharacterValue;
025import net.sf.jaccumulator.doubles.SealedDoubleValue;
026import net.sf.jaccumulator.floats.SealedFloatValue;
027import net.sf.jaccumulator.integers.SealedIntegerValue;
028import net.sf.jaccumulator.longs.SealedLongValue;
029import net.sf.jaccumulator.shorts.SealedShortValue;
030
031/**
032 * Read operations for all system supported "scalar" values, or binary vectors
033 * optimized for processing and generally participate in arithmetic operators
034 * supported by the host programming language
035 * 
036 * @param <SCALAR>
037 *        the type of scalar to produce from the {@link #copy()} function
038 * @since JAccumulator 4.0
039 * @author Nicole Tedesco (<a
040 *         href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
041 */
042public interface SealedScalar<SCALAR extends SealedScalar<SCALAR>>
043    extends
044        SealedScalarDomain,
045        SealedKernel,
046        NumericProperties,
047        CharacterProperties,
048        ScalarReplicator<SCALAR>,
049        SealedBooleanValue,
050        SealedByteValue,
051        SealedCharacterValue,
052        SealedDoubleValue,
053        SealedFloatValue,
054        SealedIntegerValue,
055        SealedLongValue,
056        SealedShortValue
057{
058    /**
059     * Compares this object with the specified object for order
060     * 
061     * @param aValue
062     *        an object to be compared to
063     * @return a negative integer, zero, or a positive integer if this object is
064     *         less than, equal to, or greater than the specified object.
065     * @see Comparable#compareTo(Object)
066     */
067    public int compareToNumber( final Number aValue );
068
069    /**
070     * Compares this object with the specified scalar for order
071     * 
072     * @param aValue
073     *        a scalar to be compared to
074     * @return a negative integer, zero, or a positive integer if this object is
075     *         less than, equal to, or greater than the specified scalar.
076     * @see Comparable#compareTo(Object)
077     */
078    public int compareToScalar( final boolean aValue );
079
080    /**
081     * Compares this object with the specified scalar for order
082     * 
083     * @param aValue
084     *        a scalar to be compared to
085     * @return a negative integer, zero, or a positive integer if this object is
086     *         less than, equal to, or greater than the specified scalar.
087     * @see Comparable#compareTo(Object)
088     */
089    public int compareToScalar( final byte aValue );
090
091    /**
092     * Compares this object with the specified scalar for order
093     * 
094     * @param aValue
095     *        a scalar to be compared to
096     * @return a negative integer, zero, or a positive integer if this object is
097     *         less than, equal to, or greater than the specified scalar.
098     * @see Comparable#compareTo(Object)
099     */
100    public int compareToScalar( final char aValue );
101
102    /**
103     * Compares this object with the specified scalar for order
104     * 
105     * @param aValue
106     *        a scalar to be compared to
107     * @return a negative integer, zero, or a positive integer if this object is
108     *         less than, equal to, or greater than the specified scalar.
109     * @see Comparable#compareTo(Object)
110     */
111    public int compareToScalar( final double aValue );
112
113    /**
114     * Compares this object with the specified scalar for order
115     * 
116     * @param aValue
117     *        a scalar to be compared to
118     * @return a negative integer, zero, or a positive integer if this object is
119     *         less than, equal to, or greater than the specified scalar.
120     * @see Comparable#compareTo(Object)
121     */
122    public int compareToScalar( final float aValue );
123
124    /**
125     * Compares this object with the specified scalar for order
126     * 
127     * @param aValue
128     *        a scalar to be compared to
129     * @return a negative integer, zero, or a positive integer if this object is
130     *         less than, equal to, or greater than the specified scalar.
131     * @see Comparable#compareTo(Object)
132     */
133    public int compareToScalar( final int aValue );
134
135    /**
136     * Compares this object with the specified scalar for order
137     * 
138     * @param aValue
139     *        a scalar to be compared to
140     * @return a negative integer, zero, or a positive integer if this object is
141     *         less than, equal to, or greater than the specified scalar.
142     * @see Comparable#compareTo(Object)
143     */
144    public int compareToScalar( final long aValue );
145
146    /**
147     * Compares this object with the specified object for order
148     * 
149     * @param aValue
150     *        an object to be compared to
151     * @return a negative integer, zero, or a positive integer if this object is
152     *         less than, equal to, or greater than the specified object.
153     * @see Comparable#compareTo(Object)
154     */
155    public int compareToScalar( final SealedScalar<?> aValue );
156
157    /**
158     * Compares this object with the specified scalar for order
159     * 
160     * @param aValue
161     *        a scalar to be compared to
162     * @return a negative integer, zero, or a positive integer if this object is
163     *         less than, equal to, or greater than the specified scalar.
164     * @see Comparable#compareTo(Object)
165     */
166    public int compareToScalar( final short aValue );
167
168    /**
169     * Compares this object with zero for order
170     * 
171     * @return a negative integer, zero, or a positive integer if this object is
172     *         less than, equal to, or greater than zero
173     * @see Comparable#compareTo(Object)
174     */
175    public int compareToZero();
176
177    public boolean isEqual( final boolean aScalar );
178
179    public boolean isEqual( final byte aScalar );
180
181    public boolean isEqual( final char aScalar );
182
183    public boolean isEqual( final double aScalar );
184
185    public boolean isEqual( final float aScalar );
186
187    public boolean isEqual( final int aScalar );
188
189    public boolean isEqual( final long aScalar );
190
191    public boolean isEqual( final short aScalar );
192
193    public boolean isEqualToNumber( final Number aValue );
194
195    public boolean isEqualToScalar( final SealedScalar<?> aScalar );
196
197    /**
198     * @return this object represents a {@code false} value if {@code boolean},
199     *         or the additive identity otherwise
200     */
201    public boolean isFalse();
202
203    public boolean isGreater( final boolean aScalar );
204
205    public boolean isGreater( final byte aScalar );
206
207    public boolean isGreater( final char aScalar );
208
209    public boolean isGreater( final double aScalar );
210
211    public boolean isGreater( final float aScalar );
212
213    public boolean isGreater( final int aScalar );
214
215    public boolean isGreater( final long aScalar );
216
217    public boolean isGreater( final short aScalar );
218
219    public boolean isGreaterOrEqual( final boolean aScalar );
220
221    public boolean isGreaterOrEqual( final byte aScalar );
222
223    public boolean isGreaterOrEqual( final char aScalar );
224
225    public boolean isGreaterOrEqual( final double aScalar );
226
227    public boolean isGreaterOrEqual( final float aScalar );
228
229    public boolean isGreaterOrEqual( final int aScalar );
230
231    public boolean isGreaterOrEqual( final long aScalar );
232
233    public boolean isGreaterOrEqual( final short aScalar );
234
235    public boolean isGreaterOrEqualToNumber( final Number aValue );
236
237    public boolean isGreaterOrEqualToScalar( final SealedScalar<?> aScalar );
238
239    public boolean isGreaterThanNumber( final Number aValue );
240
241    public boolean isGreaterThanScalar( final SealedScalar<?> aScalar );
242
243    public boolean isLess( final boolean aScalar );
244
245    public boolean isLess( final byte aScalar );
246
247    public boolean isLess( final char aScalar );
248
249    public boolean isLess( final double aScalar );
250
251    public boolean isLess( final float aScalar );
252
253    public boolean isLess( final int aScalar );
254
255    public boolean isLess( final long aScalar );
256
257    public boolean isLess( final short aScalar );
258
259    public boolean isLessOrEqual( final boolean aScalar );
260
261    public boolean isLessOrEqual( final byte aScalar );
262
263    public boolean isLessOrEqual( final char aScalar );
264
265    public boolean isLessOrEqual( final double aScalar );
266
267    public boolean isLessOrEqual( final float aScalar );
268
269    public boolean isLessOrEqual( final int aScalar );
270
271    public boolean isLessOrEqual( final long aScalar );
272
273    public boolean isLessOrEqual( final short aScalar );
274
275    public boolean isLessOrEqualToNumber( final Number aValue );
276
277    public boolean isLessOrEqualToScalar( final SealedScalar<?> aScalar );
278
279    public boolean isLessThanNumber( final Number aValue );
280
281    public boolean isLessThanScalar( final SealedScalar<?> aScalar );
282
283    public boolean isNotEqual( final boolean aScalar );
284
285    public boolean isNotEqual( final byte aScalar );
286
287    public boolean isNotEqual( final char aScalar );
288
289    public boolean isNotEqual( final double aScalar );
290
291    public boolean isNotEqual( final float aScalar );
292
293    public boolean isNotEqual( final int aScalar );
294
295    public boolean isNotEqual( final long aScalar );
296
297    public boolean isNotEqual( final short aScalar );
298
299    public boolean isNotEqualToNumber( final Number aValue );
300
301    public boolean isNotEqualToScalar( final SealedScalar<?> aScalar );
302
303    /**
304     * @return this object represents a {@code true} value if {@code boolean},
305     *         or the multiplicative identity otherwise
306     */
307    public boolean isTrue();
308
309    /**
310     * @return this object as a best-match, system-supported {@link Boolean}
311     *         object
312     */
313    public Boolean toBoolean();
314
315    /**
316     * @return this object as a best-match, system-supported {@link Boolean}
317     *         object
318     */
319    public Character toCharacter();
320
321    /**
322     * Represent the value of this object as a code point
323     * 
324     * @return the value of this object represented as a single code point
325     */
326    public int toCodePoint();
327
328    /**
329     * Represent the value of this object as an appropriate member of the class
330     * of the specified {@link Enum enumeration}
331     * 
332     * @param anEnumerationClass
333     *        the class of {@link Enum enumeration} to convert to
334     * @return this object (facilitates operation chaining)
335     * @throws IllegalArgumentException
336     *         if the specified value was incommensurate with this object's
337     *         specification
338     * @throws ArithmeticException
339     *         the numeric value provided was incompatible with with algebraic
340     *         interpretation of this object
341     * @throws NullPointerException
342     *         a {@code null} value was provided though this object does not
343     *         accept {@code null} values
344     */
345    public <E extends Enum<E>> E toEnumeration(
346        final Class<E> anEnumerationClass )
347        throws ArithmeticException,
348            IllegalArgumentException,
349            NullPointerException;
350
351    /**
352     * @return this object as a best-match, system-supported {@link Number}
353     *         object
354     */
355    public Number toNumber();
356}