001/**
002 * The MIT License (MIT)
003 *
004 * Copyright (c) 2015-2016 decimal4j (tools4j), Marco Terzer
005 *
006 * Permission is hereby granted, free of charge, to any person obtaining a copy
007 * of this software and associated documentation files (the "Software"), to deal
008 * in the Software without restriction, including without limitation the rights
009 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
010 * copies of the Software, and to permit persons to whom the Software is
011 * furnished to do so, subject to the following conditions:
012 *
013 * The above copyright notice and this permission notice shall be included in all
014 * copies or substantial portions of the Software.
015 *
016 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
017 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
018 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
019 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
020 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
021 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
022 * SOFTWARE.
023 */
024package org.decimal4j.api;
025
026import java.math.BigDecimal;
027import java.math.BigInteger;
028import java.math.RoundingMode;
029
030import org.decimal4j.factory.DecimalFactory;
031import org.decimal4j.scale.ScaleMetrics;
032import org.decimal4j.truncate.OverflowMode;
033import org.decimal4j.truncate.TruncationPolicy;
034
035/**
036 * Signed fixed-point decimal number similar to {@link BigDecimal}. A Decimal number can be immutable or mutable and it
037 * is based on an underlying <i>unscaled</i> long value and a fixed {@link #getScale() scale}. The scale defines the
038 * number of digits to the right of the decimal point. If the scale is {@code f} then the value represented by a
039 * {@code Decimal} instance is <tt>(unscaledValue &times; 10<sup>-f</sup>)</tt>.
040 * <p>
041 * <i>Scale of Result and Operands</i> <br>
042 * The result of an arithmetic operation is generally of the same scale as this Decimal unless otherwise indicated.
043 * Decimal operands of arithmetic operations are typically also of the same scale as this Decimal. Scale compatibility
044 * of Decimal operands is enforced through the generic {@link ScaleMetrics} parameter {@code <S>}.
045 * <p>
046 * <i>Operands involving Type Conversion</i> <br>
047 * For convenience, arithmetic operations with other data types are sometimes also provided. Such operations usually
048 * perform a value conversion into a Decimal of the current scale before performing the actual operation.
049 * <p>
050 * <i>Rounding</i> <br>
051 * If the result of an arithmetic operation cannot be represented exactly in the scale of this Decimal, it is rounded to
052 * the least significant digit. {@link RoundingMode#HALF_UP HALF_UP} rounding is used by default if no other rounding
053 * mode is explicitly specified. Note that in a few exceptional cases {@link RoundingMode#HALF_EVEN HALF_EVEN} rounding
054 * is used by default to comply with inherited specification constraints (e.g. see {@link #doubleValue()},
055 * {@link #floatValue()} etc.). The documentation of operations which involve rounding indicate the rounding mode that
056 * is applied.
057 * <p>
058 * <i>Overflows</i> <br>
059 * Operations with Decimal values can lead to overflows in marked contrast to the {@link BigDecimal}. This is a direct
060 * consequence of the construction of a Decimal value on the basis of a long value. Unless otherwise indicated
061 * operations silently truncate overflows by default. This choice has been made for performance reasons and because Java
062 * programmers are already familiar with this behavior from operations with primitive integer types. If this behavior is
063 * inappropriate for an application, exceptions in overflow situations can be enforced through an optional
064 * {@link OverflowMode} or {@link TruncationPolicy} argument. Some operations like conversion operations or arithmetic
065 * operations involving conversion <i>always</i> throw an exception if an overflow occurs. The documentation of
066 * operations which can cause an overflow always indicates the exact overflow behavior.
067 * <p>
068 * All methods for this interface throw {@code NullPointerException} when passed a {@code null} object reference for any
069 * input parameter.
070 * 
071 * @param <S>
072 *            the scale metrics type associated with this Decimal
073 */
074public interface Decimal<S extends ScaleMetrics> extends Comparable<Decimal<S>> {
075
076        /**
077         * Returns the metrics associated with the scale of this Decimal. Scale defines the number of fraction digits and
078         * the scale factor applied to the {@code long} value underlying this {@code Decimal}.
079         * 
080         * @return the scale metrics object
081         * @see ScaleMetrics#getScale()
082         * @see ScaleMetrics#getScaleFactor()
083         */
084        S getScaleMetrics();
085
086        /**
087         * Returns the scale associated with this Decimal. The scale defines the number of fraction digits and the scale
088         * factor applied to the {@code long} value underlying this {@code Decimal}.
089         * <p>
090         * If the scale is {@code f} then the value represented by a {@code Decimal} instance is
091         * <tt>(unscaledValue &times; 10<sup>-f</sup>)</tt>.
092         * <p>
093         * This method is a shortcut for {@code getScaleMetrics().getScale()}.
094         * 
095         * @return the scale
096         * @see #getScaleMetrics()
097         * @see ScaleMetrics#getScale()
098         * @see #unscaledValue()
099         */
100        int getScale();
101
102        /**
103         * Returns the unscaled value underlying this {@code Decimal}. This {@code Decimal} is
104         * <tt>(unscaledValue &times; 10<sup>-f</sup>)</tt> with {@code f} representing the {@link #getScale() scale}, hence
105         * the returned value equals <tt>(10<sup>f</sup> &times; this)</tt>.
106         * 
107         * @return the unscaled numeric value, the same as this Decimal but without applying the scale factor
108         * @see #getScale()
109         * @see ScaleMetrics#getScaleFactor()
110         */
111        long unscaledValue();
112
113        /**
114         * Returns the factory that can be used to create other Decimal values of the same scale as {@code this} Decimal.
115         * 
116         * @return the factory to create other Decimal values of the same scale as this Decimal
117         */
118        DecimalFactory<S> getFactory();
119
120        /**
121         * Returns a {@code Decimal} whose value represents the integral part of {@code this} Decimal. The integral part
122         * corresponds to digits at the left of the decimal point. The result is {@code this} Decimal rounded to precision
123         * zero with {@link RoundingMode#DOWN}.
124         * <p>
125         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
126         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
127         * the outcome of the operation.
128         * 
129         * @return <code>&lfloor;this&rfloor;</code> for non-negative and <code>&lceil;this&rceil;</code> for negative
130         *         values
131         * @see #fractionalPart()
132         * @see #isIntegral()
133         * @see #isIntegralPartZero()
134         * @see #round(int, RoundingMode)
135         */
136        Decimal<S> integralPart();
137
138        /**
139         * Returns a {@code Decimal} whose value represents the fractional part of {@code (this)} value. The fractional part
140         * corresponds to digits at the right of the decimal point. The result is {@code this} minus the integral part of
141         * this Decimal.
142         * <p>
143         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
144         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
145         * the outcome of the operation.
146         * 
147         * @return {@code this-integralPart()} which is always less than one and greater than minus one
148         * @see #integralPart()
149         * @see #isIntegral()
150         * @see #isIntegralPartZero()
151         */
152        Decimal<S> fractionalPart();
153
154        // some methods "inherited" from Number and BigDecimal
155
156        /**
157         * Returns the value of this {@code Decimal} as a {@code byte} after a narrowing primitive conversion.
158         * 
159         * @return this {@code Decimal} converted to an {@code byte}.
160         * @see Number#byteValue()
161         * @see #byteValueExact()
162         */
163        byte byteValue();
164
165        /**
166         * Converts this {@code Decimal} to a {@code byte}, checking for lost information. If this {@code Decimal} has a
167         * nonzero fractional part or is out of the possible range for a {@code byte} result then an
168         * {@code ArithmeticException} is thrown.
169         *
170         * @return this {@code Decimal} converted to a {@code byte}.
171         * @throws ArithmeticException
172         *             if {@code this} has a nonzero fractional part, or will not fit in a {@code byte}.
173         * @see #byteValue()
174         */
175        byte byteValueExact();
176
177        /**
178         * Returns the value of this {@code Decimal} as a {@code short} after a narrowing primitive conversion.
179         * 
180         * @return this {@code Decimal} converted to an {@code short}.
181         * @see Number#shortValue()
182         * @see #shortValueExact()
183         */
184        short shortValue();
185
186        /**
187         * Converts this {@code Decimal} to a {@code short}, checking for lost information. If this {@code Decimal} has a
188         * nonzero fractional part or is out of the possible range for a {@code short} result then an
189         * {@code ArithmeticException} is thrown.
190         *
191         * @return this {@code Decimal} converted to a {@code short}.
192         * @throws ArithmeticException
193         *             if {@code this} has a nonzero fractional part, or will not fit in a {@code short}.
194         * @see #shortValue()
195         */
196        short shortValueExact();
197
198        /**
199         * Converts this {@code Decimal} to an {@code int}. This conversion is analogous to the <i>narrowing primitive
200         * conversion</i> from {@code double} to {@code short} as defined in section 5.1.3 of <cite>The Java&trade; Language
201         * Specification</cite>: any fractional part of this {@code Decimal} will be discarded, and if the resulting
202         * "{@code long}" is too big to fit in an {@code int}, only the low-order 32 bits are returned. Note that this
203         * conversion can lose information about the overall magnitude and precision of this {@code Decimal} value as well
204         * as return a result with the opposite sign.
205         *
206         * @return this {@code Decimal} converted to an {@code int}.
207         * @see Number#intValue()
208         * @see #intValueExact()
209         */
210        int intValue();
211
212        /**
213         * Converts this {@code Decimal} to an {@code int}, checking for lost information. If this {@code Decimal} has a
214         * nonzero fractional part or is out of the possible range for an {@code int} result then an
215         * {@code ArithmeticException} is thrown.
216         *
217         * @return this {@code Decimal} converted to an {@code int}.
218         * @throws ArithmeticException
219         *             if {@code this} has a nonzero fractional part, or will not fit in an {@code int}.
220         * @see #intValue()
221         */
222        int intValueExact();
223
224        /**
225         * Converts this {@code Decimal} to a {@code long}. This conversion is analogous to the <i>narrowing primitive
226         * conversion</i> from {@code double} to {@code short} as defined in section 5.1.3 of <cite>The Java&trade; Language
227         * Specification</cite>: any fractional part of this {@code Decimal} will be discarded. Note that this conversion
228         * can lose information about the precision of the {@code Decimal} value.
229         * <p>
230         * Note that this method uses {@link RoundingMode#DOWN} as defined by <cite>The Java&trade;Language
231         * Specification</cite>. Other rounding modes are supported via {@link #longValue(RoundingMode)}.
232         *
233         * @return this {@code Decimal} converted to a {@code long}.
234         * @see Number#longValue()
235         * @see #longValue(RoundingMode)
236         * @see #longValueExact()
237         */
238        long longValue();
239
240        /**
241         * Converts this {@code Decimal} to a {@code long}, checking for lost information. If this {@code Decimal} has a
242         * nonzero fractional part or is out of the possible range for a {@code long} result then an
243         * {@code ArithmeticException} is thrown.
244         *
245         * @return this {@code Decimal} converted to a {@code long}.
246         * @throws ArithmeticException
247         *             if {@code this} has a nonzero fractional part
248         * @see #longValue()
249         * @see #longValue(RoundingMode)
250         */
251        long longValueExact();
252
253        /**
254         * Converts this {@code Decimal} to a {@code float}. This conversion is similar to the <i>narrowing primitive
255         * conversion</i> from {@code double} to {@code float} as defined in section 5.1.3 of <cite>The Java&trade; Language
256         * Specification</cite>. Note that this conversion can lose information about the precision of the {@code Decimal}
257         * value.
258         * <p>
259         * Note that this method uses {@link RoundingMode#HALF_EVEN} as defined by <cite>The Java&trade;Language
260         * Specification</cite>. Other rounding modes are supported via {@link #floatValue(RoundingMode)}.
261         *
262         * @return this {@code Decimal} converted to a {@code float}.
263         * @see Number#floatValue()
264         * @see #floatValue(RoundingMode)
265         */
266        float floatValue();
267
268        /**
269         * Converts this {@code Decimal} to a {@code double}. This conversion is similar to the <i>narrowing primitive
270         * conversion</i> from {@code double} to {@code float} as defined in section 5.1.3 of <cite>The Java&trade; Language
271         * Specification</cite>. Note that this conversion can lose information about the precision of the {@code Decimal}
272         * value.
273         * <p>
274         * Note that this method uses {@link RoundingMode#HALF_EVEN} as defined by <cite>The Java&trade;Language
275         * Specification</cite>. Other rounding modes are supported via {@link #doubleValue(RoundingMode)}.
276         *
277         * @return this {@code Decimal} converted to a {@code double}.
278         * @see Number#doubleValue()
279         * @see #doubleValue(RoundingMode)
280         */
281        double doubleValue();
282
283        /**
284         * Converts this {@code Decimal} to a {@code BigInteger}. This conversion is analogous to the <i>narrowing primitive
285         * conversion</i> from {@code double} to {@code long} as defined in section 5.1.3 of <cite>The Java&trade; Language
286         * Specification</cite>: any fractional part of this {@code Decimal} will be discarded. Note that this conversion
287         * can lose information about the precision of the {@code Decimal} value.
288         * <p>
289         * To have an exception thrown if the conversion is inexact (in other words if a nonzero fractional part is
290         * discarded), use the {@link #toBigIntegerExact()} method.
291         * <p>
292         * Note that this method uses {@link RoundingMode#DOWN} to be consistent with other integer conversion methods as
293         * defined by <cite>The Java&trade;Language Specification</cite>. Other rounding modes are supported via
294         * {@link #toBigInteger(RoundingMode)}.
295         *
296         * @return this {@code Decimal} converted to a {@code BigInteger}.
297         * @see #toBigIntegerExact()
298         * @see #toBigInteger(RoundingMode)
299         * @see #longValue()
300         */
301        BigInteger toBigInteger();
302
303        /**
304         * Converts this {@code Decimal} to a {@code BigInteger}, checking for lost information. An exception is thrown if
305         * this {@code Decimal} has a nonzero fractional part.
306         *
307         * @return this {@code Decimal} converted to a {@code BigInteger}.
308         * @throws ArithmeticException
309         *             if {@code this} has a nonzero fractional part.
310         * @see #toBigInteger()
311         * @see #toBigInteger(RoundingMode)
312         * @see #longValueExact()
313         */
314        BigInteger toBigIntegerExact();
315
316        /**
317         * Converts this {@code Decimal} to a {@code BigDecimal} using the same {@link #getScale() scale} as this Decimal
318         * value.
319         *
320         * @return this {@code Decimal} converted to a {@code BigDecimal} with the same scale as this Decimal value.
321         * @see #toBigDecimal(int, RoundingMode)
322         */
323        BigDecimal toBigDecimal();
324
325        // mutable/immutable conversion methods
326
327        /**
328         * If this {@code Decimal} value is already an {@link ImmutableDecimal} it is simply returned. Otherwise a new
329         * immutable value with the same scale and numerical value as {@code this} Decimal is created and returned.
330         * 
331         * @return {@code this} if immutable and a new {@link ImmutableDecimal} with the same scale and value as
332         *         {@code this} Decimal otherwise
333         */
334        ImmutableDecimal<S> toImmutableDecimal();
335
336        /**
337         * If this {@code Decimal} value is already a {@link MutableDecimal} it is simply returned. Otherwise a new mutable
338         * value with the same scale and numerical value as {@code this} Decimal is created and returned.
339         * 
340         * @return {@code this} if mutable and a new {@link MutableDecimal} with the same scale and value as {@code this}
341         *         Decimal otherwise
342         */
343        MutableDecimal<S> toMutableDecimal();
344
345        // some conversion methods with rounding mode
346
347        /**
348         * Converts this {@code Decimal} to a {@code long} using the specified rounding mode if necessary. Rounding is
349         * applied if the Decimal value can not be represented as a long value, that is, if it has a nonzero fractional
350         * part. Note that this conversion can lose information about the precision of the {@code Decimal} value.
351         * 
352         * @param roundingMode
353         *            the rounding mode to apply when rounding is necessary to convert this Decimal into a long
354         * @return this {@code Decimal} converted to a {@code long}.
355         * @throws ArithmeticException
356         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
357         * @see #longValue()
358         * @see #longValueExact()
359         */
360        long longValue(RoundingMode roundingMode);
361
362        /**
363         * Converts this {@code Decimal} to a {@code float} using the specified rounding mode if the Decimal value can not
364         * be exactly represented as a float value. Note that this conversion can lose information about the precision of
365         * the {@code Decimal} value.
366         *
367         * @param roundingMode
368         *            the rounding mode to apply when rounding is necessary to convert this Decimal into a float value
369         * @return this {@code Decimal} converted to a {@code float}.
370         * @throws ArithmeticException
371         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
372         * @see #floatValue()
373         */
374        float floatValue(RoundingMode roundingMode);
375
376        /**
377         * Converts this {@code Decimal} to a {@code double} using the specified rounding mode if the Decimal value can not
378         * be exactly represented as a double value. Note that this conversion can lose information about the precision of
379         * the {@code Decimal} value.
380         *
381         * @param roundingMode
382         *            the rounding mode to apply when rounding is necessary to convert this Decimal into a double value
383         * @return this {@code Decimal} converted to a {@code double}.
384         * @throws ArithmeticException
385         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
386         * @see #doubleValue()
387         */
388        double doubleValue(RoundingMode roundingMode);
389
390        /**
391         * Converts this {@code Decimal} to a {@link BigInteger} value using the specified rounding mode if necessary.
392         * Rounding is applied if the Decimal value can not be represented as a {@code BigInteger}, that is, if it has a
393         * nonzero fractional part. Note that this conversion can lose information about the precision of the
394         * {@code Decimal} value.
395         * 
396         * @param roundingMode
397         *            the rounding mode to apply when rounding is necessary to convert this Decimal into a
398         *            {@code BigInteger}
399         * @return this {@code Decimal} converted to a {@code BigInteger}.
400         * @throws ArithmeticException
401         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
402         * @see #toBigInteger()
403         * @see #toBigIntegerExact()
404         */
405        BigInteger toBigInteger(RoundingMode roundingMode);
406
407        /**
408         * Returns a {@code BigDecimal} value of the given scale using the specified rounding mode if necessary.
409         * 
410         * @param scale
411         *            the scale used for the returned {@code BigDecimal}
412         * @param roundingMode
413         *            the rounding mode to apply when rounding is necessary to convert from the this Decimal's
414         *            {@link #getScale() scale} to the target scale
415         * @return a {@code BigDecimal} instance of the specified scale
416         * @throws ArithmeticException
417         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
418         * @see #toBigDecimal()
419         */
420        BigDecimal toBigDecimal(int scale, RoundingMode roundingMode);
421
422        // methods to round and change the scale
423
424        /**
425         * Returns a {@code Decimal} value rounded to the specified {@code precision} using {@link RoundingMode#HALF_UP
426         * HALF_UP} rounding. If an overflow occurs due to the rounding operation, the result is silently truncated.
427         * <p>
428         * Note that contrary to the {@code scale(..)} operations this method does not change the scale of the value ---
429         * extra digits are simply zeroised.
430         * <p>
431         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
432         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
433         * the rounded value.
434         * <p>
435         * <i>Examples and special cases:</i>
436         * <ul>
437         * <li><b>precision = 0</b><br>
438         * value is rounded to an integer value</li>
439         * <li><b>precision = 2</b><br>
440         * value is rounded to the second digit after the decimal point</li>
441         * <li><b>precision = -3</b><br>
442         * value is rounded to the thousands</li>
443         * <li><b>precision &ge; scale</b><br>
444         * values is returned unchanged</li>
445         * <li><b>precision &lt; scale - 18</b><br>
446         * {@code IllegalArgumentException} is thrown</li>
447         * </ul>
448         * 
449         * @param precision
450         *            the precision to use for the rounding, for instance 2 to round to the second digit after the decimal
451         *            point; must be at least {@code (scale - 18)}
452         * @return a Decimal instance rounded to the given precision
453         * @throws IllegalArgumentException
454         *             if {@code precision < scale - 18}
455         * @see #round(int, RoundingMode)
456         * @see #round(int, TruncationPolicy)
457         * @see #scale(int)
458         */
459        Decimal<S> round(int precision);
460
461        /**
462         * Returns a {@code Decimal} value rounded to the specified {@code precision} using the given rounding mode. If an
463         * overflow occurs due to the rounding operation, the result is silently truncated.
464         * <p>
465         * Note that contrary to the {@code scale(..)} operations this method does not change the scale of the value ---
466         * extra digits are simply zeroised.
467         * <p>
468         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
469         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
470         * the rounded value.
471         * <p>
472         * <i>Examples and special cases:</i>
473         * <ul>
474         * <li><b>precision = 0</b><br>
475         * value is rounded to an integer value</li>
476         * <li><b>precision = 2</b><br>
477         * value is rounded to the second digit after the decimal point</li>
478         * <li><b>precision = -3</b><br>
479         * value is rounded to the thousands</li>
480         * <li><b>precision &ge; scale</b><br>
481         * values is returned unchanged</li>
482         * <li><b>precision &lt; scale - 18</b><br>
483         * {@code IllegalArgumentException} is thrown</li>
484         * </ul>
485         * 
486         * @param precision
487         *            the precision to use for the rounding, for instance 2 to round to the second digit after the decimal
488         *            point; must be at least {@code (scale - 18)}
489         * @param roundingMode
490         *            the rounding mode to apply when rounding to the desired precision
491         * @return a Decimal instance rounded to the given precision
492         * @throws IllegalArgumentException
493         *             if {@code precision < scale - 18}
494         * @throws ArithmeticException
495         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
496         * @see #round(int)
497         * @see #round(int, TruncationPolicy)
498         * @see #scale(int, RoundingMode)
499         */
500        Decimal<S> round(int precision, RoundingMode roundingMode);
501
502        /**
503         * Returns a {@code Decimal} value rounded to the specified {@code precision} using the given truncation policy.
504         * <p>
505         * Note that contrary to the {@code scale(..)} operations this method does not change the scale of the value ---
506         * extra digits are simply zeroised.
507         * <p>
508         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
509         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
510         * the rounded value.
511         * <p>
512         * <i>Examples and special cases:</i>
513         * <ul>
514         * <li><b>precision = 0</b><br>
515         * value is rounded to an integer value</li>
516         * <li><b>precision = 2</b><br>
517         * value is rounded to the second digit after the decimal point</li>
518         * <li><b>precision = -3</b><br>
519         * value is rounded to the thousands</li>
520         * <li><b>precision &ge; scale</b><br>
521         * values is returned unchanged</li>
522         * <li><b>precision &lt; scale - 18</b><br>
523         * {@code IllegalArgumentException} is thrown</li>
524         * </ul>
525         * 
526         * @param precision
527         *            the precision to use for the rounding, for instance 2 to round to the second digit after the decimal
528         *            point; must be at least {@code (scale - 18)}
529         * @param truncationPolicy
530         *            the truncation policy defining {@link RoundingMode} and {@link OverflowMode} for the rounding
531         *            operation
532         * @return a Decimal instance rounded to the given precision
533         * @throws IllegalArgumentException
534         *             if {@code precision < scale - 18}
535         * @throws ArithmeticException
536         *             if {@code truncationPolicy} specifies {@link RoundingMode#UNNECESSARY} and rounding is necessary or
537         *             if an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
538         * @see #round(int)
539         * @see #round(int, RoundingMode)
540         * @see #scale(int, RoundingMode)
541         */
542        Decimal<S> round(int precision, TruncationPolicy truncationPolicy);
543
544        /**
545         * Returns a {@code Decimal} value whose {@link #getScale() scale} is changed to the given {@code scale} value.
546         * {@link RoundingMode#HALF_UP HALF_UP} rounding is used if the scale change involves rounding.
547         * <p>
548         * An exception is thrown if the scale conversion leads to an overflow.
549         * 
550         * @param scale
551         *            the scale to use for the result, must be in {@code [0,18]}
552         * @return a Decimal instance with the given new scale
553         * @throws IllegalArgumentException
554         *             if {@code scale < 0} or {@code scale > 18}
555         * @throws ArithmeticException
556         *             if an overflow occurs during the scale conversion
557         * @see #scale(ScaleMetrics)
558         * @see #scale(int, RoundingMode)
559         * @see #round(int)
560         */
561        Decimal<?> scale(int scale);
562
563        /**
564         * Returns a {@code Decimal} value whose {@link #getScale() scale} is changed to the scale given by the
565         * {@code scaleMetrics} argument. {@link RoundingMode#HALF_UP HALF_UP} rounding is used if the scale change involves
566         * rounding.
567         * <p>
568         * An exception is thrown if the scale conversion leads to an overflow.
569         * 
570         * @param <S>
571         *            the scale metrics type of the result
572         * @param scaleMetrics
573         *            the scale metrics to use for the result
574         * @return a Decimal instance with the given new scale metrics
575         * @throws ArithmeticException
576         *             if an overflow occurs during the scale conversion
577         * @see #scale(int)
578         * @see #scale(ScaleMetrics, RoundingMode)
579         * @see #round(int)
580         */
581        @SuppressWarnings("hiding")
582        <S extends ScaleMetrics> Decimal<S> scale(S scaleMetrics);
583
584        /**
585         * Returns a {@code Decimal} value whose {@link #getScale() scale} is changed to the given {@code scale} value. The
586         * specified {@code roundingMode} is used if the scale change involves rounding.
587         * <p>
588         * An exception is thrown if the scale conversion leads to an overflow.
589         * 
590         * @param scale
591         *            the scale to use for the result, must be in {@code [0,18]}
592         * @param roundingMode
593         *            the rounding mode to apply if the scale change involves rounding
594         * @return a Decimal instance with the given new scale
595         * @throws IllegalArgumentException
596         *             if {@code scale < 0} or {@code scale > 18}
597         * @throws ArithmeticException
598         *             if {@code roundingMode} is {@link RoundingMode#UNNECESSARY UNNESSESSARY} and rounding is necessary,
599         *             or if an overflow occurs during the scale conversion
600         * @see #scale(int)
601         * @see #scale(ScaleMetrics, RoundingMode)
602         * @see #round(int, RoundingMode)
603         */
604        Decimal<?> scale(int scale, RoundingMode roundingMode);
605
606        /**
607         * Returns a {@code Decimal} value whose {@link #getScale() scale} is changed to the scale given by the
608         * {@code scaleMetrics} argument. The specified {@code roundingMode} is used if the scale change involves rounding.
609         * <p>
610         * An exception is thrown if the scale conversion leads to an overflow.
611         * 
612         * @param <S>
613         *            the scale metrics type of the result
614         * @param scaleMetrics
615         *            the scale metrics to use for the result
616         * @param roundingMode
617         *            the rounding mode to apply if the scale change involves rounding
618         * @return a Decimal instance with the given new scale metrics
619         * @throws ArithmeticException
620         *             if {@code roundingMode} is {@link RoundingMode#UNNECESSARY UNNESSESSARY} and rounding is necessary,
621         *             or if an overflow occurs during the scale conversion
622         * @see #scale(ScaleMetrics)
623         * @see #scale(int, RoundingMode)
624         * @see #round(int, RoundingMode)
625         */
626        @SuppressWarnings("hiding")
627        <S extends ScaleMetrics> Decimal<S> scale(S scaleMetrics, RoundingMode roundingMode);
628
629        // add
630
631        /**
632         * Returns a {@code Decimal} whose value is {@code (this + augend)}. If the addition causes an overflow, the result
633         * is silently truncated.
634         * <p>
635         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
636         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
637         * the outcome of the addition.
638         * 
639         * @param augend
640         *            value to be added to this {@code Decimal}
641         * @return {@code this + augend}
642         */
643        Decimal<S> add(Decimal<S> augend);
644
645        /**
646         * Returns a {@code Decimal} whose value is {@code (this + augend)}. The specified {@code overflowMode} determines
647         * whether to truncate the result silently or to throw an exception if an overflow occurs.
648         * <p>
649         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
650         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
651         * the outcome of the addition.
652         * 
653         * @param augend
654         *            value to be added to this {@code Decimal}
655         * @param overflowMode
656         *            the overflow mode to apply if the addition leads to an overflow
657         * @return {@code this + augend}
658         * @throws ArithmeticException
659         *             if {@code overflowMode==CHECKED} and an overflow occurs
660         */
661        Decimal<S> add(Decimal<S> augend, OverflowMode overflowMode);
662
663        /**
664         * Returns a {@code Decimal} whose value is {@code (this + augend)}. The result of the addition is rounded if
665         * necessary using the specified {@code roundingMode}. Overflows during scale conversion or subtraction are silently
666         * truncated.
667         * <p>
668         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
669         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
670         * the outcome of the addition.
671         * 
672         * @param augend
673         *            value to be added to this {@code Decimal}
674         * @param roundingMode
675         *            the rounding mode to apply if rounding is necessary
676         * @return <tt>round<sub>HALF_UP</sub>(this + augend)</tt>
677         * @throws ArithmeticException
678         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
679         */
680        Decimal<S> add(Decimal<?> augend, RoundingMode roundingMode);
681
682        /**
683         * Returns a {@code Decimal} whose value is {@code (this + augend)}. The result of the addition is rounded if
684         * necessary using the {@link RoundingMode} defined by the {@code truncationPolicy} argument. The
685         * {@code truncationPolicy} also defines the {@link OverflowMode} to apply if the operation causes an overflow.
686         * <p>
687         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
688         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
689         * the outcome of the addition.
690         * 
691         * @param augend
692         *            value to be added to this {@code Decimal}
693         * @param truncationPolicy
694         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
695         *            necessary or if an overflow occurs during the addition
696         * @return {@code round(this + augend)}
697         * @throws ArithmeticException
698         *             if {@code truncationPolicy} specifies {@link RoundingMode#UNNECESSARY} and rounding is necessary or
699         *             if an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
700         */
701        Decimal<S> add(Decimal<?> augend, TruncationPolicy truncationPolicy);
702
703        /**
704         * Returns a {@code Decimal} whose value is {@code (this + augend)} after converting the given {@code long} value to
705         * the scale of {@code this} Decimal. If the operation causes an overflow, the result is silently truncated.
706         * <p>
707         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
708         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
709         * the outcome of the addition.
710         * 
711         * @param augend
712         *            long value to be added to this {@code Decimal}
713         * @return {@code this + augend}
714         */
715        Decimal<S> add(long augend);
716
717        /**
718         * Returns a {@code Decimal} whose value is {@code (this + augend)} after converting the given {@code long} value to
719         * the scale of {@code this} Decimal. The specified {@code overflowMode} determines whether to truncate the result
720         * silently or to throw an exception if an overflow occurs.
721         * <p>
722         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
723         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
724         * the outcome of the addition.
725         * 
726         * @param augend
727         *            long value to be added to this {@code Decimal}
728         * @param overflowMode
729         *            the overflow mode to apply if the addition leads to an overflow
730         * @return {@code this + augend}
731         * @throws ArithmeticException
732         *             if {@code overflowMode==CHECKED} and an overflow occurs
733         */
734        Decimal<S> add(long augend, OverflowMode overflowMode);
735
736        /**
737         * Returns a {@code Decimal} whose value is {@code (this + augend)} after converting the given {@code double}
738         * argument into a Decimal value of the same scale as {@code this} Decimal. If rounding is necessary,
739         * {@link RoundingMode#HALF_UP HALF_UP} rounding mode is used and applied during the conversion step <i>before</i>
740         * the addition operation. Overflows due to conversion or addition result in an exception.
741         * <p>
742         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
743         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
744         * the outcome of the addition.
745         * 
746         * @param augend
747         *            value to be added to this {@code Decimal}
748         * @return <tt>this + round<sub>HALF_UP</sub>(augend)</tt>
749         * @throws IllegalArgumentException
750         *             if {@code augend} is NaN or infinite or if the magnitude is too large for the double to be
751         *             represented as a {@code Decimal}
752         * @throws ArithmeticException
753         *             if an overflow occurs during the addition operation
754         */
755        Decimal<S> add(double augend);
756
757        /**
758         * Returns a {@code Decimal} whose value is {@code (this + augend)} after converting the given {@code double}
759         * argument into a Decimal value of the same scale as {@code this} Decimal. If rounding is necessary, the specified
760         * {@code roundingMode} is used and applied during the conversion step <i>before</i> the addition operation.
761         * Overflows due to conversion or addition result in an exception.
762         * <p>
763         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
764         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
765         * the outcome of the addition.
766         * 
767         * @param augend
768         *            value to be added to this {@code Decimal}
769         * @param roundingMode
770         *            the rounding mode to apply if the augend argument needs to be rounded when converted into a Decimal
771         *            number of the same scale as {@code this} Decimal
772         * @return {@code this + round(augend)}
773         * @throws IllegalArgumentException
774         *             if {@code augend} is NaN or infinite or if the magnitude is too large for the double to be
775         *             represented as a {@code Decimal}
776         * @throws ArithmeticException
777         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary or if an overflow occurs during the
778         *             addition operation
779         */
780        Decimal<S> add(double augend, RoundingMode roundingMode);
781
782        /**
783         * Returns a {@code Decimal} whose value is <tt>(this + unscaledAugend &times; 10<sup>-scale</sup>)</tt> with the
784         * {@link #getScale() scale} of this Decimal. If the addition causes an overflow, the result is silently truncated.
785         * <p>
786         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
787         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
788         * the outcome of the addition.
789         * 
790         * @param unscaledAugend
791         *            value to be added to this {@code Decimal}
792         * @return <tt>round<sub>HALF_UP</sub>(this + unscaledAugend &times; 10<sup>-scale</sup>)</tt>
793         */
794        Decimal<S> addUnscaled(long unscaledAugend);
795
796        /**
797         * Returns a {@code Decimal} whose value is <tt>(this + unscaledAugend &times; 10<sup>-scale</sup>)</tt> with the
798         * {@link #getScale() scale} of this Decimal. The specified {@code overflowMode} determines whether to truncate the
799         * result silently or to throw an exception if an overflow occurs.
800         * <p>
801         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
802         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
803         * the outcome of the addition.
804         * 
805         * @param unscaledAugend
806         *            value to be added to this {@code Decimal}
807         * @param overflowMode
808         *            the overflow mode to apply if the addition leads to an overflow
809         * @return <tt>round(this + unscaledAugend &times; 10<sup>-scale</sup>)</tt>
810         * @throws ArithmeticException
811         *             if {@code overflowMode==CHECKED} and an overflow occurs
812         */
813        Decimal<S> addUnscaled(long unscaledAugend, OverflowMode overflowMode);
814
815        /**
816         * Returns a {@code Decimal} whose value is <tt>(this + unscaledAugend &times; 10<sup>-scale</sup>)</tt>. The result
817         * of the addition is rounded if necessary using {@link RoundingMode#HALF_UP HALF_UP} rounding. If the operation
818         * causes an overflow, the result is silently truncated.
819         * <p>
820         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
821         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
822         * the outcome of the addition.
823         * 
824         * @param unscaledAugend
825         *            value to be added to this {@code Decimal}
826         * @param scale
827         *            the scale to apply to {@code unscaledAugend}, positive to indicate the number of fraction digits to
828         *            the right of the Decimal point and negative to indicate up-scaling with a power of ten
829         * @return <tt>round<sub>HALF_UP</sub>(this + unscaledAugend &times; 10<sup>-scale</sup>)</tt>
830         */
831        Decimal<S> addUnscaled(long unscaledAugend, int scale);
832
833        /**
834         * Returns a {@code Decimal} whose value is <tt>(this + unscaledAugend &times; 10<sup>-scale</sup>)</tt>. The result
835         * of the addition is rounded if necessary using the specified {@code roundingMode}. If the operation causes an
836         * overflow, the result is silently truncated.
837         * <p>
838         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
839         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
840         * the outcome of the addition.
841         * 
842         * @param unscaledAugend
843         *            value to be added to this {@code Decimal}
844         * @param scale
845         *            the scale to apply to {@code unscaledAugend}, positive to indicate the number of fraction digits to
846         *            the right of the Decimal point and negative to indicate up-scaling with a power of ten
847         * @param roundingMode
848         *            the rounding mode to apply if rounding is necessary
849         * @return <tt>round(this + unscaledAugend &times; 10<sup>-scale</sup>)</tt>
850         * @throws ArithmeticException
851         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
852         */
853        Decimal<S> addUnscaled(long unscaledAugend, int scale, RoundingMode roundingMode);
854
855        /**
856         * Returns a {@code Decimal} whose value is <tt>(this + unscaledAugend &times; 10<sup>-scale</sup>)</tt>. The result
857         * of the addition is rounded if necessary using the {@link RoundingMode} defined by the {@code truncationPolicy}
858         * argument. The {@code truncationPolicy} also defines the {@link OverflowMode} to apply if the operation causes an
859         * overflow.
860         * <p>
861         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
862         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
863         * the outcome of the addition.
864         * 
865         * @param unscaledAugend
866         *            value to be added to this {@code Decimal}
867         * @param scale
868         *            the scale to apply to {@code unscaledAugend}, positive to indicate the number of fraction digits to
869         *            the right of the Decimal point and negative to indicate up-scaling with a power of ten
870         * @param truncationPolicy
871         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
872         *            necessary or if an overflow occurs during the addition
873         * @return <tt>round(this + unscaledAugend &times; 10<sup>-scale</sup>)</tt>
874         * @throws ArithmeticException
875         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary or if
876         *             an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
877         */
878        Decimal<S> addUnscaled(long unscaledAugend, int scale, TruncationPolicy truncationPolicy);
879
880        /**
881         * Returns a {@code Decimal} whose value is <tt>(this + value<sup>2</sup>)</tt>. The squared value is rounded
882         * <i>before</i> the addition if necessary using default {@link RoundingMode#HALF_UP HALF_UP} rounding. Overflows
883         * during squaring or addition are silently truncated.
884         * <p>
885         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
886         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
887         * the outcome of the addition.
888         * 
889         * @param value
890         *            value to be squared and added to this {@code Decimal}
891         * @return <tt>this + round<sub>HALF_UP</sub>(value*value)</tt>
892         */
893        Decimal<S> addSquared(Decimal<S> value);
894
895        /**
896         * Returns a {@code Decimal} whose value is <tt>(this + value<sup>2</sup>)</tt>. The squared value is rounded
897         * <i>before</i> the addition if necessary using the specified {@code roundingMode}. Overflows during squaring or
898         * addition are silently truncated.
899         * <p>
900         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
901         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
902         * the outcome of the addition.
903         * 
904         * @param value
905         *            value to be squared and added to this {@code Decimal}
906         * @param roundingMode
907         *            the rounding mode to apply if necessary when squaring the value
908         * @return <tt>this + round(value*value)</tt>
909         * @throws ArithmeticException
910         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
911         */
912        Decimal<S> addSquared(Decimal<S> value, RoundingMode roundingMode);
913
914        /**
915         * Returns a {@code Decimal} whose value is <tt>(this + value<sup>2</sup>)</tt>. The squared value is rounded
916         * <i>before</i> the addition if necessary using the {@link RoundingMode} specified by the {@code truncationPolicy}
917         * argument. The {@code truncationPolicy} also defines the {@link OverflowMode} to apply if an overflow occurs
918         * during square or add operation.
919         * <p>
920         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
921         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
922         * the outcome of the addition.
923         * 
924         * @param value
925         *            value to be squared and added to this {@code Decimal}
926         * @param truncationPolicy
927         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
928         *            necessary when squaring the value or if an overflow occurs during the square or add operation
929         * @return <tt>this + round(value*value)</tt>
930         * @throws ArithmeticException
931         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary or if
932         *             an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
933         */
934        Decimal<S> addSquared(Decimal<S> value, TruncationPolicy truncationPolicy);
935
936        // subtract
937
938        /**
939         * Returns a {@code Decimal} whose value is {@code (this - subtrahend)}. If the subtraction causes an overflow, the
940         * result is silently truncated.
941         * <p>
942         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
943         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
944         * the outcome of the subtraction.
945         * 
946         * @param subtrahend
947         *            value to be subtracted from this {@code Decimal}
948         * @return {@code this - subtrahend}
949         */
950        Decimal<S> subtract(Decimal<S> subtrahend);
951
952        /**
953         * Returns a {@code Decimal} whose value is {@code (this - subtrahend)}. The specified {@code overflowMode}
954         * determines whether to truncate the result silently or to throw an exception if an overflow occurs.
955         * <p>
956         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
957         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
958         * the outcome of the subtraction.
959         * 
960         * @param subtrahend
961         *            value to be subtracted from this {@code Decimal}
962         * @param overflowMode
963         *            the overflow mode to apply if the subtraction leads to an overflow
964         * @return {@code this - subtrahend}
965         * @throws ArithmeticException
966         *             if {@code overflowMode==CHECKED} and an overflow occurs
967         */
968        Decimal<S> subtract(Decimal<S> subtrahend, OverflowMode overflowMode);
969
970        /**
971         * Returns a {@code Decimal} whose value is {@code (this - subtrahend)} after converting the given
972         * {@code subtrahend} argument to the scale of {@code this} Decimal. The result of the subtraction is rounded if
973         * necessary using the specified {@code roundingMode}. Overflows during scale conversion or subtraction are silently
974         * truncated.
975         * <p>
976         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
977         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
978         * the outcome of the subtraction.
979         * 
980         * @param subtrahend
981         *            value to be subtracted from this {@code Decimal}
982         * @param roundingMode
983         *            the rounding mode to apply if rounding is necessary
984         * @return <tt>round<sub>HALF_UP</sub>(this - subtrahend)</tt>
985         * @throws ArithmeticException
986         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
987         */
988        Decimal<S> subtract(Decimal<?> subtrahend, RoundingMode roundingMode);
989
990        /**
991         * Returns a {@code Decimal} whose value is {@code (this - subtrahend)} after converting the given
992         * {@code subtrahend} argument to the scale of {@code this} Decimal. The result of the subtraction is rounded if
993         * necessary using the {@link RoundingMode} defined by the {@code truncationPolicy} argument. The
994         * {@code truncationPolicy} also defines the {@link OverflowMode} to apply if the operation causes an overflow.
995         * <p>
996         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
997         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
998         * the outcome of the subtraction.
999         * 
1000         * @param subtrahend
1001         *            value to be subtracted from this {@code Decimal}
1002         * @param truncationPolicy
1003         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
1004         *            necessary or if an overflow occurs during the subtraction
1005         * @return <tt>round(this - subtrahend)</tt>
1006         * @throws ArithmeticException
1007         *             if {@code truncationPolicy} specifies {@link RoundingMode#UNNECESSARY} and rounding is necessary or
1008         *             if an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
1009         */
1010        Decimal<S> subtract(Decimal<?> subtrahend, TruncationPolicy truncationPolicy);
1011
1012        /**
1013         * Returns a {@code Decimal} whose value is {@code (this - subtrahend)}. If the subtraction causes an overflow, the
1014         * result is silently truncated.
1015         * <p>
1016         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1017         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1018         * the outcome of the subtraction.
1019         * 
1020         * @param subtrahend
1021         *            long value to be subtracted from this {@code Decimal}
1022         * @return {@code this - subtrahend}
1023         */
1024        Decimal<S> subtract(long subtrahend);
1025
1026        /**
1027         * Returns a {@code Decimal} whose value is {@code (this - subtrahend)}. The specified {@code overflowMode}
1028         * determines whether to truncate the result silently or to throw an exception if an overflow occurs.
1029         * <p>
1030         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1031         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1032         * the outcome of the subtraction.
1033         * 
1034         * @param subtrahend
1035         *            long value to be subtracted from this {@code Decimal}
1036         * @param overflowMode
1037         *            the overflow mode to apply if the subtraction leads to an overflow
1038         * @return {@code this - subtrahend}
1039         * @throws ArithmeticException
1040         *             if {@code overflowMode==CHECKED} and an overflow occurs
1041         */
1042        Decimal<S> subtract(long subtrahend, OverflowMode overflowMode);
1043
1044        /**
1045         * Returns a {@code Decimal} whose value is {@code (this - subtrahend)} after converting the given {@code double}
1046         * argument into a Decimal value of the same scale as {@code this} Decimal. If rounding is necessary,
1047         * {@link RoundingMode#HALF_UP HALF_UP} rounding mode is used and applied during the conversion step <i>before</i>
1048         * the subtraction operation. Overflows due to conversion or subtraction result in an exception.
1049         * <p>
1050         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1051         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1052         * the outcome of the subtraction.
1053         * 
1054         * @param subtrahend
1055         *            value to be subtracted from this {@code Decimal}
1056         * @return <tt>this - round<sub>HALF_UP</sub>(subtrahend)</tt>
1057         * @throws IllegalArgumentException
1058         *             if {@code subtrahend} is NaN or infinite or if the magnitude is too large for the double to be
1059         *             represented as a {@code Decimal}
1060         * @throws ArithmeticException
1061         *             if an overflow occurs during the subtraction operation
1062         */
1063        Decimal<S> subtract(double subtrahend);
1064
1065        /**
1066         * Returns a {@code Decimal} whose value is {@code (this - subtrahend)} after converting the given {@code double}
1067         * argument into a Decimal value of the same scale as {@code this} Decimal. If rounding is necessary, the specified
1068         * {@code roundingMode} is used and applied during the conversion step <i>before</i> the subtraction operation.
1069         * Overflows due to conversion or subtraction result in an exception.
1070         * <p>
1071         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1072         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1073         * the outcome of the subtraction.
1074         * 
1075         * @param subtrahend
1076         *            value to be subtracted from this {@code Decimal}
1077         * @param roundingMode
1078         *            the rounding mode to apply if the subtrahend argument needs to be rounded when converted into a
1079         *            Decimal number of the same scale as {@code this} Decimal
1080         * @return <tt>this - round(subtrahend)</tt>
1081         * @throws IllegalArgumentException
1082         *             if {@code subtrahend} is NaN or infinite or if the magnitude is too large for the double to be
1083         *             represented as a {@code Decimal}
1084         * @throws ArithmeticException
1085         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary or if an overflow occurs during the
1086         *             subtraction operation
1087         */
1088        Decimal<S> subtract(double subtrahend, RoundingMode roundingMode);
1089
1090        /**
1091         * Returns a {@code Decimal} whose value is <tt>(this - unscaledSubtrahend &times; 10<sup>-scale</sup>)</tt> with
1092         * the {@link #getScale() scale} of this Decimal. If the subtraction causes an overflow, the result is silently
1093         * truncated.
1094         * <p>
1095         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1096         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1097         * the outcome of the subtraction.
1098         * 
1099         * @param unscaledSubtrahend
1100         *            value to be subtracted from this {@code Decimal}
1101         * @return <tt>this - unscaledSubtrahend &times; 10<sup>-scale</sup></tt>
1102         */
1103        Decimal<S> subtractUnscaled(long unscaledSubtrahend);
1104
1105        /**
1106         * Returns a {@code Decimal} whose value is <tt>(this - unscaledSubtrahend &times; 10<sup>-scale</sup>)</tt> with
1107         * the {@link #getScale() scale} of this Decimal. The specified {@code overflowMode} determines whether to truncate
1108         * the result silently or to throw an exception if an overflow occurs.
1109         * <p>
1110         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1111         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1112         * the outcome of the subtraction.
1113         * 
1114         * @param unscaledSubtrahend
1115         *            value to be subtracted from this {@code Decimal}
1116         * @param overflowMode
1117         *            the overflow mode to apply if the subtraction leads to an overflow
1118         * @return <tt>this - unscaledSubtrahend &times; 10<sup>-scale</sup></tt>
1119         * @throws ArithmeticException
1120         *             if {@code overflowMode==CHECKED} and an overflow occurs
1121         */
1122        Decimal<S> subtractUnscaled(long unscaledSubtrahend, OverflowMode overflowMode);
1123
1124        /**
1125         * Returns a {@code Decimal} whose value is <tt>(this - unscaledSubtrahend &times; 10<sup>-scale</sup>)</tt>. The
1126         * result of the subtraction is rounded if necessary using {@link RoundingMode#HALF_UP HALF_UP} rounding. If the
1127         * operation causes an overflow, the result is silently truncated.
1128         * <p>
1129         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1130         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1131         * the outcome of the subtraction.
1132         * 
1133         * @param unscaledSubtrahend
1134         *            value to be subtracted from this {@code Decimal}
1135         * @param scale
1136         *            the scale to apply to {@code unscaledSubtrahend}, positive to indicate the number of fraction digits
1137         *            to the right of the Decimal point and negative to indicate up-scaling with a power of ten
1138         * @return <tt>round<sub>HALF_UP</sub>(this - unscaledSubtrahend &times; 10<sup>-scale</sup>)</tt>
1139         */
1140        Decimal<S> subtractUnscaled(long unscaledSubtrahend, int scale);
1141
1142        /**
1143         * Returns a {@code Decimal} whose value is <tt>(this - unscaledSubtrahend &times; 10<sup>-scale</sup>)</tt>. The
1144         * result of the subtraction is rounded if necessary using the specified {@code roundingMode}. If the operation
1145         * causes an overflow, the result is silently truncated.
1146         * <p>
1147         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1148         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1149         * the outcome of the subtraction.
1150         * 
1151         * @param unscaledSubtrahend
1152         *            value to be subtracted from this {@code Decimal}
1153         * @param scale
1154         *            the scale to apply to {@code unscaledSubtrahend}, positive to indicate the number of fraction digits
1155         *            to the right of the Decimal point and negative to indicate up-scaling with a power of ten
1156         * @param roundingMode
1157         *            the rounding mode to apply if rounding is necessary
1158         * @return <tt>round(this - unscaledSubtrahend &times; 10<sup>-scale</sup>)</tt>
1159         * @throws ArithmeticException
1160         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
1161         */
1162        Decimal<S> subtractUnscaled(long unscaledSubtrahend, int scale, RoundingMode roundingMode);
1163
1164        /**
1165         * Returns a {@code Decimal} whose value is <tt>(this - unscaledSubtrahend &times; 10<sup>-scale</sup>)</tt>. The
1166         * result of the subtraction is rounded if necessary using the {@link RoundingMode} defined by the
1167         * {@code truncationPolicy} argument. The {@code truncationPolicy} also defines the {@link OverflowMode} to apply if
1168         * the operation causes an overflow.
1169         * <p>
1170         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1171         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1172         * the outcome of the subtraction.
1173         * 
1174         * @param unscaledSubtrahend
1175         *            value to be subtracted from this {@code Decimal}
1176         * @param scale
1177         *            the scale to apply to {@code unscaledSubtrahend}, positive to indicate the number of fraction digits
1178         *            to the right of the Decimal point and negative to indicate up-scaling with a power of ten
1179         * @param truncationPolicy
1180         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
1181         *            necessary or if an overflow occurs during the subtraction
1182         * @return <tt>round(this - unscaledSubtrahend &times; 10<sup>-scale</sup>)</tt>
1183         * @throws ArithmeticException
1184         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary or if
1185         *             an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
1186         */
1187        Decimal<S> subtractUnscaled(long unscaledSubtrahend, int scale, TruncationPolicy truncationPolicy);
1188
1189        /**
1190         * Returns a {@code Decimal} whose value is <tt>(this - value<sup>2</sup>)</tt>. The squared value is rounded
1191         * <i>before</i> the subtraction if necessary using default {@link RoundingMode#HALF_UP HALF_UP} rounding. Overflows
1192         * during squaring or subtraction are silently truncated.
1193         * <p>
1194         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1195         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1196         * the outcome of the subtraction.
1197         * 
1198         * @param value
1199         *            value to be squared and subtracted from this {@code Decimal}
1200         * @return <tt>this - round<sub>HALF_UP</sub>(value*value)</tt>
1201         */
1202        Decimal<S> subtractSquared(Decimal<S> value);
1203
1204        /**
1205         * Returns a {@code Decimal} whose value is <tt>(this - value<sup>2</sup>)</tt>. The squared value is rounded
1206         * <i>before</i> the subtraction if necessary using the specified {@code roundingMode}. Overflows during squaring or
1207         * subtraction are silently truncated.
1208         * <p>
1209         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1210         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1211         * the outcome of the subtraction.
1212         * 
1213         * @param value
1214         *            value to be squared and subtracted from this {@code Decimal}
1215         * @param roundingMode
1216         *            the rounding mode to apply if necessary when squaring the value
1217         * @return <tt>this - round(value*value)</tt>
1218         * @throws ArithmeticException
1219         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
1220         */
1221        Decimal<S> subtractSquared(Decimal<S> value, RoundingMode roundingMode);
1222
1223        /**
1224         * Returns a {@code Decimal} whose value is <tt>(this - value<sup>2</sup>)</tt>. The squared value is rounded
1225         * <i>before</i> the subtraction if necessary using the {@link RoundingMode} specified by the
1226         * {@code truncationPolicy} argument. The {@code truncationPolicy} also defines the {@link OverflowMode} to apply if
1227         * an overflow occurs during square or subtract operation.
1228         * <p>
1229         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1230         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1231         * the outcome of the subtraction.
1232         * 
1233         * @param value
1234         *            value to be squared and subtracted from this {@code Decimal}
1235         * @param truncationPolicy
1236         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
1237         *            necessary when squaring the value or if an overflow occurs during the square or subtract operation
1238         * @return <tt>this - round(value*value)</tt>
1239         * @throws ArithmeticException
1240         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary or if
1241         *             an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
1242         */
1243        Decimal<S> subtractSquared(Decimal<S> value, TruncationPolicy truncationPolicy);
1244
1245        // multiply
1246
1247        /**
1248         * Returns a {@code Decimal} whose value is {@code (this * multiplicand)}. The result is rounded to the
1249         * {@link #getScale() scale} of this Decimal using default {@link RoundingMode#HALF_UP HALF_UP} rounding. If the
1250         * multiplication causes an overflow, the result is silently truncated.
1251         * <p>
1252         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1253         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1254         * the outcome of the multiplication.
1255         * 
1256         * @param multiplicand
1257         *            factor to multiply with this {@code Decimal}
1258         * @return <tt>round<sub>HALF_UP</sub>(this * multiplicand)</tt>
1259         */
1260        Decimal<S> multiply(Decimal<S> multiplicand);
1261
1262        /**
1263         * Returns a {@code Decimal} whose value is {@code (this * multiplicand)}. The result is rounded to the
1264         * {@link #getScale() scale} of this Decimal using the specified {@code roundingMode}. If the multiplication causes
1265         * an overflow, the result is silently truncated.
1266         * <p>
1267         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1268         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1269         * the outcome of the multiplication.
1270         * 
1271         * @param multiplicand
1272         *            factor to multiply with this {@code Decimal}
1273         * @param roundingMode
1274         *            the rounding mode to apply if the result needs to be rounded
1275         * @return <tt>round(this * multiplicand)</tt>
1276         * @throws ArithmeticException
1277         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
1278         */
1279        Decimal<S> multiply(Decimal<S> multiplicand, RoundingMode roundingMode);
1280
1281        /**
1282         * Returns a {@code Decimal} whose value is {@code (this * multiplicand)}. The result is rounded to the
1283         * {@link #getScale() scale} of this Decimal using the {@link RoundingMode} specified by the
1284         * {@code truncationPolicy} argument. The {@code truncationPolicy} also defines the {@link OverflowMode} to apply if
1285         * an overflow occurs during the multiply operation.
1286         * <p>
1287         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1288         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1289         * the outcome of the multiplication.
1290         * 
1291         * @param multiplicand
1292         *            factor to multiply with this {@code Decimal}
1293         * @param truncationPolicy
1294         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
1295         *            necessary or if an overflow occurs
1296         * @return <tt>round(this * multiplicand)</tt>
1297         * @throws ArithmeticException
1298         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary or if
1299         *             an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
1300         */
1301        Decimal<S> multiply(Decimal<S> multiplicand, TruncationPolicy truncationPolicy);
1302
1303        /**
1304         * Returns a {@code Decimal} whose value is {@code (this * multiplicand)}. The result is rounded to the
1305         * {@link #getScale() scale} of this Decimal using {@link RoundingMode#HALF_UP HALF_UP} rounding. If the
1306         * multiplication causes an overflow, the result is silently truncated.
1307         * <p>
1308         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1309         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1310         * the outcome of the multiplication.
1311         * 
1312         * @param multiplicand
1313         *            factor to multiply with this {@code Decimal}
1314         * @return <tt>round<sub>HALF_UP</sub>(this * multiplicand)</tt>
1315         */
1316        Decimal<S> multiplyBy(Decimal<?> multiplicand);
1317
1318        /**
1319         * Returns a {@code Decimal} whose value is {@code (this * multiplicand)}. The result is rounded to the
1320         * {@link #getScale() scale} of this Decimal using the specified {@code roundingMode}. If the multiplication causes
1321         * an overflow, the result is silently truncated.
1322         * <p>
1323         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1324         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1325         * the outcome of the multiplication.
1326         * 
1327         * @param multiplicand
1328         *            factor to multiply with this {@code Decimal}
1329         * @param roundingMode
1330         *            the rounding mode to apply if rounding is necessary
1331         * @return <tt>round(this * multiplicand)</tt>
1332         * @throws ArithmeticException
1333         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
1334         */
1335        Decimal<S> multiplyBy(Decimal<?> multiplicand, RoundingMode roundingMode);
1336
1337        /**
1338         * Returns a {@code Decimal} whose value is {@code (this * multiplicand)}. The result is rounded to the
1339         * {@link #getScale() scale} of this Decimal using the {@link RoundingMode} defined by the {@code truncationPolicy}
1340         * argument. The {@code truncationPolicy} also defines the {@link OverflowMode} to apply if the operation causes an
1341         * overflow.
1342         * <p>
1343         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1344         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1345         * the outcome of the multiplication.
1346         * 
1347         * @param multiplicand
1348         *            factor to multiply with this {@code Decimal}
1349         * @param truncationPolicy
1350         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
1351         *            necessary or if an overflow occurs
1352         * @return <tt>round(this * multiplicand)</tt>
1353         * @throws ArithmeticException
1354         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary or if
1355         *             an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
1356         */
1357        Decimal<S> multiplyBy(Decimal<?> multiplicand, TruncationPolicy truncationPolicy);
1358
1359        /**
1360         * Returns a {@code Decimal} whose value is {@code (this * multiplicand)}. The scale of the returned value is the
1361         * sum of the scales of {@code this} Decimal and the {@code multiplicand} argument. If the result scale exceeds 18,
1362         * an {@link IllegalArgumentException} is thrown. An {@link ArithmeticException} is thrown if the product is out of
1363         * the possible range for a Decimal with the result scale.
1364         * <p>
1365         * Note that the result is <i>always</i> a new instance --- immutable if this Decimal is an {@link ImmutableDecimal}
1366         * and mutable if it is a {@link MutableDecimal}.
1367         * 
1368         * @param multiplicand
1369         *            factor to multiply with this {@code Decimal}
1370         * @return {@code (this * multiplicand)} with scale equal to the sum of scales of {@code this} and
1371         *         {@code multiplicand}
1372         * @throws IllegalArgumentException
1373         *             if the sum of the scales of {@code this} Decimal and the {@code multiplicand} argument exceeds 18
1374         * @throws ArithmeticException
1375         *             if an overflow occurs and product is out of the possible range for a Decimal with the result scale
1376         */
1377        Decimal<?> multiplyExact(Decimal<?> multiplicand);
1378
1379        /**
1380         * Returns a {@code Decimal} whose value is {@code (this * multiplicand)}. If the multiplication causes an overflow,
1381         * the result is silently truncated.
1382         * <p>
1383         * This method performs multiplication of this {@code Decimal} with a {@code long} value which is usually more
1384         * efficient than multiplication of two Decimal values.
1385         * <p>
1386         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1387         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1388         * the outcome of the multiplication.
1389         * 
1390         * @param multiplicand
1391         *            factor to multiply with this {@code Decimal}
1392         * @return {@code (this * multiplicand)}
1393         */
1394        Decimal<S> multiply(long multiplicand);
1395
1396        /**
1397         * Returns a {@code Decimal} whose value is {@code (this * multiplicand)}. The specified {@code overflowMode}
1398         * determines whether to truncate the result silently or to throw an exception if an overflow occurs.
1399         * <p>
1400         * This method performs multiplication of this {@code Decimal} with a {@code long} value which is usually more
1401         * efficient than multiplication of two Decimal values.
1402         * <p>
1403         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1404         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1405         * the outcome of the multiplication.
1406         * 
1407         * @param multiplicand
1408         *            factor to multiply with this {@code Decimal}
1409         * @param overflowMode
1410         *            the overflow mode to apply if the multiplication leads to an overflow
1411         * @return {@code (this * multiplicand)}
1412         * @throws ArithmeticException
1413         *             if {@code overflowMode==CHECKED} and an overflow occurs
1414         */
1415        Decimal<S> multiply(long multiplicand, OverflowMode overflowMode);
1416
1417        /**
1418         * Returns a {@code Decimal} whose value is {@code (this * multiplicand)} after converting the given {@code double}
1419         * argument into a Decimal value of the same scale as {@code this} Decimal. {@link RoundingMode#HALF_UP HALF_UP}
1420         * rounding mode is used if necessary and applied twice during the conversion step <i>before</i> the multiplication
1421         * and again when rounding the product to the {@link #getScale() scale} of this Decimal. Overflows due to conversion
1422         * or multiplication result in an exception.
1423         * <p>
1424         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1425         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1426         * the outcome of the multiplication.
1427         * 
1428         * @param multiplicand
1429         *            factor to multiply with this {@code Decimal}
1430         * @return <tt>round<sub>HALF_UP</sub>(this * round<sub>HALF_UP</sub>(multiplicand))</tt>
1431         * @throws IllegalArgumentException
1432         *             if {@code multiplicand} is NaN or infinite or if the magnitude is too large for the double to be
1433         *             represented as a {@code Decimal}
1434         * @throws ArithmeticException
1435         *             if an overflow occurs during the multiply operation
1436         */
1437        Decimal<S> multiply(double multiplicand);
1438
1439        /**
1440         * Returns a {@code Decimal} whose value is {@code (this * multiplicand)} after converting the given {@code double}
1441         * argument into a Decimal value of the same scale as {@code this} Decimal. Rounding, if necessary, uses the
1442         * specified {@code roundingMode} and is applied during the conversion step <i>before</i> the multiplication and
1443         * again when rounding the product to the {@link #getScale() scale} of this Decimal. Overflows due to conversion or
1444         * multiplication result in an exception.
1445         * <p>
1446         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1447         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1448         * the outcome of the multiplication.
1449         * 
1450         * @param multiplicand
1451         *            factor to multiply with this {@code Decimal}
1452         * @param roundingMode
1453         *            the rounding mode to apply if the converted multiplicand or the resulting product needs to be rounded
1454         * @return {@code round(this * round(multiplicand))}
1455         * @throws IllegalArgumentException
1456         *             if {@code multiplicand} is NaN or infinite or if the magnitude is too large for the double to be
1457         *             represented as a {@code Decimal}
1458         * @throws ArithmeticException
1459         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary or if an overflow occurs during the
1460         *             multiply operation
1461         */
1462        Decimal<S> multiply(double multiplicand, RoundingMode roundingMode);
1463
1464        /**
1465         * Returns a {@code Decimal} whose value is <tt>(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt> with
1466         * the {@link #getScale() scale} of this Decimal. The result is rounded to the scale of this Decimal using default
1467         * {@link RoundingMode#HALF_UP HALF_UP} rounding. If the multiplication causes an overflow, the result is silently
1468         * truncated.
1469         * <p>
1470         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1471         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1472         * the outcome of the multiplication.
1473         * 
1474         * @param unscaledMultiplicand
1475         *            factor to multiply with this {@code Decimal}
1476         * @return <tt>round<sub>HALF_UP</sub>(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt>
1477         */
1478        Decimal<S> multiplyUnscaled(long unscaledMultiplicand);
1479
1480        /**
1481         * Returns a {@code Decimal} whose value is <tt>(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt> with
1482         * the {@link #getScale() scale} of this Decimal. The result is rounded to the scale of this Decimal using the
1483         * specified {@code roundingMode}. If the multiplication causes an overflow, the result is silently truncated.
1484         * <p>
1485         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1486         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1487         * the outcome of the multiplication.
1488         * 
1489         * @param unscaledMultiplicand
1490         *            factor to multiply with this {@code Decimal}
1491         * @param roundingMode
1492         *            the rounding mode to apply if the result needs to be rounded
1493         * @return <tt>round(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt>
1494         * @throws ArithmeticException
1495         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
1496         */
1497        Decimal<S> multiplyUnscaled(long unscaledMultiplicand, RoundingMode roundingMode);
1498
1499        /**
1500         * Returns a {@code Decimal} whose value is <tt>(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt> with
1501         * the {@link #getScale() scale} of this Decimal. The result is rounded to the scale of this Decimal using the using
1502         * the {@link RoundingMode} specified by the {@code truncationPolicy} argument. The {@code truncationPolicy} also
1503         * defines the {@link OverflowMode} to apply if an overflow occurs during the multiplication.
1504         * <p>
1505         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1506         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1507         * the outcome of the multiplication.
1508         * 
1509         * @param unscaledMultiplicand
1510         *            factor to multiply with this {@code Decimal}
1511         * @param truncationPolicy
1512         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
1513         *            necessary or if an overflow occurs
1514         * @return <tt>round(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt>
1515         * @throws ArithmeticException
1516         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary or if
1517         *             an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
1518         */
1519        Decimal<S> multiplyUnscaled(long unscaledMultiplicand, TruncationPolicy truncationPolicy);
1520
1521        /**
1522         * Returns a {@code Decimal} whose value is <tt>(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt>. The
1523         * result of the multiplication is rounded to the {@link #getScale() scale} of this Decimal using
1524         * {@link RoundingMode#HALF_UP HALF_UP} rounding. If the operation causes an overflow, the result is silently
1525         * truncated.
1526         * <p>
1527         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1528         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1529         * the outcome of the multiplication.
1530         * 
1531         * @param unscaledMultiplicand
1532         *            factor to multiply with this {@code Decimal}
1533         * @param scale
1534         *            the scale to apply to {@code unscaledMultiplicand}, positive to indicate the number of fraction digits
1535         *            to the right of the Decimal point and negative to indicate up-scaling with a power of ten
1536         * @return <tt>round<sub>HALF_UP</sub>(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt>
1537         */
1538        Decimal<S> multiplyUnscaled(long unscaledMultiplicand, int scale);
1539
1540        /**
1541         * Returns a {@code Decimal} whose value is <tt>(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt>. The
1542         * result of the multiplication is rounded to the {@link #getScale() scale} of this Decimal using the specified
1543         * {@code roundingMode}. If the operation causes an overflow, the result is silently truncated.
1544         * <p>
1545         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1546         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1547         * the outcome of the multiplication.
1548         * 
1549         * @param unscaledMultiplicand
1550         *            factor to multiply with this {@code Decimal}
1551         * @param scale
1552         *            the scale to apply to {@code unscaledMultiplicand}, positive to indicate the number of fraction digits
1553         *            to the right of the Decimal point and negative to indicate up-scaling with a power of ten
1554         * @param roundingMode
1555         *            the rounding mode to apply if rounding is necessary
1556         * @return <tt>round(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt>
1557         * @throws ArithmeticException
1558         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
1559         */
1560        Decimal<S> multiplyUnscaled(long unscaledMultiplicand, int scale, RoundingMode roundingMode);
1561
1562        /**
1563         * Returns a {@code Decimal} whose value is <tt>(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt>. The
1564         * result of the multiplication is rounded to the {@link #getScale() scale} of this Decimal using the
1565         * {@link RoundingMode} defined by the {@code truncationPolicy} argument. The {@code truncationPolicy} also defines
1566         * the {@link OverflowMode} to apply if the operation causes an overflow.
1567         * <p>
1568         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1569         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1570         * the outcome of the multiplication.
1571         * 
1572         * @param unscaledMultiplicand
1573         *            factor to multiply with this {@code Decimal}
1574         * @param scale
1575         *            the scale to apply to {@code unscaledMultiplicand}, positive to indicate the number of fraction digits
1576         *            to the right of the Decimal point and negative to indicate up-scaling with a power of ten
1577         * @param truncationPolicy
1578         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
1579         *            necessary or if an overflow occurs
1580         * @return <tt>round(this * unscaledMultiplicand &times; 10<sup>-scale</sup>)</tt>
1581         * @throws ArithmeticException
1582         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary or if
1583         *             an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
1584         */
1585        Decimal<S> multiplyUnscaled(long unscaledMultiplicand, int scale, TruncationPolicy truncationPolicy);
1586
1587        /**
1588         * Returns a {@code Decimal} whose value is <tt>(this * 10<sup>n</sup>)</tt> . For negative <tt>n</tt> the
1589         * multiplication turns into a de-facto division and the result is rounded to the {@link #getScale() scale} of this
1590         * Decimal using default {@link RoundingMode#HALF_UP HALF_UP} rounding. If the multiplication causes an overflow,
1591         * the result is silently truncated.
1592         * <p>
1593         * The result of this operation is the same as for {@link #divideByPowerOfTen(int) divideByPowerOfTen(-n)} given
1594         * {@code n > }{@link Integer#MIN_VALUE}.
1595         * <p>
1596         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1597         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1598         * the outcome of the multiplication.
1599         * 
1600         * @param n
1601         *            the exponent of the power-of-ten factor to multiply with this {@code Decimal}
1602         * @return <tt>round<sub>HALF_UP</sub>(this * 10<sup>n</sup>)</tt>
1603         */
1604        Decimal<S> multiplyByPowerOfTen(int n);
1605
1606        /**
1607         * Returns a {@code Decimal} whose value is <tt>(this * 10<sup>n</sup>)</tt> . For negative <tt>n</tt> the
1608         * multiplication turns into a de-facto division and the result is rounded to the {@link #getScale() scale} of this
1609         * Decimal using the specified {@code roundingMode}. If the multiplication causes an overflow, the result is
1610         * silently truncated.
1611         * <p>
1612         * The result of this operation is the same as for {@link #divideByPowerOfTen(int, RoundingMode)
1613         * divideByPowerOfTen(-n, roundingMode)} given {@code n > }{@link Integer#MIN_VALUE}.
1614         * <p>
1615         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1616         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1617         * the outcome of the multiplication.
1618         * 
1619         * @param n
1620         *            the exponent of the power-of-ten factor to multiply with this {@code Decimal}
1621         * @param roundingMode
1622         *            the rounding mode to apply if the result needs to be rounded for the case {@code n < 0}
1623         * @return <tt>round(this * 10<sup>n</sup>)</tt>
1624         * @throws ArithmeticException
1625         *             if {@code n < 0} and {@code roundingMode==UNNECESSARY} and rounding is necessary
1626         */
1627        Decimal<S> multiplyByPowerOfTen(int n, RoundingMode roundingMode);
1628
1629        /**
1630         * Returns a {@code Decimal} whose value is <tt>(this * 10<sup>n</sup>)</tt> . For negative <tt>n</tt> the
1631         * multiplication turns into a de-facto division and the result is rounded to the {@link #getScale() scale} of this
1632         * Decimal using the {@link RoundingMode} specified by the {@code truncationPolicy} argument. The
1633         * {@code truncationPolicy} also defines the {@link OverflowMode} to apply if an overflow occurs during the
1634         * multiplication.
1635         * <p>
1636         * The result of this operation is the same as for {@link #divideByPowerOfTen(int, TruncationPolicy)
1637         * divideByPowerOfTen(-n, truncationPolicy)} given {@code n > }{@link Integer#MIN_VALUE}.
1638         * <p>
1639         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1640         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1641         * the outcome of the multiplication.
1642         * 
1643         * @param n
1644         *            the exponent of the power-of-ten factor to multiply with this {@code Decimal}
1645         * @param truncationPolicy
1646         *            the truncation policy specifying {@link RoundingMode} to apply if rounding is necessary when
1647         *            {@code n < 0} as well {@link OverflowMode} to use if {@code n > 0} and an overflow occurs during the
1648         *            multiplication
1649         * @return <tt>round(this * 10<sup>n</sup>)</tt>
1650         * @throws ArithmeticException
1651         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary when
1652         *             {@code n < 0}, or if an overflow occurs and the policy declares {@link OverflowMode#CHECKED} for the
1653         *             case {@code n > 0}
1654         */
1655        Decimal<S> multiplyByPowerOfTen(int n, TruncationPolicy truncationPolicy);
1656
1657        // divide
1658
1659        /**
1660         * Returns a {@code Decimal} whose value is {@code (this / divisor)}. The result is rounded to the
1661         * {@link #getScale() scale} of this Decimal using {@link RoundingMode#HALF_UP HALF_UP} rounding. If the division
1662         * causes an overflow, the result is silently truncated.
1663         * <p>
1664         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1665         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1666         * the outcome of the division.
1667         * 
1668         * @param divisor
1669         *            divisor value by which this {@code Decimal} is to be divided
1670         * @return <tt>round<sub>HALF_UP</sub>(this / divisor)</tt>
1671         * @throws ArithmeticException
1672         *             if {@code divisor==0}
1673         */
1674        Decimal<S> divide(Decimal<S> divisor);
1675
1676        /**
1677         * Returns a {@code Decimal} whose value is {@code (this / divisor)}. The result is rounded to the
1678         * {@link #getScale() scale} of this Decimal using the specified {@code roundingMode}. If the division causes an
1679         * overflow, the result is silently truncated.
1680         * <p>
1681         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1682         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1683         * the outcome of the division.
1684         * 
1685         * @param divisor
1686         *            divisor value by which this {@code Decimal} is to be divided
1687         * @param roundingMode
1688         *            the rounding mode to apply if the result needs to be rounded
1689         * @return {@code round(this / divisor)}
1690         * @throws ArithmeticException
1691         *             if {@code divisor==0} or if {@code roundingMode==UNNECESSARY} and rounding is necessary
1692         */
1693        Decimal<S> divide(Decimal<S> divisor, RoundingMode roundingMode);
1694
1695        /**
1696         * Returns a {@code Decimal} whose value is {@code (this / divisor)}. The result is rounded to the
1697         * {@link #getScale() scale} of this Decimal using the {@link RoundingMode} specified by the
1698         * {@code truncationPolicy} argument. The {@code truncationPolicy} also defines the {@link OverflowMode} to apply if
1699         * an overflow occurs during the divide operation.
1700         * <p>
1701         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1702         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1703         * the outcome of the division.
1704         * 
1705         * @param divisor
1706         *            divisor value by which this {@code Decimal} is to be divided
1707         * @param truncationPolicy
1708         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
1709         *            necessary or if an overflow occurs
1710         * @return <tt>round(this / divisor)</tt>
1711         * @throws ArithmeticException
1712         *             if {@code divisor==0}, or if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and
1713         *             rounding is necessary or if an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
1714         */
1715        Decimal<S> divide(Decimal<S> divisor, TruncationPolicy truncationPolicy);
1716
1717        /**
1718         * Returns a {@code Decimal} whose value is {@code (this / divisor)}. The result is rounded to the
1719         * {@link #getScale() scale} of this Decimal using {@link RoundingMode#HALF_UP HALF_UP} rounding. If the division
1720         * causes an overflow, the result is silently truncated.
1721         * <p>
1722         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1723         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1724         * the outcome of the division.
1725         * 
1726         * @param divisor
1727         *            divisor value by which this {@code Decimal} is to be divided
1728         * @return <tt>round<sub>HALF_UP</sub>(this / divisor)</tt>
1729         * @throws ArithmeticException
1730         *             if {@code divisor==0}
1731         */
1732        Decimal<S> divideBy(Decimal<?> divisor);
1733
1734        /**
1735         * Returns a {@code Decimal} whose value is {@code (this / divisor)}. The result is rounded to the
1736         * {@link #getScale() scale} of this Decimal using the specified {@code roundingMode}. If the division causes an
1737         * overflow, the result is silently truncated.
1738         * <p>
1739         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1740         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1741         * the outcome of the division.
1742         * 
1743         * @param divisor
1744         *            divisor value by which this {@code Decimal} is to be divided
1745         * @param roundingMode
1746         *            the rounding mode to apply if rounding is necessary
1747         * @return {@code round(this / divisor)}
1748         * @throws ArithmeticException
1749         *             if {@code divisor==0} or if {@code roundingMode==UNNECESSARY} and rounding is necessary
1750         */
1751        Decimal<S> divideBy(Decimal<?> divisor, RoundingMode roundingMode);
1752
1753        /**
1754         * Returns a {@code Decimal} whose value is {@code (this / divisor)}. The result is rounded to the
1755         * {@link #getScale() scale} of this Decimal using the {@link RoundingMode} defined by the {@code truncationPolicy}
1756         * argument. The {@code truncationPolicy} also defines the {@link OverflowMode} to apply if the operation causes an
1757         * overflow.
1758         * <p>
1759         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1760         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1761         * the outcome of the division.
1762         * 
1763         * @param divisor
1764         *            divisor value by which this {@code Decimal} is to be divided
1765         * @param truncationPolicy
1766         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
1767         *            necessary or if an overflow occurs
1768         * @return {@code round(this / divisor)}
1769         * @throws ArithmeticException
1770         *             if {@code divisor==0}, or if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and
1771         *             rounding is necessary, or if an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
1772         */
1773        Decimal<S> divideBy(Decimal<?> divisor, TruncationPolicy truncationPolicy);
1774
1775        /**
1776         * Returns a {@code Decimal} whose value is {@code (this / divisor)} rounded down. This method is a shortcut for
1777         * calling {@link #divide(Decimal,RoundingMode) divide(divisor, RoundingMode.DOWN)}. If the division causes an
1778         * overflow, the result is silently truncated.
1779         * <p>
1780         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1781         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1782         * the outcome of the division.
1783         * 
1784         * @param divisor
1785         *            divisor value by which this {@code Decimal} is to be divided
1786         * @return <tt>round<sub>DOWN</sub>(this / divisor)</tt>
1787         * @throws ArithmeticException
1788         *             if {@code divisor==0}
1789         */
1790        Decimal<S> divideTruncate(Decimal<S> divisor);
1791
1792        /**
1793         * Returns a {@code Decimal} whose value is {@code (this / divisor)}, checking for lost information. If the quotient
1794         * cannot be represented exactly with the {@link #getScale() scale} of this Decimal then an
1795         * {@code ArithmeticException} is thrown.
1796         * <p>
1797         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1798         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1799         * the outcome of the division.
1800         * 
1801         * @param divisor
1802         *            divisor value by which this {@code Decimal} is to be divided
1803         * @return {@code this / divisor}
1804         * @throws ArithmeticException
1805         *             if {@code divisor==0}, or if the result does not fit in a Decimal with the scale of this Decimal
1806         *             without rounding and without exceeding the the possible range of such a Decimal
1807         */
1808        Decimal<S> divideExact(Decimal<S> divisor);
1809
1810        /**
1811         * Returns a {@code Decimal} whose value is {@code (this / divisor)}. The result is rounded to the
1812         * {@link #getScale() scale} of this Decimal using {@link RoundingMode#HALF_UP HALF_UP} rounding. If the division
1813         * causes an overflow, the result is silently truncated.
1814         * <p>
1815         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1816         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1817         * the outcome of the division.
1818         * 
1819         * @param divisor
1820         *            long value by which this {@code Decimal} is to be divided
1821         * @return <tt>round<sub>HALF_UP</sub>(this / divisor)</tt>
1822         * @throws ArithmeticException
1823         *             if {@code divisor==0}
1824         */
1825        Decimal<S> divide(long divisor);
1826
1827        /**
1828         * Returns a {@code Decimal} whose value is {@code (this / divisor)}. The result is rounded to the
1829         * {@link #getScale() scale} of this Decimal using the specified {@code roundingMode}. If the division causes an
1830         * overflow, the result is silently truncated.
1831         * <p>
1832         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1833         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1834         * the outcome of the division.
1835         * 
1836         * @param divisor
1837         *            long value by which this {@code Decimal} is to be divided
1838         * @param roundingMode
1839         *            the rounding mode to apply if the result needs to be rounded
1840         * @return {@code round(this / divisor)}
1841         * @throws ArithmeticException
1842         *             if {@code divisor==0} or if {@code roundingMode==UNNECESSARY} and rounding is necessary
1843         */
1844        Decimal<S> divide(long divisor, RoundingMode roundingMode);
1845
1846        /**
1847         * Returns a {@code Decimal} whose value is {@code (this / divisor)}. The result is rounded to the
1848         * {@link #getScale() scale} of this Decimal using the {@link RoundingMode} specified by the
1849         * {@code truncationPolicy} argument. The {@code truncationPolicy} also defines the {@link OverflowMode} to apply if
1850         * an overflow occurs during the divide operation.
1851         * <p>
1852         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1853         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1854         * the outcome of the division.
1855         * 
1856         * @param divisor
1857         *            long value by which this {@code Decimal} is to be divided
1858         * @param truncationPolicy
1859         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
1860         *            necessary or if an overflow occurs
1861         * @return <tt>round(this / divisor)</tt>
1862         * @throws ArithmeticException
1863         *             if {@code divisor==0}, or if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and
1864         *             rounding is necessary, or if the policy declares {@link OverflowMode#CHECKED} an overflow occurs
1865         */
1866        Decimal<S> divide(long divisor, TruncationPolicy truncationPolicy);
1867
1868        /**
1869         * Returns a {@code Decimal} whose value is {@code (this / divisor)} after converting the given {@code double}
1870         * argument into a Decimal value of the same scale as {@code this} Decimal. {@link RoundingMode#HALF_UP HALF_UP}
1871         * rounding mode is used if necessary and applied twice during the conversion step <i>before</i> the division and
1872         * again when rounding the quotient to the {@link #getScale() scale} of this Decimal. Overflows due to conversion or
1873         * division result in an exception.
1874         * <p>
1875         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1876         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1877         * the outcome of the division.
1878         * 
1879         * @param divisor
1880         *            divisor value by which this {@code Decimal} is to be divided
1881         * @return <tt>round<sub>HALF_UP</sub>(this / round<sub>HALF_UP</sub>(divisor))</tt>
1882         * @throws IllegalArgumentException
1883         *             if {@code divisor} is NaN or infinite or if the magnitude is too large for the double to be
1884         *             represented as a {@code Decimal}
1885         * @throws ArithmeticException
1886         *             if {@code divisor==0} or if an overflow occurs during the divide operation
1887         */
1888        Decimal<S> divide(double divisor);
1889
1890        /**
1891         * Returns a {@code Decimal} whose value is {@code (this / divisor)} after converting the given {@code double}
1892         * argument into a Decimal value of the same scale as {@code this} Decimal. Rounding, if necessary, uses the
1893         * specified {@code roundingMode} and is applied during the conversion step <i>before</i> the division and again
1894         * when rounding the quotient to the {@link #getScale() scale} of this Decimal. Overflows due to conversion or
1895         * division result in an exception.
1896         * <p>
1897         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1898         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1899         * the outcome of the division.
1900         * 
1901         * @param divisor
1902         *            divisor value by which this {@code Decimal} is to be divided
1903         * @param roundingMode
1904         *            the rounding mode to apply if the converted divisor or the resulting quotient needs to be rounded
1905         * @return {@code round(this / round(divisor))}
1906         * @throws IllegalArgumentException
1907         *             if {@code divisor} is NaN or infinite or if the magnitude is too large for the double to be
1908         *             represented as a {@code Decimal}
1909         * @throws ArithmeticException
1910         *             if {@code divisor==0}, if {@code roundingMode==UNNECESSARY} and rounding is necessary or if an
1911         *             overflow occurs during the divide operation
1912         */
1913        Decimal<S> divide(double divisor, RoundingMode roundingMode);
1914
1915        /**
1916         * Returns a {@code Decimal} whose value is <tt>(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt> with the
1917         * {@link #getScale() scale} of this Decimal. The result is rounded to the scale of this Decimal using default
1918         * {@link RoundingMode#HALF_UP HALF_UP} rounding. If the division causes an overflow, the result is silently
1919         * truncated.
1920         * <p>
1921         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1922         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1923         * the outcome of the division.
1924         * 
1925         * @param unscaledDivisor
1926         *            divisor value by which this {@code Decimal} is to be divided
1927         * @return <tt>round<sub>HALF_UP</sub>(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt>
1928         * @throws ArithmeticException
1929         *             if {@code unscaledDivisor==0}
1930         */
1931        Decimal<S> divideUnscaled(long unscaledDivisor);
1932
1933        /**
1934         * Returns a {@code Decimal} whose value is <tt>(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt> with the
1935         * {@link #getScale() scale} of this Decimal. The result is rounded to the scale of this Decimal using the specified
1936         * {@code roundingMode}. If the division causes an overflow, the result is silently truncated.
1937         * <p>
1938         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1939         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1940         * the outcome of the division.
1941         * 
1942         * @param unscaledDivisor
1943         *            divisor value by which this {@code Decimal} is to be divided
1944         * @param roundingMode
1945         *            the rounding mode to apply if the result needs to be rounded
1946         * @return <tt>round(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt>
1947         * @throws ArithmeticException
1948         *             if {@code unscaledDivisor==0} or if {@code roundingMode==UNNECESSARY} and rounding is necessary
1949         */
1950        Decimal<S> divideUnscaled(long unscaledDivisor, RoundingMode roundingMode);
1951
1952        /**
1953         * Returns a {@code Decimal} whose value is <tt>(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt> with the
1954         * {@link #getScale() scale} of this Decimal. The result is rounded to the scale of this Decimal using the using the
1955         * {@link RoundingMode} specified by the {@code truncationPolicy} argument. The {@code truncationPolicy} also
1956         * defines the {@link OverflowMode} to apply if an overflow occurs during the division.
1957         * <p>
1958         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1959         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1960         * the outcome of the division.
1961         * 
1962         * @param unscaledDivisor
1963         *            divisor value by which this {@code Decimal} is to be divided
1964         * @param truncationPolicy
1965         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
1966         *            necessary or if an overflow occurs
1967         * @return <tt>round(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt>
1968         * @throws ArithmeticException
1969         *             if {@code unscaledDivisor==0}, if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY}
1970         *             and rounding is necessary or if an overflow occurs and the policy declares
1971         *             {@link OverflowMode#CHECKED}
1972         */
1973        Decimal<S> divideUnscaled(long unscaledDivisor, TruncationPolicy truncationPolicy);
1974
1975        /**
1976         * Returns a {@code Decimal} whose value is <tt>(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt>. The
1977         * result is rounded to the scale of this Decimal using {@link RoundingMode#HALF_UP HALF_UP} rounding. If the
1978         * operation causes an overflow, the result is silently truncated.
1979         * <p>
1980         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
1981         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
1982         * the outcome of the division.
1983         * 
1984         * @param unscaledDivisor
1985         *            divisor value by which this {@code Decimal} is to be divided
1986         * @param scale
1987         *            the scale to apply to {@code unscaledDivisor}, positive to indicate the number of fraction digits to
1988         *            the right of the Decimal point and negative to indicate up-scaling with a power of ten
1989         * @return <tt>round<sub>HALF_UP</sub>(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt>
1990         * @throws ArithmeticException
1991         *             if {@code unscaledDivisor==0}
1992         */
1993        Decimal<S> divideUnscaled(long unscaledDivisor, int scale);
1994
1995        /**
1996         * Returns a {@code Decimal} whose value is <tt>(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt>. The
1997         * result is rounded to the scale of this Decimal using the specified {@code roundingMode}. If the operation causes
1998         * an overflow, the result is silently truncated.
1999         * <p>
2000         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2001         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2002         * the outcome of the division.
2003         * 
2004         * @param unscaledDivisor
2005         *            divisor value by which this {@code Decimal} is to be divided
2006         * @param scale
2007         *            the scale to apply to {@code unscaledDivisor}, positive to indicate the number of fraction digits to
2008         *            the right of the Decimal point and negative to indicate up-scaling with a power of ten
2009         * @param roundingMode
2010         *            the rounding mode to apply if the result needs to be rounded
2011         * @return <tt>round(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt>
2012         * @throws ArithmeticException
2013         *             if {@code unscaledDivisor==0} or if {@code roundingMode==UNNECESSARY} and rounding is necessary
2014         */
2015        Decimal<S> divideUnscaled(long unscaledDivisor, int scale, RoundingMode roundingMode);
2016
2017        /**
2018         * Returns a {@code Decimal} whose value is <tt>(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt>. The
2019         * result is rounded to the scale of this Decimal using the {@link RoundingMode} defined by the
2020         * {@code truncationPolicy} argument. The {@code truncationPolicy} also defines the {@link OverflowMode} to apply if
2021         * the operation causes an overflow.
2022         * <p>
2023         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2024         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2025         * the outcome of the division.
2026         * 
2027         * @param unscaledDivisor
2028         *            divisor value by which this {@code Decimal} is to be divided
2029         * @param scale
2030         *            the scale to apply to {@code unscaledDivisor}, positive to indicate the number of fraction digits to
2031         *            the right of the Decimal point and negative to indicate up-scaling with a power of ten
2032         * @param truncationPolicy
2033         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
2034         *            necessary or if an overflow occurs
2035         * @return <tt>round(this / (unscaledDivisor &times; 10<sup>-scale</sup>))</tt>
2036         * @throws ArithmeticException
2037         *             if {@code unscaledDivisor==0}, if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY}
2038         *             and rounding is necessary or if an overflow occurs and the policy declares
2039         *             {@link OverflowMode#CHECKED}
2040         */
2041        Decimal<S> divideUnscaled(long unscaledDivisor, int scale, TruncationPolicy truncationPolicy);
2042
2043        /**
2044         * Returns a {@code Decimal} whose value is <tt>(this / 10<sup>n</sup>)</tt> . The result is rounded to the
2045         * {@link #getScale() scale} of this Decimal using {@link RoundingMode#HALF_UP HALF_UP} rounding.
2046         * <p>
2047         * For negative <tt>n</tt> the division turns into a de-facto multiplication. If the multiplication causes an
2048         * overflow, the result is silently truncated.
2049         * <p>
2050         * The result of this operation is the same as for {@link #multiplyByPowerOfTen(int) multiplyByPowerOfTen(-n)}
2051         * (unless {@code n == } {@link Integer#MIN_VALUE}).
2052         * <p>
2053         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2054         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2055         * the outcome of the division.
2056         * 
2057         * @param n
2058         *            the exponent of the power-of-ten divisor by which this {@code Decimal} is to be divided
2059         * @return <tt>round<sub>HALF_UP</sub>(this / 10<sup>n</sup>)</tt>
2060         */
2061        Decimal<S> divideByPowerOfTen(int n);
2062
2063        /**
2064         * Returns a {@code Decimal} whose value is <tt>(this / 10<sup>n</sup>)</tt> . The result is rounded to the
2065         * {@link #getScale() scale} of this Decimal using the specified {@code roudningMode}.
2066         * <p>
2067         * For negative <tt>n</tt> the division turns into a de-facto multiplication. If the multiplication causes an
2068         * overflow, the result is silently truncated.
2069         * <p>
2070         * The result of this operation is the same as for {@link #multiplyByPowerOfTen(int, RoundingMode)
2071         * multiplyByPowerOfTen(-n, roundingMode)} (unless {@code n == } {@link Integer#MIN_VALUE}).
2072         * <p>
2073         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2074         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2075         * the outcome of the division.
2076         * 
2077         * @param n
2078         *            the exponent of the power-of-ten divisor by which this {@code Decimal} is to be divided
2079         * @param roundingMode
2080         *            the rounding mode to apply if the result needs to be rounded for the case {@code n > 0}
2081         * @return <tt>round(this / 10<sup>n</sup>)</tt>
2082         * @throws ArithmeticException
2083         *             if {@code n > 0} and {@code roundingMode==UNNECESSARY} and rounding is necessary
2084         */
2085        Decimal<S> divideByPowerOfTen(int n, RoundingMode roundingMode);
2086
2087        /**
2088         * Returns a {@code Decimal} whose value is <tt>(this / 10<sup>n</sup>)</tt> . The result is rounded to the
2089         * {@link #getScale() scale} of this Decimal using the {@link RoundingMode} specified by the
2090         * {@code truncationPolicy} argument.
2091         * <p>
2092         * For negative <tt>n</tt> the division turns into a de-facto multiplication and {@code truncationPolicy} defines
2093         * the {@link OverflowMode} to apply if an overflow occurs during the multiplication.
2094         * <p>
2095         * The result of this operation is the same as for {@link #multiplyByPowerOfTen(int, TruncationPolicy)
2096         * multiplyByPowerOfTen(-n, truncationPolicy)} (unless {@code n == } {@link Integer#MIN_VALUE}).
2097         * <p>
2098         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2099         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2100         * the outcome of the division.
2101         * 
2102         * @param n
2103         *            the exponent of the power-of-ten divisor by which this {@code Decimal} is to be divided
2104         * @param truncationPolicy
2105         *            the truncation policy specifying {@link RoundingMode} to apply if rounding is necessary when
2106         *            {@code n > 0} as well {@link OverflowMode} to use if {@code n < 0} and an overflow occurs during the
2107         *            de-facto multiplication
2108         * @return <tt>round(this / 10<sup>n</sup>)</tt>
2109         * @throws ArithmeticException
2110         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary when
2111         *             {@code n > 0}, or if an overflow occurs and the policy declares {@link OverflowMode#CHECKED} for the
2112         *             case {@code n < 0}
2113         */
2114        Decimal<S> divideByPowerOfTen(int n, TruncationPolicy truncationPolicy);
2115
2116        /**
2117         * Returns a {@code Decimal} whose value is {@code (this / divisor)} rounded down to the next integer. If the
2118         * division causes an overflow, the result is silently truncated.
2119         * <p>
2120         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2121         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2122         * the outcome of the division.
2123         *
2124         * @param divisor
2125         *            value by which this {@code Decimal} is to be divided.
2126         * @return The integer part of {@code (this / divisor)}.
2127         * @throws ArithmeticException
2128         *             if {@code divisor==0}
2129         * @see #divideToIntegralValue(Decimal, OverflowMode)
2130         * @see #divideToLongValue(Decimal)
2131         * @see #remainder(Decimal)
2132         */
2133        Decimal<S> divideToIntegralValue(Decimal<S> divisor);
2134
2135        /**
2136         * Returns a {@code Decimal} whose value is {@code (this / divisor)} rounded down to the next integer. The specified
2137         * {@code overflowMode} determines whether to truncate the result silently or to throw an exception if an overflow
2138         * occurs.
2139         * <p>
2140         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2141         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2142         * the outcome of the division.
2143         *
2144         * @param divisor
2145         *            value by which this {@code Decimal} is to be divided.
2146         * @param overflowMode
2147         *            the overflow mode to apply if the division leads to an overflow
2148         * @return The integer part of {@code (this / divisor)}.
2149         * @throws ArithmeticException
2150         *             if {@code divisor==0} or if {@code overflowMode==CHECKED} and an overflow occurs
2151         * @see #divideToIntegralValue(Decimal)
2152         * @see #divideToLongValue(Decimal)
2153         * @see #remainder(Decimal)
2154         */
2155        Decimal<S> divideToIntegralValue(Decimal<S> divisor, OverflowMode overflowMode);
2156
2157        /**
2158         * Returns a {@code Decimal} whose value {@code (this / divisor)} rounded down to the next {@code long} value. If
2159         * the division causes an overflow, the result is silently truncated.
2160         *
2161         * @param divisor
2162         *            value by which this {@code Decimal} is to be divided.
2163         * @return The integer part of {@code (this / divisor)} returned as {@code long}
2164         * @throws ArithmeticException
2165         *             if {@code divisor==0}
2166         * @see #divideToLongValue(Decimal, OverflowMode)
2167         * @see #divideToIntegralValue(Decimal)
2168         * @see #remainder(Decimal)
2169         */
2170        long divideToLongValue(Decimal<S> divisor);
2171
2172        /**
2173         * Returns a {@code Decimal} whose value {@code (this / divisor)} rounded down to the next {@code long} value. The
2174         * specified {@code overflowMode} determines whether to truncate the result silently or to throw an exception if an
2175         * overflow occurs.
2176         *
2177         * @param divisor
2178         *            value by which this {@code Decimal} is to be divided.
2179         * @param overflowMode
2180         *            the overflow mode to apply if the division leads to an overflow
2181         * @return The integer part of {@code (this / divisor)} returned as {@code long}
2182         * @throws ArithmeticException
2183         *             if {@code divisor==0} or if {@code overflowMode==CHECKED} and an overflow occurs
2184         * @see #divideToLongValue(Decimal)
2185         * @see #divideToIntegralValue(Decimal)
2186         * @see #remainder(Decimal)
2187         */
2188        long divideToLongValue(Decimal<S> divisor, OverflowMode overflowMode);
2189
2190        /**
2191         * Returns a two-element {@code Decimal} array containing the result of {@code divideToIntegralValue} followed by
2192         * the result of {@code remainder} on the two operands. If the division causes an overflow, the result is silently
2193         * truncated.
2194         * <p>
2195         * Note that if both the integer quotient and remainder are needed, this method is faster than using the
2196         * {@code divideToIntegralValue} and {@code remainder} methods separately because the division need only be carried
2197         * out once.
2198         *
2199         * @param divisor
2200         *            value by which this {@code Decimal} is to be divided, and the remainder computed.
2201         * @return a two element {@code Decimal} array: the quotient (the result of {@code divideToIntegralValue}) is the
2202         *         initial element and the remainder is the final element.
2203         * @throws ArithmeticException
2204         *             if {@code divisor==0}
2205         * @see #divideAndRemainder(Decimal, OverflowMode)
2206         * @see #divideToIntegralValue(Decimal)
2207         * @see #remainder(Decimal)
2208         */
2209        Decimal<S>[] divideAndRemainder(Decimal<S> divisor);
2210
2211        /**
2212         * Returns a two-element {@code Decimal} array containing the result of {@code divideToIntegralValue} followed by
2213         * the result of {@code remainder} on the two operands. The specified {@code overflowMode} determines whether to
2214         * truncate the result silently or to throw an exception if an overflow occurs.
2215         * <p>
2216         * Note that if both the integer quotient and remainder are needed, this method is faster than using the
2217         * {@code divideToIntegralValue} and {@code remainder} methods separately because the division need only be carried
2218         * out once.
2219         *
2220         * @param divisor
2221         *            value by which this {@code Decimal} is to be divided, and the remainder computed.
2222         * @param overflowMode
2223         *            the overflow mode to apply if the division leads to an overflow
2224         * @return a two element {@code Decimal} array: the quotient (the result of {@code divideToIntegralValue}) is the
2225         *         initial element and the remainder is the final element.
2226         * @throws ArithmeticException
2227         *             if {@code divisor==0} or if {@code overflowMode==CHECKED} and an overflow occurs
2228         * @see #divideAndRemainder(Decimal)
2229         * @see #divideToIntegralValue(Decimal)
2230         * @see #remainder(Decimal)
2231         */
2232        Decimal<S>[] divideAndRemainder(Decimal<S> divisor, OverflowMode overflowMode);
2233
2234        /**
2235         * Returns a {@code Decimal} whose value is {@code (this % divisor)}.
2236         * <p>
2237         * The remainder is given by {@code this.subtract(this.divideToIntegralValue(divisor).multiply(divisor))} . Note
2238         * that this is not the modulo operation (the result can be negative).
2239         * <p>
2240         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2241         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2242         * the outcome of the operation.
2243         *
2244         * @param divisor
2245         *            value by which this {@code Decimal} is to be divided.
2246         * @return {@code this % divisor}.
2247         * @throws ArithmeticException
2248         *             if {@code divisor==0}
2249         * @see #divideToIntegralValue(Decimal)
2250         * @see #divideAndRemainder(Decimal)
2251         */
2252        Decimal<S> remainder(Decimal<S> divisor);
2253
2254        // other arithmetic operations
2255
2256        /**
2257         * Returns a {@code Decimal} whose value is {@code (-this)}.
2258         * <p>
2259         * If an overflow occurs (which is true iff {@code this.unscaledValue()==Long.MIN_VALUE}) then the result is still
2260         * negative and numerically equal to {@code this} value.
2261         * <p>
2262         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2263         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2264         * the outcome of the division.
2265         * 
2266         * @return {@code -this}
2267         */
2268        Decimal<S> negate();
2269
2270        /**
2271         * Returns a {@code Decimal} whose value is {@code (-this)}.
2272         * <p>
2273         * The specified {@code overflowMode} determines whether to truncate the result silently or to throw an exception if
2274         * an overflow occurs (which is true iff {@code this.unscaledValue()==Long.MIN_VALUE}).
2275         * <p>
2276         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2277         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2278         * the outcome of the division.
2279         * 
2280         * @param overflowMode
2281         *            the overflow mode to apply
2282         * @return {@code -this}
2283         * @throws ArithmeticException
2284         *             if {@code overflowMode==CHECKED} and an overflow occurs (which is true iff
2285         *             {@code this.unscaledValue()==Long.MIN_VALUE})
2286         */
2287        Decimal<S> negate(OverflowMode overflowMode);
2288
2289        /**
2290         * Returns a {@code Decimal} whose value is the absolute value of this {@code Decimal}.
2291         * <p>
2292         * If an overflow occurs (which is true iff {@code this.unscaledValue()==Long.MIN_VALUE}) then the result is still
2293         * negative and numerically equal to {@code this} value.
2294         * <p>
2295         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2296         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2297         * the outcome of the division.
2298         * 
2299         * @return {@code abs(this)}
2300         */
2301        Decimal<S> abs();
2302
2303        /**
2304         * Returns a {@code Decimal} whose value is the absolute value of this {@code Decimal}.
2305         * <p>
2306         * The specified {@code overflowMode} determines whether to truncate the result silently or to throw an exception if
2307         * an overflow occurs (which is true iff {@code this.unscaledValue()==Long.MIN_VALUE}).
2308         * <p>
2309         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2310         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2311         * the outcome of the division.
2312         * 
2313         * @param overflowMode
2314         *            the overflow mode to apply
2315         * @return {@code abs(this)}
2316         * @throws ArithmeticException
2317         *             if {@code overflowMode==CHECKED} and an overflow occurs (which is true iff
2318         *             {@code this.unscaledValue()==Long.MIN_VALUE})
2319         */
2320        Decimal<S> abs(OverflowMode overflowMode);
2321
2322        /**
2323         * Returns a {@code Decimal} whose value is {@code (1 / this)}. The result is rounded to the {@link #getScale()
2324         * scale} of this Decimal using default {@link RoundingMode#HALF_UP HALF_UP} rounding. If the inversion causes an
2325         * overflow, the result is silently truncated.
2326         * <p>
2327         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2328         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2329         * the outcome of the inversion.
2330         * 
2331         * @return <tt>round<sub>HALF_UP</sub>(1 / this)</tt>
2332         * @throws ArithmeticException
2333         *             if {@code this==0}
2334         */
2335        Decimal<S> invert();
2336
2337        /**
2338         * Returns a {@code Decimal} whose value is {@code (1 / this)}. The result is rounded to the {@link #getScale()
2339         * scale} of this Decimal using the specified {@code roundingMode}. If the inversion causes an overflow, the result
2340         * is silently truncated.
2341         * <p>
2342         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2343         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2344         * the outcome of the inversion.
2345         * 
2346         * @param roundingMode
2347         *            the rounding mode to apply if the result needs to be rounded
2348         * @return {@code round(1 / this)}
2349         * @throws ArithmeticException
2350         *             if {@code this==0} or if {@code roundingMode==UNNECESSARY} and rounding is necessary
2351         */
2352        Decimal<S> invert(RoundingMode roundingMode);
2353
2354        /**
2355         * Returns a {@code Decimal} whose value is {@code (1 / this)}. The result is rounded to the {@link #getScale()
2356         * scale} of this Decimal using the {@link RoundingMode} specified by the {@code truncationPolicy} argument. The
2357         * {@code truncationPolicy} also defines the {@link OverflowMode} to apply if an overflow occurs during the invert
2358         * operation.
2359         * <p>
2360         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2361         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2362         * the outcome of the inversion.
2363         * 
2364         * @param truncationPolicy
2365         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
2366         *            necessary or if an overflow occurs
2367         * @return {@code round(1 / this)}
2368         * @throws ArithmeticException
2369         *             if {@code this==0}, if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding
2370         *             is necessary or if an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
2371         */
2372        Decimal<S> invert(TruncationPolicy truncationPolicy);
2373
2374        /**
2375         * Returns a {@code Decimal} whose value is <tt>(this<sup>2</sup>)</tt>. The result is rounded to the
2376         * {@link #getScale() scale} of this Decimal using default {@link RoundingMode#HALF_UP HALF_UP} rounding. If the
2377         * square operation causes an overflow, the result is silently truncated.
2378         * <p>
2379         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2380         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2381         * the outcome of the square operation.
2382         * 
2383         * @return <tt>round<sub>HALF_UP</sub>(this * this)</tt>
2384         */
2385        Decimal<S> square();
2386
2387        /**
2388         * Returns a {@code Decimal} whose value is <tt>(this<sup>2</sup>)</tt>. The result is rounded to the
2389         * {@link #getScale() scale} of this Decimal using the specified {@code roundingMode}. If the square operation
2390         * causes an overflow, the result is silently truncated.
2391         * <p>
2392         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2393         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2394         * the outcome of the square operation.
2395         * 
2396         * @param roundingMode
2397         *            the rounding mode to apply if the result needs to be rounded
2398         * @return {@code round(this * this)}
2399         * @throws ArithmeticException
2400         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
2401         */
2402        Decimal<S> square(RoundingMode roundingMode);
2403
2404        /**
2405         * Returns a {@code Decimal} whose value is <tt>(this<sup>2</sup>)</tt>. The result is rounded to the
2406         * {@link #getScale() scale} of this Decimal using the {@link RoundingMode} specified by the
2407         * {@code truncationPolicy} argument. The {@code truncationPolicy} also defines the {@link OverflowMode} to apply if
2408         * an overflow occurs during the square operation.
2409         * <p>
2410         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2411         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2412         * the outcome of the square operation.
2413         * 
2414         * @param truncationPolicy
2415         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
2416         *            necessary or if an overflow occurs
2417         * @return {@code round(this * this)}
2418         * @throws ArithmeticException
2419         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary or if
2420         *             an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
2421         */
2422        Decimal<S> square(TruncationPolicy truncationPolicy);
2423
2424        /**
2425         * Returns a {@code Decimal} whose value is the square root of {@code this} Decimal value. The result is rounded to
2426         * the {@link #getScale() scale} of this Decimal using default {@link RoundingMode#HALF_UP HALF_UP} rounding.
2427         * <p>
2428         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2429         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2430         * the outcome of the operation.
2431         * 
2432         * @return {@code sqrt(this)}
2433         * @throws ArithmeticException
2434         *             if {@code this < 0}
2435         */
2436        Decimal<S> sqrt();
2437
2438        /**
2439         * Returns a {@code Decimal} whose value is the square root of {@code this} Decimal value. The result is rounded to
2440         * the {@link #getScale() scale} of this Decimal using the specified {@code roundingMode}.
2441         * <p>
2442         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2443         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2444         * the outcome of the operation.
2445         * 
2446         * @param roundingMode
2447         *            the rounding mode to apply if the result needs to be rounded
2448         * @return {@code sqrt(this)}
2449         * @throws ArithmeticException
2450         *             if {@code this < 0} or if {@code roundingMode==UNNECESSARY} and rounding is necessary
2451         */
2452        Decimal<S> sqrt(RoundingMode roundingMode);
2453
2454        /**
2455         * Returns the signum function of this {@code Decimal}.
2456         * 
2457         * @return -1, 0, or 1 as the value of this {@code Decimal} is negative, zero, or positive.
2458         */
2459        int signum();
2460
2461        /**
2462         * Returns a {@code Decimal} whose value is {@code (this << n)}. The shift distance, {@code n}, may be negative, in
2463         * which case this method performs a right shift.
2464         * <p>
2465         * Computes <tt>floor(this * 2<sup>n</sup>)</tt>.
2466         * <p>
2467         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2468         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2469         * the outcome of the shift operation.
2470         *
2471         * @param n
2472         *            shift distance, in bits.
2473         * @return {@code this << n}
2474         * @see #shiftRight
2475         */
2476        Decimal<S> shiftLeft(int n);
2477
2478        /**
2479         * Returns a {@code Decimal} whose value is {@code (this << n)}. The shift distance, {@code n}, may be negative, in
2480         * which case this method performs a right shift.
2481         * <p>
2482         * Computes <tt>round(this * 2<sup>n</sup>)</tt> using the specified {@code roundingMode}.
2483         * <p>
2484         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2485         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2486         * the outcome of the shift operation.
2487         *
2488         * @param n
2489         *            shift distance, in bits.
2490         * @param roundingMode
2491         *            the rounding mode to use if truncation is involved for negative {@code n}, that is, for right shifts
2492         * @return {@code this << n}
2493         * @throws ArithmeticException
2494         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
2495         * @see #shiftRight
2496         */
2497        Decimal<S> shiftLeft(int n, RoundingMode roundingMode);
2498
2499        /**
2500         * Returns a {@code Decimal} whose value is {@code (this << n)}. The shift distance, {@code n}, may be negative, in
2501         * which case this method performs a right shift.
2502         * <p>
2503         * Computes <tt>round(this * 2<sup>n</sup>)</tt> using the {@link RoundingMode} specified by the
2504         * {@code truncationPolicy} argument.
2505         * <p>
2506         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2507         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2508         * the outcome of the shift operation.
2509         *
2510         * @param n
2511         *            shift distance, in bits.
2512         * @param truncationPolicy
2513         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
2514         *            necessary or if an overflow occurs
2515         * @return {@code this << n}
2516         * @throws ArithmeticException
2517         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary or if
2518         *             an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
2519         * @see #shiftRight
2520         */
2521        Decimal<S> shiftLeft(int n, TruncationPolicy truncationPolicy);
2522
2523        /**
2524         * Returns a BigInteger whose value is {@code (this >> n)}. Sign extension is performed. The shift distance,
2525         * {@code n}, may be negative, in which case this method performs a left shift.
2526         * <p>
2527         * Computes <tt>floor(this / 2<sup>n</sup>)</tt>.
2528         * <p>
2529         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2530         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2531         * the outcome of the shift operation.
2532         *
2533         * @param n
2534         *            shift distance, in bits.
2535         * @return {@code this >> n}
2536         * @see #shiftLeft
2537         */
2538        Decimal<S> shiftRight(int n);
2539
2540        /**
2541         * Returns a BigInteger whose value is {@code (this >> n)}. Sign extension is performed. The shift distance,
2542         * {@code n}, may be negative, in which case this method performs a left shift.
2543         * <p>
2544         * Computes <tt>round(this / 2<sup>n</sup>)</tt> using the specified {@code roundingMode}.
2545         * <p>
2546         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2547         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2548         * the outcome of the shift operation.
2549         *
2550         * @param n
2551         *            shift distance, in bits.
2552         * @param roundingMode
2553         *            the rounding mode to use if truncation is involved
2554         * @return {@code this >> n}
2555         * @see #shiftLeft
2556         * @throws ArithmeticException
2557         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
2558         */
2559        Decimal<S> shiftRight(int n, RoundingMode roundingMode);
2560
2561        /**
2562         * Returns a BigInteger whose value is {@code (this >> n)}. Sign extension is performed. The shift distance,
2563         * {@code n}, may be negative, in which case this method performs a left shift.
2564         * <p>
2565         * Computes <tt>round(this / 2<sup>n</sup>)</tt> using the {@link RoundingMode} specified by the
2566         * {@code truncationPolicy} argument.
2567         * <p>
2568         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2569         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2570         * the outcome of the shift operation.
2571         *
2572         * @param n
2573         *            shift distance, in bits.
2574         * @param truncationPolicy
2575         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
2576         *            necessary or if an overflow occurs
2577         * @return {@code this >> n}
2578         * @throws ArithmeticException
2579         *             if {@code truncationPolicy} defines {@link RoundingMode#UNNECESSARY} and rounding is necessary or if
2580         *             an overflow occurs and the policy declares {@link OverflowMode#CHECKED}
2581         * @see #shiftLeft
2582         */
2583        Decimal<S> shiftRight(int n, TruncationPolicy truncationPolicy);
2584
2585        /**
2586         * Returns a {@code Decimal} whose value is <tt>(this<sup>n</sup>)</tt> using default {@link RoundingMode#HALF_UP
2587         * HALF_UP} rounding.
2588         * <p>
2589         * The current implementation uses the core algorithm defined in ANSI standard X3.274-1996. For {@code n >= 0}, the
2590         * returned numerical value is within 1 ULP of the exact numerical value. No precision is guaranteed for
2591         * {@code n < 0} but the result is usually exact up to 10-20 ULP.
2592         * <p>
2593         * Properties of the X3.274-1996 algorithm are:
2594         * <ul>
2595         * <li>An {@code IllegalArgumentException} is thrown if {@code abs(n) > 999999999}</li>
2596         * <li>if {@code n} is zero, one is returned even if {@code this} is zero, otherwise
2597         * <ul>
2598         * <li>if {@code n} is positive, the result is calculated via the repeated squaring technique into a single
2599         * accumulator</li>
2600         * <li>if {@code n} is negative, the result is calculated as if {@code n} were positive; this value is then divided
2601         * into one</li>
2602         * <li>The final value from either the positive or negative case is then rounded using {@link RoundingMode#HALF_UP
2603         * HALF_UP} rounding</li>
2604         * </ul>
2605         * </li>
2606         * </ul>
2607         * <p>
2608         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2609         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2610         * the outcome of the shift operation.
2611         * 
2612         * @param n
2613         *            power to raise this {@code Decimal} to
2614         * @return <tt>this<sup>n</sup></tt> using the ANSI standard X3.274-1996 algorithm
2615         * @throws IllegalArgumentException
2616         *             if {@code abs(n) > 999999999}
2617         * @throws ArithmeticException
2618         *             if {@code n} is negative and {@code this} equals zero
2619         */
2620        Decimal<S> pow(int n);
2621
2622        /**
2623         * Returns a {@code Decimal} whose value is <tt>(this<sup>n</sup>)</tt> applying the specified {@code roundingMode}.
2624         * <p>
2625         * The current implementation uses the core algorithm defined in ANSI standard X3.274-1996. For {@code n >= 0}, the
2626         * returned numerical value is within 1 ULP of the exact numerical value; the result is actually exact for all
2627         * rounding modes other than HALF_UP, HALF_EVEN and HALF_DOWN. No precision is guaranteed for {@code n < 0} but the
2628         * result is usually exact up to 10-20 ULP.
2629         * <p>
2630         * Properties of the X3.274-1996 algorithm are:
2631         * <ul>
2632         * <li>An {@code IllegalArgumentException} is thrown if {@code abs(n) > 999999999}</li>
2633         * <li>if {@code n} is zero, one is returned even if {@code this} is zero, otherwise
2634         * <ul>
2635         * <li>if {@code n} is positive, the result is calculated via the repeated squaring technique into a single
2636         * accumulator</li>
2637         * <li>if {@code n} is negative, the result is calculated as if {@code n} were positive; this value is then divided
2638         * into one</li>
2639         * <li>The final value from either the positive or negative case is then rounded using the specified
2640         * {@code roundingMode}</li>
2641         * </ul>
2642         * </li>
2643         * </ul>
2644         * <p>
2645         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2646         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2647         * the outcome of the shift operation.
2648         * 
2649         * @param n
2650         *            power to raise this {@code Decimal} to
2651         * @param roundingMode
2652         *            the rounding mode to apply if rounding is necessary
2653         * @return <tt>this<sup>n</sup></tt> using the ANSI standard X3.274-1996 algorithm
2654         * @throws IllegalArgumentException
2655         *             if {@code abs(n) > 999999999}
2656         * @throws ArithmeticException
2657         *             if {@code n} is negative and {@code this} equals zero or if {@code roundingMode} equals
2658         *             {@link RoundingMode#UNNECESSARY} and rounding is necessary
2659         */
2660        Decimal<S> pow(int n, RoundingMode roundingMode);
2661
2662        /**
2663         * Returns a {@code Decimal} whose value is <tt>(this<sup>n</sup>)</tt> applying the {@link RoundingMode} specified
2664         * by {@code truncationPolicy}. The {@code truncationPolicy} argument also defines the {@link OverflowMode} to apply
2665         * if an overflow occurs during the power operation.
2666         * <p>
2667         * The current implementation uses the core algorithm defined in ANSI standard X3.274-1996. For {@code n >= 0}, the
2668         * returned numerical value is within 1 ULP of the exact numerical value; the result is actually exact for all
2669         * rounding modes other than HALF_UP, HALF_EVEN and HALF_DOWN. No precision is guaranteed for {@code n < 0} but the
2670         * result is usually exact up to 10-20 ULP.
2671         * <p>
2672         * Properties of the X3.274-1996 algorithm are:
2673         * <ul>
2674         * <li>An {@code IllegalArgumentException} is thrown if {@code abs(n) > 999999999}</li>
2675         * <li>if {@code n} is zero, one is returned even if {@code this} is zero, otherwise
2676         * <ul>
2677         * <li>if {@code n} is positive, the result is calculated via the repeated squaring technique into a single
2678         * accumulator</li>
2679         * <li>if {@code n} is negative, the result is calculated as if {@code n} were positive; this value is then divided
2680         * into one</li>
2681         * <li>The final value from either the positive or negative case is then rounded using the {@link RoundingMode}
2682         * specified by {@code truncationPolicy}</li>
2683         * </ul>
2684         * </li>
2685         * </ul>
2686         * <p>
2687         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2688         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2689         * the outcome of the shift operation.
2690         * 
2691         * @param n
2692         *            power to raise this {@code Decimal} to
2693         * @param truncationPolicy
2694         *            the truncation policy specifying {@link RoundingMode} and {@link OverflowMode} to apply if rounding is
2695         *            necessary or if an overflow occurs
2696         * @return <tt>this<sup>n</sup></tt> using the ANSI standard X3.274-1996 algorithm
2697         * @throws IllegalArgumentException
2698         *             if {@code abs(n) > 999999999}
2699         * @throws ArithmeticException
2700         *             if {@code n} is negative and {@code this} equals zero; if {@code truncationPolicy} defines
2701         *             {@link RoundingMode#UNNECESSARY} and rounding is necessary or if an overflow occurs and the policy
2702         *             declares {@link OverflowMode#CHECKED}
2703         */
2704        Decimal<S> pow(int n, TruncationPolicy truncationPolicy);
2705
2706        // compare and related methods
2707
2708        /**
2709         * Compares two {@code Decimal} objects numerically.
2710         * 
2711         * @param other
2712         *            {@code Decimal} to which this {@code Decimal} is to be compared
2713         * @return the value {@code 0} if this {@code Decimal} is equal to the argument {@code Decimal}; a value less than
2714         *         {@code 0} if this {@code Decimal} is numerically less than the argument {@code Decimal}; and a value
2715         *         greater than {@code 0} if this {@code Decimal} is numerically greater than the argument {@code Decimal}
2716         */
2717        @Override
2718        int compareTo(Decimal<S> other);
2719
2720        /**
2721         * Compares this {@code Decimal} with the specified {@code Decimal} and returns true if the two are numerically
2722         * equal.
2723         * <p>
2724         * Returns true iff {@link #compareTo(Decimal)} returns 0.
2725         * 
2726         * @param other
2727         *            {@code Decimal} to which this {@code Decimal} is to be compared
2728         * @return true this {@code Decimal} is numerically equal to {@code other} and false otherwise
2729         */
2730        boolean isEqualTo(Decimal<S> other);
2731
2732        /**
2733         * Compares this {@code Decimal} with the specified {@code Decimal} and returns true if this Decimal is numerically
2734         * greater than {@code other}.
2735         * <p>
2736         * Returns true iff {@link #compareTo(Decimal)} returns a value greater than 0.
2737         * 
2738         * @param other
2739         *            {@code Decimal} to which this {@code Decimal} is to be compared
2740         * @return true if {@code this > other}
2741         */
2742        boolean isGreaterThan(Decimal<S> other);
2743
2744        /**
2745         * Compares this {@code Decimal} with the specified {@code Decimal} and returns true if this Decimal is numerically
2746         * greater than or equal to {@code other}.
2747         * <p>
2748         * Returns true iff {@link #compareTo(Decimal)} returns a non-negative value.
2749         * 
2750         * @param other
2751         *            {@code Decimal} to which this {@code Decimal} is to be compared
2752         * @return true if {@code this >= other}
2753         */
2754        boolean isGreaterThanOrEqualTo(Decimal<S> other);
2755
2756        /**
2757         * Compares this {@code Decimal} with the specified {@code Decimal} and returns true if this Decimal is numerically
2758         * less than {@code other}.
2759         * <p>
2760         * Returns true iff {@link #compareTo(Decimal)} returns a negative value.
2761         * 
2762         * @param other
2763         *            {@code Decimal} to which this {@code Decimal} is to be compared.
2764         * @return true if {@code this < other}
2765         */
2766        boolean isLessThan(Decimal<S> other);
2767
2768        /**
2769         * Compares this {@code Decimal} with the specified {@code Decimal} and returns true if this Decimal is numerically
2770         * less than or equal to {@code other}.
2771         * <p>
2772         * Returns true iff {@link #compareTo(Decimal)} returns a non-positive value.
2773         * 
2774         * @param other
2775         *            {@code Decimal} to which this {@code Decimal} is to be compared
2776         * @return true if {@code this <= other}
2777         */
2778        boolean isLessThanOrEqualTo(Decimal<S> other);
2779
2780        /**
2781         * Returns the minimum of this {@code Decimal} and {@code val}.
2782         *
2783         * @param val
2784         *            value with which the minimum is to be computed.
2785         * @return the {@code Decimal} whose value is the lesser of this {@code Decimal} and {@code val}. If they are equal,
2786         *         as defined by the {@link #compareTo(Decimal) compareTo} method, {@code this} is returned.
2787         * @see #compareTo(Decimal)
2788         */
2789        Decimal<S> min(Decimal<S> val);
2790
2791        /**
2792         * Returns the maximum of this {@code Decimal} and {@code val}.
2793         *
2794         * @param val
2795         *            value with which the maximum is to be computed.
2796         * @return the {@code Decimal} whose value is the greater of this {@code Decimal} and {@code val}. If they are
2797         *         equal, as defined by the {@link #compareTo(Decimal) compareTo} method, {@code this} is returned.
2798         * @see #compareTo(Decimal)
2799         */
2800        Decimal<S> max(Decimal<S> val);
2801
2802        /**
2803         * Returns the average of this {@code Decimal} and {@code val}. The result is rounded to the {@link #getScale()
2804         * scale} of this Decimal using default {@link RoundingMode#HALF_UP HALF_UP} rounding. The method is much more
2805         * efficient than an addition and subsequent long division and is guaranteed not to overflow.
2806         * <p>
2807         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2808         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2809         * the outcome of the average operation.
2810         *
2811         * @param val
2812         *            value with which the average is to be computed.
2813         * @return <tt>round<sub>HALF_UP</sub>((this + val) / 2)</tt>
2814         */
2815        Decimal<S> avg(Decimal<S> val);
2816
2817        /**
2818         * Returns the average of this {@code Decimal} and {@code val}. The result is rounded to the {@link #getScale()
2819         * scale} of this Decimal using the specified {@code roundingMode}. The method is much more efficient than an
2820         * addition and subsequent long division and is guaranteed not to overflow.
2821         * <p>
2822         * The returned value is a new instance if this Decimal is an {@link ImmutableDecimal}. If it is a
2823         * {@link MutableDecimal} then its internal state is altered and {@code this} is returned as result now representing
2824         * the outcome of the average operation.
2825         *
2826         * @param val
2827         *            value with which the average is to be computed.
2828         * @param roundingMode
2829         *            the rounding mode to use if rounding is necessary
2830         * @return {@code round((this + val) / 2)}
2831         * @throws ArithmeticException
2832         *             if {@code roundingMode==UNNECESSARY} and rounding is necessary
2833         */
2834        Decimal<S> avg(Decimal<S> val, RoundingMode roundingMode);
2835
2836        /**
2837         * Returns true if this {@code Decimal} is zero.
2838         * 
2839         * @return true if {@code this == 0}
2840         */
2841        boolean isZero();
2842
2843        /**
2844         * Returns true if this {@code Decimal} is one.
2845         * 
2846         * @return true if {@code this == 1}
2847         */
2848        boolean isOne();
2849
2850        /**
2851         * Returns true if this {@code Decimal} is minus one.
2852         * 
2853         * @return true if {@code this == -1}
2854         */
2855        boolean isMinusOne();
2856
2857        /**
2858         * Returns true if this {@code Decimal} is equal to the smallest positive number representable by a Decimal with the
2859         * current {@link #getScale() scale}.
2860         * 
2861         * @return true if {@code unscaledValue() == 1}
2862         */
2863        boolean isUlp();
2864
2865        /**
2866         * Returns true if this {@code Decimal} is strictly positive.
2867         * 
2868         * @return true if {@code this > 0}
2869         */
2870        boolean isPositive();
2871
2872        /**
2873         * Returns true if this {@code Decimal} is not negative.
2874         * 
2875         * @return true if {@code this >= 0}
2876         */
2877        boolean isNonNegative();
2878
2879        /**
2880         * Returns true if this {@code Decimal} is negative.
2881         * 
2882         * @return true if {@code this < 0}
2883         */
2884        boolean isNegative();
2885
2886        /**
2887         * Returns true if this {@code Decimal} is not positive.
2888         * 
2889         * @return true if {@code this <= 0}
2890         */
2891        boolean isNonPositive();
2892
2893        /**
2894         * Returns true if this {@code Decimal} number is integral, or equivalently if its {@link #fractionalPart()
2895         * fractional part} is zero.
2896         * 
2897         * @return true if {@code this} is an integer number
2898         */
2899        boolean isIntegral();
2900
2901        /**
2902         * Returns true if the {@link #integralPart() integral part} of this {@code Decimal} number is zero.
2903         * 
2904         * @return true if {@code -1 < this < 1}
2905         */
2906        boolean isIntegralPartZero();
2907
2908        /**
2909         * Returns true if this {@code Decimal} is between zero (inclusive) and one (exclusive). The result value is true if
2910         * and only if this {@code Decimal} is not negative and its {@link #integralPart() integral part} is zero.
2911         * 
2912         * @return true if {@code 0 <= this < 1}
2913         */
2914        boolean isBetweenZeroAndOne();
2915
2916        /**
2917         * Returns true if this {@code Decimal} is between zero (inclusive) and minus one (exclusive). The result value is
2918         * true if and only if this {@code Decimal} is not positive and its {@link #integralPart() integral part} is zero.
2919         * 
2920         * @return true if {@code -1 < this <= 0}
2921         */
2922        boolean isBetweenZeroAndMinusOne();
2923
2924        /**
2925         * Compares this {@code Decimal} with the specified {@code Decimal}. Two {@code Decimal} objects that are equal in
2926         * value but have a different scale (like 2.0 and 2.00) are considered equal by this method.
2927         *
2928         * @param other
2929         *            {@code Decimal} to which this {@code Decimal} is to be compared.
2930         * @return the value {@code 0} if this {@code Decimal} is equal to the argument {@code Decimal}; a value less than
2931         *         {@code 0} if this {@code Decimal} is numerically less than the argument {@code Decimal}; and a value
2932         *         greater than {@code 0} if this {@code Decimal} is numerically greater than the argument {@code Decimal}
2933         * @see #isEqualToNumerically(Decimal)
2934         * @see #compareTo(Decimal)
2935         */
2936        int compareToNumerically(Decimal<?> other);
2937
2938        /**
2939         * Compares this {@code Decimal} with the specified {@code Decimal} and returns true if the two are numerically
2940         * equal. Two {@code Decimal} objects that are equal in value but have a different scale (like 2.0 and 2.00) are
2941         * considered equal by this method as opposed to the {@link #equals(Object) equals} method which requires identical
2942         * scales of the compared values.
2943         * <p>
2944         * Returns true iff {@link #compareToNumerically(Decimal)} returns 0.
2945         *
2946         * @param other
2947         *            {@code Decimal} to which this {@code Decimal} is to be compared.
2948         * @return true if this {@code Decimal} is numerically equal to {@code other} and false otherwise.
2949         * @see #compareToNumerically(Decimal)
2950         * @see #compareTo(Decimal)
2951         */
2952        boolean isEqualToNumerically(Decimal<?> other);
2953
2954        // finally some basic object methods plus equals
2955
2956        /**
2957         * Returns a hash code for this {@code Decimal}. The hash code is calculated from {@link #getScale() scale} and
2958         * {@link #unscaledValue() unscaled value}.
2959         * 
2960         * @return a hash code value for this object
2961         */
2962        @Override
2963        int hashCode();
2964
2965        /**
2966         * Compares this Decimal to the specified object. The result is {@code true} if and only if the argument is a
2967         * {@code Decimal} value with the same {@link #getScale() scale} and {@link #unscaledValue() unscaled value} as this
2968         * Decimal.
2969         * 
2970         * @param obj
2971         *            the object to compare with
2972         * @return {@code true} if the argument is a {@code Decimal} object that contains the same value and scale as this
2973         *         object; {@code false} otherwise
2974         * 
2975         * @see #isEqualTo(Decimal)
2976         * @see #isEqualToNumerically(Decimal)
2977         * @see #hashCode()
2978         */
2979        @Override
2980        boolean equals(Object obj);
2981
2982        /**
2983         * Returns a string representation of this {@code Decimal} object as fixed-point Decimal always showing all Decimal
2984         * places (also trailing zeros) and a leading sign character if negative.
2985         * 
2986         * @return a {@code String} Decimal representation of this {@code Decimal} object with all the fraction digits
2987         *         (including trailing zeros)
2988         */
2989        @Override
2990        String toString();
2991}