001/**
002 * MutablePrimitive.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.primitives;
020
021import java.math.BigDecimal;
022import java.math.BigInteger;
023
024import net.sf.jaccumulator.reals.MutableReal;
025import net.sf.jaccumulator.scalars.MutableScalar;
026import net.sf.jaccumulator.texts.MutableText;
027
028/**
029 * Write operations for system supported primitives. "Primitives", as defined in
030 * the UML 2.1 specification, are:
031 * <ul>
032 * <li>{@code boolean}</li>
033 * <li>{@code byte}</li>
034 * <li>{@code char}</li>
035 * <li>{@code int}</li>
036 * <li>{@code long}</li>
037 * <li>{@code float}</li>
038 * <li>{@code double}</li>
039 * <li>{@code short}</li>
040 * <li>unlimited {@link BigInteger integer}</li>
041 * <li>unlimited {@link BigDecimal decimal}</li>
042 * <li>{@link String text}</li>
043 * </ul>
044 *
045 * @param <PRIMITIVE>
046 *        this type (used to facilitate operation chaining)
047 * @since JAccumulator 4.0
048 * @author Nicole Tedesco (<a
049 *         href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
050 */
051public interface MutablePrimitive<PRIMITIVE extends MutablePrimitive<PRIMITIVE>>
052    extends
053        MutableText<PRIMITIVE>,
054        MutableReal<PRIMITIVE>,
055        MutableScalar<PRIMITIVE>
056{
057    /**
058     * Set this value to the bit <b>and</b> of the <i>integral</i> boolean
059     * vector equivalent of this value and the specified integral boolean vector
060     *
061     * @param aValue
062     *        an integral boolean vector
063     * @return this object (facilitates operation chaining)
064     * @throws UnsupportedOperationException
065     *         if this object's value cannot be changed
066     * @throws IllegalArgumentException
067     *         if the new value was incommensurate with this object's
068     *         specification
069     * @throws ArithmeticException
070     *         the new numeric value was incompatible with with algebraic
071     *         interpretation of this object
072     */
073    public PRIMITIVE andOfPrimitive( final SealedPrimitive<?> aValue )
074        throws UnsupportedOperationException,
075            IllegalArgumentException,
076            ArithmeticException;
077
078    /**
079     * Set this value to the angle formed by the rectangular coordinates given
080     * by the current value, <i>x</i>, and the specified value, <i>y</i>. In
081     * other words returns the angle <i>theta</i> from the conversion of
082     * rectangular coordinates (x,y) to polar coordinates (r,<i>theta</i>).
083     *
084     * @param y
085     *        a <i>y</i> coordinate value
086     * @return this object (facilitates operation chaining)
087     * @throws UnsupportedOperationException
088     *         if this object's value cannot be changed
089     * @throws IllegalArgumentException
090     *         if the new value was incommensurate with this object's
091     *         specification
092     * @throws ArithmeticException
093     *         the new numeric value was incompatible with with algebraic
094     *         interpretation of this object
095     * @see Math#atan2(double, double)
096     */
097    public PRIMITIVE angleWithPrimitive( final SealedPrimitive<?> y )
098        throws UnsupportedOperationException,
099            IllegalArgumentException,
100            ArithmeticException;
101
102    /**
103     * Set the value of this scalar to the <i>mathematical</i> difference
104     * between its current value and the specified value.
105     *
106     * @param aValue
107     *        a subtrahend
108     * @return this object (facilitates operation chaining)
109     * @throws UnsupportedOperationException
110     *         if this object's value cannot be changed
111     * @throws IllegalArgumentException
112     *         if the new value was incommensurate with this object's
113     *         specification
114     * @throws ArithmeticException
115     *         the new numeric value was incompatible with with algebraic
116     *         interpretation of this object
117     */
118    public PRIMITIVE differenceOfPrimitive( final SealedPrimitive<?> aValue )
119        throws UnsupportedOperationException,
120            IllegalArgumentException,
121            ArithmeticException;
122
123    /**
124     * Set this value to the hypotenuse formed by the square root of the sum of
125     * the square of the current value, <i>x</i>, and the square of the
126     * specified value, <i>y</i>, without intermediate overflow or underflow
127     *
128     * @param y
129     *        a <i>y</i> value
130     * @return this object (facilitates operation chaining)
131     * @throws UnsupportedOperationException
132     *         if this object's value cannot be changed
133     * @throws IllegalArgumentException
134     *         if the new value was incommensurate with this object's
135     *         specification
136     * @throws ArithmeticException
137     *         the new numeric value was incompatible with with algebraic
138     *         interpretation of this object
139     * @see Math#hypot(double, double)
140     */
141    public PRIMITIVE hypotenuseWithPrimitive( final SealedPrimitive<?> y )
142        throws UnsupportedOperationException,
143            IllegalArgumentException,
144            ArithmeticException;
145
146    /**
147     * Set the value of this scalar to its current value <i>modulo</i> of the
148     * specified value
149     *
150     * @param aValue
151     *        a modulus
152     * @return this object (facilitates operation chaining)
153     * @throws UnsupportedOperationException
154     *         if this object's value cannot be changed
155     * @throws IllegalArgumentException
156     *         if the new value was incommensurate with this object's
157     *         specification
158     * @throws ArithmeticException
159     *         the new numeric value was incompatible with with algebraic
160     *         interpretation of this object
161     */
162    public PRIMITIVE modOfPrimitive( final SealedPrimitive<?> aValue )
163        throws UnsupportedOperationException,
164            IllegalArgumentException,
165            ArithmeticException;
166
167    /**
168     * Set this value to the bit <b>or</b> of the <i>integral</i> boolean vector
169     * equivalent of this value and the specified integral boolean vector
170     *
171     * @param aValue
172     *        an integral boolean vector
173     * @return this object (facilitates operation chaining)
174     * @throws UnsupportedOperationException
175     *         if this object's value cannot be changed
176     * @throws IllegalArgumentException
177     *         if the new value was incommensurate with this object's
178     *         specification
179     * @throws ArithmeticException
180     *         the new numeric value was incompatible with with algebraic
181     *         interpretation of this object
182     */
183    public PRIMITIVE orOfPrimitive( final SealedPrimitive<?> aValue )
184        throws UnsupportedOperationException,
185            IllegalArgumentException,
186            ArithmeticException;
187
188    /**
189     * Set this value to the current value, <i>x</i>, raised to the specified
190     * exponent, <i>n</i>, or <i>x<sup>n</sup></i>
191     *
192     * @param aValue
193     *        an exponent
194     * @return this object (facilitates operation chaining)
195     * @throws UnsupportedOperationException
196     *         if this object's value cannot be changed
197     * @throws IllegalArgumentException
198     *         if the new value was incommensurate with this object's
199     *         specification
200     * @throws ArithmeticException
201     *         the new numeric value was incompatible with with algebraic
202     *         interpretation of this object
203     */
204    public PRIMITIVE powerOfPrimitive( final SealedPrimitive<?> aValue )
205        throws UnsupportedOperationException,
206            IllegalArgumentException,
207            ArithmeticException;
208
209    /**
210     * Set the value of this scalar to the <i>mathematical</i> product of its
211     * current value and the specified value.
212     *
213     * @param aValue
214     *        a multiplicand
215     * @return this object (facilitates operation chaining)
216     * @throws UnsupportedOperationException
217     *         if this object's value cannot be changed
218     * @throws IllegalArgumentException
219     *         if the new value was incommensurate with this object's
220     *         specification
221     * @throws ArithmeticException
222     *         the new numeric value was incompatible with with algebraic
223     *         interpretation of this object
224     */
225    public PRIMITIVE productOfPrimitive( final SealedPrimitive<?> aValue )
226        throws UnsupportedOperationException,
227            IllegalArgumentException,
228            ArithmeticException;
229
230    /**
231     * Set the value of this scalar to the <i>mathematical</i> quotient between
232     * its current value and the specified value.
233     *
234     * @param aValue
235     *        a divisor
236     * @return this object (facilitates operation chaining)
237     * @throws UnsupportedOperationException
238     *         if this object's value cannot be changed
239     * @throws IllegalArgumentException
240     *         if the new value was incommensurate with this object's
241     *         specification
242     * @throws ArithmeticException
243     *         the new numeric value was incompatible with with algebraic
244     *         interpretation of this object
245     */
246    public PRIMITIVE quotientOfPrimitive( final SealedPrimitive<?> aValue )
247        throws UnsupportedOperationException,
248            IllegalArgumentException,
249            ArithmeticException;
250
251    /**
252     * Set this property to the specified system-supported {@link Boolean} and
253     * answer this object (facilitates chaining)
254     *
255     * @param aValue
256     *        a system-supported {@link Boolean}
257     * @return this object (facilitates operation chaining)
258     * @throws UnsupportedOperationException
259     *         if this object's value cannot be changed
260     * @throws IllegalArgumentException
261     *         if the specified value was incommensurate with this object's
262     *         specification
263     * @throws ArithmeticException
264     *         the numeric value provided was incompatible with with algebraic
265     *         interpretation of this object
266     * @throws NullPointerException
267     *         a {@code null} value was provided though this object does not
268     *         accept {@code null} values
269     */
270    public PRIMITIVE setBoolean( final Boolean aValue )
271        throws UnsupportedOperationException,
272            IllegalArgumentException,
273            ArithmeticException,
274            NullPointerException;
275
276    /**
277     * Set this property to the specified system-supported {@link Character} and
278     * answer this object (facilitates chaining)
279     *
280     * @param aValue
281     *        a system-supported {@link Character}
282     * @return this object (facilitates operation chaining)
283     * @throws UnsupportedOperationException
284     *         if this object's value cannot be changed
285     * @throws IllegalArgumentException
286     *         if the specified value was incommensurate with this object's
287     *         specification
288     * @throws ArithmeticException
289     *         the numeric value provided was incompatible with with algebraic
290     *         interpretation of this object
291     * @throws NullPointerException
292     *         a {@code null} value was provided though this object does not
293     *         accept {@code null} values
294     */
295    public PRIMITIVE setCharacter( final Character aValue )
296        throws UnsupportedOperationException,
297            IllegalArgumentException,
298            ArithmeticException,
299            NullPointerException;
300
301    /**
302     * Set this property to the specified primitive
303     *
304     * @param aValue
305     *        a primitive
306     * @return this object (facilitates operation chaining)
307     * @throws UnsupportedOperationException
308     *         if this object's value cannot be changed
309     * @throws IllegalArgumentException
310     *         if the specified value was incommensurate with this object's
311     *         specification
312     * @throws ArithmeticException
313     *         the numeric value provided was incompatible with with algebraic
314     *         interpretation of this object
315     * @throws NullPointerException
316     *         a {@code null} value was provided though this object does not
317     *         accept {@code null} values
318     */
319    public PRIMITIVE setPrimitive( final SealedPrimitive<?> aValue )
320        throws UnsupportedOperationException,
321            IllegalArgumentException,
322            ArithmeticException,
323            NullPointerException;
324
325    /**
326     * Set the value of this scalar to the <i>mathematical</i> sum of its
327     * current value and the specified value.
328     *
329     * @param aValue
330     *        an addend
331     * @return this object (facilitates operation chaining)
332     * @throws UnsupportedOperationException
333     *         if this object's value cannot be changed
334     * @throws IllegalArgumentException
335     *         if the new value was incommensurate with this object's
336     *         specification
337     * @throws ArithmeticException
338     *         the new numeric value was incompatible with with algebraic
339     *         interpretation of this object
340     */
341    public PRIMITIVE sumOfPrimitive( final SealedPrimitive<?> aValue )
342        throws UnsupportedOperationException,
343            IllegalArgumentException,
344            ArithmeticException;
345
346    /**
347     * Set this value to the bit <b>exclusive-or</b> of the <i>integral</i>
348     * boolean vector equivalent of this value and the specified integral
349     * boolean vector
350     *
351     * @param aValue
352     *        an integral boolean vector
353     * @return this object (facilitates operation chaining)
354     * @throws UnsupportedOperationException
355     *         if this object's value cannot be changed
356     * @throws IllegalArgumentException
357     *         if the new value was incommensurate with this object's
358     *         specification
359     * @throws ArithmeticException
360     *         the new numeric value was incompatible with with algebraic
361     *         interpretation of this object
362     */
363    public PRIMITIVE xorOfPrimitive( final SealedPrimitive<?> aValue )
364        throws UnsupportedOperationException,
365            IllegalArgumentException,
366            ArithmeticException;
367}