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.exact;
025
026import java.util.Objects;
027
028import org.decimal4j.api.Decimal;
029import org.decimal4j.immutable.Decimal0f;
030import org.decimal4j.immutable.Decimal1f;
031import org.decimal4j.immutable.Decimal2f;
032import org.decimal4j.immutable.Decimal3f;
033import org.decimal4j.immutable.Decimal4f;
034import org.decimal4j.immutable.Decimal5f;
035import org.decimal4j.immutable.Decimal6f;
036import org.decimal4j.immutable.Decimal7f;
037import org.decimal4j.immutable.Decimal11f;
038import org.decimal4j.immutable.Decimal12f;
039import org.decimal4j.immutable.Decimal13f;
040import org.decimal4j.immutable.Decimal14f;
041import org.decimal4j.immutable.Decimal15f;
042import org.decimal4j.immutable.Decimal16f;
043import org.decimal4j.immutable.Decimal17f;
044import org.decimal4j.immutable.Decimal18f;
045import org.decimal4j.mutable.MutableDecimal0f;
046import org.decimal4j.mutable.MutableDecimal1f;
047import org.decimal4j.mutable.MutableDecimal2f;
048import org.decimal4j.mutable.MutableDecimal3f;
049import org.decimal4j.mutable.MutableDecimal4f;
050import org.decimal4j.mutable.MutableDecimal5f;
051import org.decimal4j.mutable.MutableDecimal6f;
052import org.decimal4j.mutable.MutableDecimal7f;
053import org.decimal4j.scale.Scale11f;
054
055/**
056 * A {@code Multipliable11f} encapsulates a Decimal of scale 11 and facilitates
057 * exact typed multiplication. The multipliable object acts as first factor in the multiplication
058 * and provides a set of overloaded methods for different scales. Each one of those methods 
059 * delivers a different result scale which represents the appropriate scale for the product of
060 * an exact multiplication.
061 * <p>
062 * A {@code Multipliable11f} object is returned by {@link Decimal11f#multiplyExact()},
063 * hence an exact typed multiplication can be written as:
064 * <pre>
065 * Decimal11f value = ... //some value
066 * Decimal13f product = value.multiplyExact().by(Decimal2f.FIVE);
067 * </pre>
068 */
069public final class Multipliable11f {
070        
071        private final Decimal<Scale11f> value;
072        
073        /**
074         * Constructor with Decimal value to be encapsulated.
075         * @param value the decimal value to be wrapped as a multipliable object
076         */
077        public Multipliable11f(Decimal<Scale11f> value) {
078                this.value = Objects.requireNonNull(value, "value cannot be null");
079        }
080        
081        /**
082         * Returns the value underlying this Multipliable11f.
083         * @return the Decimal value wrapped by this multipliable object
084         */
085        public Decimal<Scale11f> getValue() {
086                return value;
087        }
088
089        /**
090         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
091         * result is exact and has scale 11 which is the sum of the scales 
092         * of the Decimal that this multipliable object represents and the scale of
093         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
094         * product is out of the possible range for a {@code Decimal11f}.
095         * <p>
096         * Note that the result is <i>always</i> a new instance.
097         * 
098         * @param factor
099         *            the factor to multiply with the Decimal that this multipliable represents
100         * @return <tt>(this * factor)</tt>
101         * @throws ArithmeticException
102         *             if an overflow occurs and product is out of the possible
103         *             range for a {@code Decimal11f}
104         */
105        public Decimal11f by(Decimal0f factor) {
106                return Decimal11f.valueOf(this.value.multiplyExact(factor));
107        }
108        /**
109         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
110         * result is exact and has scale 11 which is the sum of the scales 
111         * of the Decimal that this multipliable object represents and the scale of
112         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
113         * product is out of the possible range for a {@code Decimal11f}.
114         * <p>
115         * Note that the result is <i>always</i> a new instance.
116         * 
117         * @param factor
118         *            the factor to multiply with the Decimal that this multipliable represents
119         * @return <tt>(this * factor)</tt>
120         * @throws ArithmeticException
121         *             if an overflow occurs and product is out of the possible
122         *             range for a {@code Decimal11f}
123         */
124        public Decimal11f by(MutableDecimal0f factor) {
125                return Decimal11f.valueOf(this.value.multiplyExact(factor));
126        }
127
128        /**
129         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
130         * result is exact and has scale 12 which is the sum of the scales 
131         * of the Decimal that this multipliable object represents and the scale of
132         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
133         * product is out of the possible range for a {@code Decimal12f}.
134         * <p>
135         * Note that the result is <i>always</i> a new instance.
136         * 
137         * @param factor
138         *            the factor to multiply with the Decimal that this multipliable represents
139         * @return <tt>(this * factor)</tt>
140         * @throws ArithmeticException
141         *             if an overflow occurs and product is out of the possible
142         *             range for a {@code Decimal12f}
143         */
144        public Decimal12f by(Decimal1f factor) {
145                return Decimal12f.valueOf(this.value.multiplyExact(factor));
146        }
147        /**
148         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
149         * result is exact and has scale 12 which is the sum of the scales 
150         * of the Decimal that this multipliable object represents and the scale of
151         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
152         * product is out of the possible range for a {@code Decimal12f}.
153         * <p>
154         * Note that the result is <i>always</i> a new instance.
155         * 
156         * @param factor
157         *            the factor to multiply with the Decimal that this multipliable represents
158         * @return <tt>(this * factor)</tt>
159         * @throws ArithmeticException
160         *             if an overflow occurs and product is out of the possible
161         *             range for a {@code Decimal12f}
162         */
163        public Decimal12f by(MutableDecimal1f factor) {
164                return Decimal12f.valueOf(this.value.multiplyExact(factor));
165        }
166
167        /**
168         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
169         * result is exact and has scale 13 which is the sum of the scales 
170         * of the Decimal that this multipliable object represents and the scale of
171         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
172         * product is out of the possible range for a {@code Decimal13f}.
173         * <p>
174         * Note that the result is <i>always</i> a new instance.
175         * 
176         * @param factor
177         *            the factor to multiply with the Decimal that this multipliable represents
178         * @return <tt>(this * factor)</tt>
179         * @throws ArithmeticException
180         *             if an overflow occurs and product is out of the possible
181         *             range for a {@code Decimal13f}
182         */
183        public Decimal13f by(Decimal2f factor) {
184                return Decimal13f.valueOf(this.value.multiplyExact(factor));
185        }
186        /**
187         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
188         * result is exact and has scale 13 which is the sum of the scales 
189         * of the Decimal that this multipliable object represents and the scale of
190         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
191         * product is out of the possible range for a {@code Decimal13f}.
192         * <p>
193         * Note that the result is <i>always</i> a new instance.
194         * 
195         * @param factor
196         *            the factor to multiply with the Decimal that this multipliable represents
197         * @return <tt>(this * factor)</tt>
198         * @throws ArithmeticException
199         *             if an overflow occurs and product is out of the possible
200         *             range for a {@code Decimal13f}
201         */
202        public Decimal13f by(MutableDecimal2f factor) {
203                return Decimal13f.valueOf(this.value.multiplyExact(factor));
204        }
205
206        /**
207         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
208         * result is exact and has scale 14 which is the sum of the scales 
209         * of the Decimal that this multipliable object represents and the scale of
210         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
211         * product is out of the possible range for a {@code Decimal14f}.
212         * <p>
213         * Note that the result is <i>always</i> a new instance.
214         * 
215         * @param factor
216         *            the factor to multiply with the Decimal that this multipliable represents
217         * @return <tt>(this * factor)</tt>
218         * @throws ArithmeticException
219         *             if an overflow occurs and product is out of the possible
220         *             range for a {@code Decimal14f}
221         */
222        public Decimal14f by(Decimal3f factor) {
223                return Decimal14f.valueOf(this.value.multiplyExact(factor));
224        }
225        /**
226         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
227         * result is exact and has scale 14 which is the sum of the scales 
228         * of the Decimal that this multipliable object represents and the scale of
229         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
230         * product is out of the possible range for a {@code Decimal14f}.
231         * <p>
232         * Note that the result is <i>always</i> a new instance.
233         * 
234         * @param factor
235         *            the factor to multiply with the Decimal that this multipliable represents
236         * @return <tt>(this * factor)</tt>
237         * @throws ArithmeticException
238         *             if an overflow occurs and product is out of the possible
239         *             range for a {@code Decimal14f}
240         */
241        public Decimal14f by(MutableDecimal3f factor) {
242                return Decimal14f.valueOf(this.value.multiplyExact(factor));
243        }
244
245        /**
246         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
247         * result is exact and has scale 15 which is the sum of the scales 
248         * of the Decimal that this multipliable object represents and the scale of
249         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
250         * product is out of the possible range for a {@code Decimal15f}.
251         * <p>
252         * Note that the result is <i>always</i> a new instance.
253         * 
254         * @param factor
255         *            the factor to multiply with the Decimal that this multipliable represents
256         * @return <tt>(this * factor)</tt>
257         * @throws ArithmeticException
258         *             if an overflow occurs and product is out of the possible
259         *             range for a {@code Decimal15f}
260         */
261        public Decimal15f by(Decimal4f factor) {
262                return Decimal15f.valueOf(this.value.multiplyExact(factor));
263        }
264        /**
265         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
266         * result is exact and has scale 15 which is the sum of the scales 
267         * of the Decimal that this multipliable object represents and the scale of
268         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
269         * product is out of the possible range for a {@code Decimal15f}.
270         * <p>
271         * Note that the result is <i>always</i> a new instance.
272         * 
273         * @param factor
274         *            the factor to multiply with the Decimal that this multipliable represents
275         * @return <tt>(this * factor)</tt>
276         * @throws ArithmeticException
277         *             if an overflow occurs and product is out of the possible
278         *             range for a {@code Decimal15f}
279         */
280        public Decimal15f by(MutableDecimal4f factor) {
281                return Decimal15f.valueOf(this.value.multiplyExact(factor));
282        }
283
284        /**
285         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
286         * result is exact and has scale 16 which is the sum of the scales 
287         * of the Decimal that this multipliable object represents and the scale of
288         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
289         * product is out of the possible range for a {@code Decimal16f}.
290         * <p>
291         * Note that the result is <i>always</i> a new instance.
292         * 
293         * @param factor
294         *            the factor to multiply with the Decimal that this multipliable represents
295         * @return <tt>(this * factor)</tt>
296         * @throws ArithmeticException
297         *             if an overflow occurs and product is out of the possible
298         *             range for a {@code Decimal16f}
299         */
300        public Decimal16f by(Decimal5f factor) {
301                return Decimal16f.valueOf(this.value.multiplyExact(factor));
302        }
303        /**
304         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
305         * result is exact and has scale 16 which is the sum of the scales 
306         * of the Decimal that this multipliable object represents and the scale of
307         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
308         * product is out of the possible range for a {@code Decimal16f}.
309         * <p>
310         * Note that the result is <i>always</i> a new instance.
311         * 
312         * @param factor
313         *            the factor to multiply with the Decimal that this multipliable represents
314         * @return <tt>(this * factor)</tt>
315         * @throws ArithmeticException
316         *             if an overflow occurs and product is out of the possible
317         *             range for a {@code Decimal16f}
318         */
319        public Decimal16f by(MutableDecimal5f factor) {
320                return Decimal16f.valueOf(this.value.multiplyExact(factor));
321        }
322
323        /**
324         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
325         * result is exact and has scale 17 which is the sum of the scales 
326         * of the Decimal that this multipliable object represents and the scale of
327         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
328         * product is out of the possible range for a {@code Decimal17f}.
329         * <p>
330         * Note that the result is <i>always</i> a new instance.
331         * 
332         * @param factor
333         *            the factor to multiply with the Decimal that this multipliable represents
334         * @return <tt>(this * factor)</tt>
335         * @throws ArithmeticException
336         *             if an overflow occurs and product is out of the possible
337         *             range for a {@code Decimal17f}
338         */
339        public Decimal17f by(Decimal6f factor) {
340                return Decimal17f.valueOf(this.value.multiplyExact(factor));
341        }
342        /**
343         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
344         * result is exact and has scale 17 which is the sum of the scales 
345         * of the Decimal that this multipliable object represents and the scale of
346         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
347         * product is out of the possible range for a {@code Decimal17f}.
348         * <p>
349         * Note that the result is <i>always</i> a new instance.
350         * 
351         * @param factor
352         *            the factor to multiply with the Decimal that this multipliable represents
353         * @return <tt>(this * factor)</tt>
354         * @throws ArithmeticException
355         *             if an overflow occurs and product is out of the possible
356         *             range for a {@code Decimal17f}
357         */
358        public Decimal17f by(MutableDecimal6f factor) {
359                return Decimal17f.valueOf(this.value.multiplyExact(factor));
360        }
361
362        /**
363         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
364         * result is exact and has scale 18 which is the sum of the scales 
365         * of the Decimal that this multipliable object represents and the scale of
366         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
367         * product is out of the possible range for a {@code Decimal18f}.
368         * <p>
369         * Note that the result is <i>always</i> a new instance.
370         * 
371         * @param factor
372         *            the factor to multiply with the Decimal that this multipliable represents
373         * @return <tt>(this * factor)</tt>
374         * @throws ArithmeticException
375         *             if an overflow occurs and product is out of the possible
376         *             range for a {@code Decimal18f}
377         */
378        public Decimal18f by(Decimal7f factor) {
379                return Decimal18f.valueOf(this.value.multiplyExact(factor));
380        }
381        /**
382         * Returns a {@code Decimal} whose value is {@code (this * factor)}. The
383         * result is exact and has scale 18 which is the sum of the scales 
384         * of the Decimal that this multipliable object represents and the scale of
385         * the {@code factor} argument. An {@link ArithmeticException} is thrown if the 
386         * product is out of the possible range for a {@code Decimal18f}.
387         * <p>
388         * Note that the result is <i>always</i> a new instance.
389         * 
390         * @param factor
391         *            the factor to multiply with the Decimal that this multipliable represents
392         * @return <tt>(this * factor)</tt>
393         * @throws ArithmeticException
394         *             if an overflow occurs and product is out of the possible
395         *             range for a {@code Decimal18f}
396         */
397        public Decimal18f by(MutableDecimal7f factor) {
398                return Decimal18f.valueOf(this.value.multiplyExact(factor));
399        }
400
401        
402        /**
403         * Returns a hash code for this <tt>Multipliable11f</tt> which happens to be the 
404         * hash code of the underlying {@code Decimal11f} value.
405         * 
406         * @return a hash code value for this object
407         * @see Decimal#hashCode()
408         */
409        @Override
410        public int hashCode() {
411                return value.hashCode();
412        }
413
414        /**
415         * Compares this Multipliable11f to the specified object. The result is {@code true}
416         * if and only if the argument is a {@code Multipliable11f} with an equal underlying 
417         * {@link #getValue() value}.
418         * 
419         * @param obj
420         *            the object to compare with
421         * @return {@code true} if the argument is a {@code Multipliable11f} and if its value
422         *         is equal to this multipliables's value; {@code false} otherwise
423         * @see #getValue()
424         * @see Decimal#equals(Object)
425         */
426        @Override
427        public boolean equals(Object obj) {
428                if (this == obj) return true;
429                if (obj == null) return false;
430                if (getClass() != obj.getClass()) return false;
431                return value.equals(((Multipliable11f)obj).value);
432        }
433
434        /**
435         * Returns a string representation of this {@code Multipliable11f} which is
436         * simply the string representation of the underlying Decimal {@link #getValue() value}.
437         * 
438         * @return a {@code String} Decimal representation of this {@code Multipliable11f}'s
439         *         value with all the fraction digits (including trailing zeros)
440         * @see #getValue()
441         * @see Decimal#toString()
442         */
443        @Override
444        public String toString() {
445                return value.toString();
446        }
447}