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.RoundingMode;
027
028import org.decimal4j.scale.ScaleMetrics;
029import org.decimal4j.truncate.OverflowMode;
030import org.decimal4j.truncate.TruncationPolicy;
031
032/**
033 * Interface implemented by immutable {@link Decimal} classes of different
034 * scales. Immutable Decimals allocate a new Decimals instance for results of
035 * arithmetic operations.
036 * <p>
037 * Consider also {@link MutableDecimal} descendants especially for chained
038 * operations.
039 * <p>
040 * Immutable Decimals are thread safe.
041 * 
042 * @param <S>
043 *            the scale metrics type associated with this Decimal
044 */
045public interface ImmutableDecimal<S extends ScaleMetrics> extends Decimal<S> {
046
047        /**
048         * Returns the minimum of this {@code Decimal} and {@code val}.
049         *
050         * @param val
051         *            value with which the minimum is to be computed.
052         * @return the {@code Decimal} whose value is the lesser of this
053         *         {@code Decimal} and {@code val}. If they are equal, as defined by
054         *         the {@link #compareTo(Decimal) compareTo} method, {@code this} is
055         *         returned.
056         * @see #compareTo(Decimal)
057         */
058        ImmutableDecimal<S> min(ImmutableDecimal<S> val);
059
060        /**
061         * Returns the maximum of this {@code Decimal} and {@code val}.
062         *
063         * @param val
064         *            value with which the maximum is to be computed.
065         * @return the {@code Decimal} whose value is the greater of this
066         *         {@code Decimal} and {@code val}. If they are equal, as defined by
067         *         the {@link #compareTo(Decimal) compareTo} method, {@code this} is
068         *         returned.
069         * @see #compareTo(Decimal)
070         */
071        ImmutableDecimal<S> max(ImmutableDecimal<S> val);
072
073        //override some methods with specialized return type
074
075        @Override
076        ImmutableDecimal<S> integralPart();
077
078        @Override
079        ImmutableDecimal<S> fractionalPart();
080
081        @Override
082        ImmutableDecimal<S> round(int precision);
083
084        @Override
085        ImmutableDecimal<S> round(int precision, RoundingMode roundingMode);
086
087        @Override
088        ImmutableDecimal<S> round(int precision, TruncationPolicy truncationPolicy);
089
090        @Override
091        ImmutableDecimal<?> scale(int scale);
092
093        @SuppressWarnings("hiding")
094        @Override
095        <S extends ScaleMetrics> ImmutableDecimal<S> scale(S scaleMetrics);
096
097        @Override
098        ImmutableDecimal<?> scale(int scale, RoundingMode roundingMode);
099
100        @SuppressWarnings("hiding")
101        @Override
102        <S extends ScaleMetrics> ImmutableDecimal<S> scale(S scaleMetrics, RoundingMode roundingMode);
103
104        @Override
105        ImmutableDecimal<S> add(Decimal<S> augend);
106
107        @Override
108        ImmutableDecimal<S> add(Decimal<S> augend, OverflowMode overflowMode);
109
110        @Override
111        ImmutableDecimal<S> add(Decimal<?> augend, RoundingMode roundingMode);
112
113        @Override
114        ImmutableDecimal<S> add(Decimal<?> augend, TruncationPolicy truncationPolicy);
115
116        @Override
117        ImmutableDecimal<S> add(long augend);
118
119        @Override
120        ImmutableDecimal<S> add(long augend, OverflowMode overflowMode);
121
122        @Override
123        ImmutableDecimal<S> add(double augend);
124
125        @Override
126        ImmutableDecimal<S> add(double augend, RoundingMode roundingMode);
127
128        @Override
129        ImmutableDecimal<S> addUnscaled(long unscaledAugend);
130
131        @Override
132        ImmutableDecimal<S> addUnscaled(long unscaledAugend, OverflowMode overflowMode);
133
134        @Override
135        ImmutableDecimal<S> addUnscaled(long unscaledAugend, int scale);
136
137        @Override
138        ImmutableDecimal<S> addUnscaled(long unscaledAugend, int scale, RoundingMode roundingMode);
139
140        @Override
141        ImmutableDecimal<S> addUnscaled(long unscaledAugend, int scale, TruncationPolicy truncationPolicy);
142
143        @Override
144        ImmutableDecimal<S> addSquared(Decimal<S> value);
145
146        @Override
147        ImmutableDecimal<S> addSquared(Decimal<S> value, RoundingMode roundingMode);
148
149        @Override
150        ImmutableDecimal<S> addSquared(Decimal<S> value, TruncationPolicy truncationPolicy);
151
152        @Override
153        ImmutableDecimal<S> subtract(Decimal<S> subtrahend);
154
155        @Override
156        ImmutableDecimal<S> subtract(Decimal<S> subtrahend, OverflowMode overflowMode);
157
158        @Override
159        ImmutableDecimal<S> subtract(Decimal<?> subtrahend, RoundingMode roundingMode);
160
161        @Override
162        ImmutableDecimal<S> subtract(Decimal<?> subtrahend, TruncationPolicy truncationPolicy);
163
164        @Override
165        ImmutableDecimal<S> subtract(long subtrahend);
166
167        @Override
168        ImmutableDecimal<S> subtract(long subtrahend, OverflowMode overflowMode);
169
170        @Override
171        ImmutableDecimal<S> subtract(double subtrahend);
172
173        @Override
174        ImmutableDecimal<S> subtract(double subtrahend, RoundingMode roundingMode);
175
176        @Override
177        ImmutableDecimal<S> subtractUnscaled(long unscaledSubtrahend);
178
179        @Override
180        ImmutableDecimal<S> subtractUnscaled(long unscaledSubtrahend, OverflowMode overflowMode);
181
182        @Override
183        ImmutableDecimal<S> subtractUnscaled(long unscaledSubtrahend, int scale);
184
185        @Override
186        ImmutableDecimal<S> subtractUnscaled(long unscaledSubtrahend, int scale, RoundingMode roundingMode);
187
188        @Override
189        ImmutableDecimal<S> subtractUnscaled(long unscaledSubtrahend, int scale, TruncationPolicy truncationPolicy);
190
191        @Override
192        ImmutableDecimal<S> subtractSquared(Decimal<S> value);
193
194        @Override
195        ImmutableDecimal<S> subtractSquared(Decimal<S> value, RoundingMode roundingMode);
196
197        @Override
198        ImmutableDecimal<S> subtractSquared(Decimal<S> value, TruncationPolicy truncationPolicy);
199
200        @Override
201        ImmutableDecimal<S> multiply(Decimal<S> multiplicand);
202
203        @Override
204        ImmutableDecimal<S> multiply(Decimal<S> multiplicand, RoundingMode roundingMode);
205
206        @Override
207        ImmutableDecimal<S> multiply(Decimal<S> multiplicand, TruncationPolicy truncationPolicy);
208
209        @Override
210        ImmutableDecimal<S> multiplyBy(Decimal<?> multiplicand);
211
212        @Override
213        ImmutableDecimal<S> multiplyBy(Decimal<?> multiplicand, RoundingMode roundingMode);
214
215        @Override
216        ImmutableDecimal<S> multiplyBy(Decimal<?> multiplicand, TruncationPolicy truncationPolicy);
217
218        @Override
219        ImmutableDecimal<?> multiplyExact(Decimal<?> multiplicand);
220
221        @Override
222        ImmutableDecimal<S> multiply(long multiplicand);
223
224        @Override
225        ImmutableDecimal<S> multiply(long multiplicand, OverflowMode overflowMode);
226
227        @Override
228        ImmutableDecimal<S> multiply(double multiplicand);
229
230        @Override
231        ImmutableDecimal<S> multiply(double multiplicand, RoundingMode roundingMode);
232
233        @Override
234        ImmutableDecimal<S> multiplyUnscaled(long unscaledMultiplicand);
235
236        @Override
237        ImmutableDecimal<S> multiplyUnscaled(long unscaledMultiplicand, RoundingMode roundingMode);
238
239        @Override
240        ImmutableDecimal<S> multiplyUnscaled(long unscaledMultiplicand, TruncationPolicy truncationPolicy);
241
242        @Override
243        ImmutableDecimal<S> multiplyUnscaled(long unscaledMultiplicand, int scale);
244
245        @Override
246        ImmutableDecimal<S> multiplyUnscaled(long unscaledMultiplicand, int scale, RoundingMode roundingMode);
247
248        @Override
249        ImmutableDecimal<S> multiplyUnscaled(long unscaledMultiplicand, int scale, TruncationPolicy truncationPolicy);
250
251        @Override
252        ImmutableDecimal<S> multiplyByPowerOfTen(int n);
253
254        @Override
255        ImmutableDecimal<S> multiplyByPowerOfTen(int n, RoundingMode roundingMode);
256
257        @Override
258        ImmutableDecimal<S> multiplyByPowerOfTen(int n, TruncationPolicy truncationPolicy);
259
260        @Override
261        ImmutableDecimal<S> divide(Decimal<S> divisor);
262
263        @Override
264        ImmutableDecimal<S> divide(Decimal<S> divisor, RoundingMode roundingMode);
265
266        @Override
267        ImmutableDecimal<S> divide(Decimal<S> divisor, TruncationPolicy truncationPolicy);
268
269        @Override
270        ImmutableDecimal<S> divideBy(Decimal<?> divisor);
271
272        @Override
273        ImmutableDecimal<S> divideBy(Decimal<?> divisor, RoundingMode roundingMode);
274
275        @Override
276        ImmutableDecimal<S> divideBy(Decimal<?> divisor, TruncationPolicy truncationPolicy);
277
278        @Override
279        ImmutableDecimal<S> divideTruncate(Decimal<S> divisor);
280
281        @Override
282        ImmutableDecimal<S> divideExact(Decimal<S> divisor);
283
284        @Override
285        ImmutableDecimal<S> divide(long divisor);
286
287        @Override
288        ImmutableDecimal<S> divide(long divisor, RoundingMode roundingMode);
289
290        @Override
291        ImmutableDecimal<S> divide(long divisor, TruncationPolicy truncationPolicy);
292
293        @Override
294        ImmutableDecimal<S> divide(double divisor);
295
296        @Override
297        ImmutableDecimal<S> divide(double divisor, RoundingMode roundingMode);
298
299        @Override
300        ImmutableDecimal<S> divideUnscaled(long unscaledDivisor);
301
302        @Override
303        ImmutableDecimal<S> divideUnscaled(long unscaledDivisor, RoundingMode roundingMode);
304
305        @Override
306        ImmutableDecimal<S> divideUnscaled(long unscaledDivisor, TruncationPolicy truncationPolicy);
307
308        @Override
309        ImmutableDecimal<S> divideUnscaled(long unscaledDivisor, int scale);
310
311        @Override
312        ImmutableDecimal<S> divideUnscaled(long unscaledDivisor, int scale, RoundingMode roundingMode);
313
314        @Override
315        ImmutableDecimal<S> divideUnscaled(long unscaledDivisor, int scale, TruncationPolicy truncationPolicy);
316
317        @Override
318        ImmutableDecimal<S> divideByPowerOfTen(int n);
319
320        @Override
321        ImmutableDecimal<S> divideByPowerOfTen(int n, RoundingMode roundingMode);
322
323        @Override
324        ImmutableDecimal<S> divideByPowerOfTen(int n, TruncationPolicy truncationPolicy);
325
326        @Override
327        ImmutableDecimal<S> divideToIntegralValue(Decimal<S> divisor);
328
329        @Override
330        ImmutableDecimal<S> divideToIntegralValue(Decimal<S> divisor, OverflowMode overflowMode);
331
332        @Override
333        ImmutableDecimal<S>[] divideAndRemainder(Decimal<S> divisor);
334
335        @Override
336        ImmutableDecimal<S>[] divideAndRemainder(Decimal<S> divisor, OverflowMode overflowMode);
337
338        @Override
339        ImmutableDecimal<S> remainder(Decimal<S> divisor);
340
341        @Override
342        ImmutableDecimal<S> negate();
343
344        @Override
345        ImmutableDecimal<S> negate(OverflowMode overflowMode);
346
347        @Override
348        ImmutableDecimal<S> abs();
349
350        @Override
351        ImmutableDecimal<S> abs(OverflowMode overflowMode);
352
353        @Override
354        ImmutableDecimal<S> invert();
355
356        @Override
357        ImmutableDecimal<S> invert(RoundingMode roundingMode);
358
359        @Override
360        ImmutableDecimal<S> invert(TruncationPolicy truncationPolicy);
361
362        @Override
363        ImmutableDecimal<S> square();
364
365        @Override
366        ImmutableDecimal<S> square(RoundingMode roundingMode);
367
368        @Override
369        ImmutableDecimal<S> square(TruncationPolicy truncationPolicy);
370
371        @Override
372        ImmutableDecimal<S> sqrt();
373
374        @Override
375        ImmutableDecimal<S> sqrt(RoundingMode roundingMode);
376
377        @Override
378        ImmutableDecimal<S> shiftLeft(int n);
379
380        @Override
381        ImmutableDecimal<S> shiftLeft(int n, RoundingMode roundingMode);
382
383        @Override
384        ImmutableDecimal<S> shiftLeft(int n, TruncationPolicy truncationPolicy);
385
386        @Override
387        ImmutableDecimal<S> shiftRight(int n);
388
389        @Override
390        ImmutableDecimal<S> shiftRight(int n, RoundingMode roundingMode);
391
392        @Override
393        ImmutableDecimal<S> shiftRight(int n, TruncationPolicy truncationPolicy);
394
395        @Override
396        ImmutableDecimal<S> pow(int n);
397
398        @Override
399        ImmutableDecimal<S> pow(int n, RoundingMode roundingMode);
400
401        @Override
402        ImmutableDecimal<S> pow(int n, TruncationPolicy truncationPolicy);
403        
404        @Override
405        ImmutableDecimal<S> avg(Decimal<S> val);
406
407        @Override
408        ImmutableDecimal<S> avg(Decimal<S> val, RoundingMode roundingMode);
409}