001/* 002 * The MIT License (MIT) 003 * 004 * Copyright (c) 2015-2024 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.mutable; 025 026import java.math.BigDecimal; 027import java.math.BigInteger; 028import java.math.RoundingMode; 029 030import org.decimal4j.api.Decimal; 031import org.decimal4j.api.DecimalArithmetic; 032import org.decimal4j.base.AbstractMutableDecimal; 033import org.decimal4j.exact.Multipliable15f; 034import org.decimal4j.factory.Factory15f; 035import org.decimal4j.immutable.Decimal15f; 036import org.decimal4j.scale.Scale15f; 037 038/** 039 * <code>MutableDecimal15f</code> represents a mutable decimal number with a fixed 040 * number of 15 digits to the right of the decimal point. 041 * <p> 042 * All methods for this class throw {@code NullPointerException} when passed a 043 * {@code null} object reference for any input parameter. 044 */ 045public final class MutableDecimal15f extends AbstractMutableDecimal<Scale15f, MutableDecimal15f> implements Cloneable { 046 047 private static final long serialVersionUID = 1L; 048 049 /** 050 * Constructs a new {@code MutableDecimal15f} with value zero. 051 * @see #zero() 052 */ 053 public MutableDecimal15f() { 054 super(0); 055 } 056 057 /** 058 * Private constructor with unscaled value. 059 * 060 * @param unscaledValue the unscaled value 061 * @param scale the scale metrics used to distinguish this constructor signature 062 * from {@link #MutableDecimal15f(long)} 063 */ 064 private MutableDecimal15f(long unscaledValue, Scale15f scale) { 065 super(unscaledValue); 066 } 067 068 /** 069 * Translates the string representation of a {@code Decimal} into a 070 * {@code MutableDecimal15f}. The string representation consists 071 * of an optional sign, {@code '+'} or {@code '-'} , followed by a sequence 072 * of zero or more decimal digits ("the integer"), optionally followed by a 073 * fraction. 074 * <p> 075 * The fraction consists of a decimal point followed by zero or more decimal 076 * digits. The string must contain at least one digit in either the integer 077 * or the fraction. If the fraction contains more than 15 digits, the 078 * value is rounded using {@link RoundingMode#HALF_UP HALF_UP} rounding. An 079 * exception is thrown if the value is too large to be represented as a 080 * {@code MutableDecimal15f}. 081 * 082 * @param value 083 * String value to convert into a {@code MutableDecimal15f} 084 * @throws NumberFormatException 085 * if {@code value} does not represent a valid {@code Decimal} 086 * or if the value is too large to be represented as a 087 * {@code MutableDecimal15f} 088 * @see #set(String, RoundingMode) 089 */ 090 public MutableDecimal15f(String value) { 091 this(); 092 set(value); 093 } 094 095 /** 096 * Constructs a {@code MutableDecimal15f} whose value is numerically equal 097 * to that of the specified {@code long} value. An exception is thrown if the 098 * specified value is too large to be represented as a {@code MutableDecimal15f}. 099 * 100 * @param value 101 * long value to convert into a {@code MutableDecimal15f} 102 * @throws IllegalArgumentException 103 * if {@code value} is too large to be represented as a 104 * {@code MutableDecimal15f} 105 */ 106 public MutableDecimal15f(long value) { 107 this(); 108 set(value); 109 } 110 111 /** 112 * Constructs a {@code MutableDecimal15f} whose value is calculated by 113 * rounding the specified {@code double} argument to scale 15 using 114 * {@link RoundingMode#HALF_UP HALF_UP} rounding. An exception is thrown if the 115 * specified value is too large to be represented as a {@code MutableDecimal15f}. 116 * 117 * @param value 118 * double value to convert into a {@code MutableDecimal15f} 119 * @throws IllegalArgumentException 120 * if {@code value} is NaN or infinite or if the magnitude is too large 121 * for the double to be represented as a {@code MutableDecimal15f} 122 * @see #set(double, RoundingMode) 123 * @see #set(float) 124 * @see #set(float, RoundingMode) 125 */ 126 public MutableDecimal15f(double value) { 127 this(); 128 set(value); 129 } 130 131 /** 132 * Constructs a {@code MutableDecimal15f} whose value is numerically equal to 133 * that of the specified {@link BigInteger} value. An exception is thrown if the 134 * specified value is too large to be represented as a {@code MutableDecimal15f}. 135 * 136 * @param value 137 * {@code BigInteger} value to convert into a {@code MutableDecimal15f} 138 * @throws IllegalArgumentException 139 * if {@code value} is too large to be represented as a {@code MutableDecimal15f} 140 */ 141 public MutableDecimal15f(BigInteger value) { 142 this(); 143 set(value); 144 } 145 146 /** 147 * Constructs a {@code MutableDecimal15f} whose value is calculated by 148 * rounding the specified {@link BigDecimal} argument to scale 15 using 149 * {@link RoundingMode#HALF_UP HALF_UP} rounding. An exception is thrown if the 150 * specified value is too large to be represented as a {@code MutableDecimal15f}. 151 * 152 * @param value 153 * {@code BigDecimal} value to convert into a {@code MutableDecimal15f} 154 * @throws IllegalArgumentException 155 * if {@code value} is too large to be represented as a {@code MutableDecimal15f} 156 * @see #set(BigDecimal, RoundingMode) 157 */ 158 public MutableDecimal15f(BigDecimal value) { 159 this(); 160 set(value); 161 } 162 163 /** 164 * Constructs a {@code MutableDecimal15f} whose value is numerically equal to 165 * that of the specified {@link Decimal15f} value. 166 * 167 * @param value 168 * {@code Decimal15f} value to convert into a {@code MutableDecimal15f} 169 */ 170 public MutableDecimal15f(Decimal15f value) { 171 this(value.unscaledValue(), Decimal15f.METRICS); 172 } 173 174 /** 175 * Constructs a {@code MutableDecimal15f} whose value is calculated by 176 * rounding the specified {@link Decimal} argument to scale 15 using 177 * {@link RoundingMode#HALF_UP HALF_UP} rounding. An exception is thrown if 178 * the specified value is too large to be represented as a {@code MutableDecimal15f}. 179 * 180 * @param value 181 * Decimal value to convert into a {@code MutableDecimal15f} 182 * @throws IllegalArgumentException 183 * if {@code value} is too large to be represented as a {@code MutableDecimal15f} 184 * @see #set(Decimal, RoundingMode) 185 */ 186 public MutableDecimal15f(Decimal<?> value) { 187 this(); 188 setUnscaled(value.unscaledValue(), value.getScale()); 189 } 190 191 @Override 192 protected final MutableDecimal15f create(long unscaled) { 193 return new MutableDecimal15f(unscaled, Decimal15f.METRICS); 194 } 195 196 @Override 197 protected final MutableDecimal15f[] createArray(int length) { 198 return new MutableDecimal15f[length]; 199 } 200 201 @Override 202 protected final MutableDecimal15f self() { 203 return this; 204 } 205 206 @Override 207 public final Scale15f getScaleMetrics() { 208 return Decimal15f.METRICS; 209 } 210 211 @Override 212 public final int getScale() { 213 return Decimal15f.SCALE; 214 } 215 216 @Override 217 public Factory15f getFactory() { 218 return Decimal15f.FACTORY; 219 } 220 221 @Override 222 protected DecimalArithmetic getDefaultArithmetic() { 223 return Decimal15f.DEFAULT_ARITHMETIC; 224 } 225 226 @Override 227 protected DecimalArithmetic getDefaultCheckedArithmetic() { 228 return Decimal15f.METRICS.getDefaultCheckedArithmetic(); 229 } 230 231 @Override 232 protected DecimalArithmetic getRoundingDownArithmetic() { 233 return Decimal15f.METRICS.getRoundingDownArithmetic(); 234 } 235 236 @Override 237 protected DecimalArithmetic getRoundingFloorArithmetic() { 238 return Decimal15f.METRICS.getRoundingFloorArithmetic(); 239 } 240 241 @Override 242 protected DecimalArithmetic getRoundingHalfEvenArithmetic() { 243 return Decimal15f.METRICS.getRoundingHalfEvenArithmetic(); 244 } 245 246 @Override 247 protected DecimalArithmetic getRoundingUnnecessaryArithmetic() { 248 return Decimal15f.METRICS.getRoundingUnnecessaryArithmetic(); 249 } 250 251 @Override 252 public MutableDecimal15f clone() { 253 return new MutableDecimal15f(unscaledValue(), Decimal15f.METRICS); 254 } 255 256 /** 257 * Returns a new {@code MutableDecimal15f} whose value is equal to 258 * <code>unscaledValue * 10<sup>-15</sup></code>. 259 * 260 * @param unscaledValue 261 * the unscaled decimal value to convert 262 * @return a new {@code MutableDecimal15f} value initialised with <code>unscaledValue * 10<sup>-15</sup></code> 263 * @see #setUnscaled(long, int) 264 * @see #setUnscaled(long, int, RoundingMode) 265 */ 266 public static MutableDecimal15f unscaled(long unscaledValue) { 267 return new MutableDecimal15f(unscaledValue, Decimal15f.METRICS); 268 } 269 270 /** 271 * Returns a new {@code MutableDecimal15f} whose value is equal to zero. 272 * 273 * @return a new {@code MutableDecimal15f} value initialised with 0. 274 */ 275 public static MutableDecimal15f zero() { 276 return new MutableDecimal15f(); 277 } 278 279 /** 280 * Returns a new {@code MutableDecimal15f} whose value is equal to one ULP. 281 * 282 * @return a new {@code MutableDecimal15f} value initialised with 10<sup>-15</sup>. 283 */ 284 public static MutableDecimal15f ulp() { 285 return new MutableDecimal15f(Decimal15f.ULP); 286 } 287 288 /** 289 * Returns a new {@code MutableDecimal15f} whose value is equal to one. 290 * 291 * @return a new {@code MutableDecimal15f} value initialised with 1. 292 */ 293 public static MutableDecimal15f one() { 294 return new MutableDecimal15f(Decimal15f.ONE); 295 } 296 297 /** 298 * Returns a new {@code MutableDecimal15f} whose value is equal to two. 299 * 300 * @return a new {@code MutableDecimal15f} value initialised with 2. 301 */ 302 public static MutableDecimal15f two() { 303 return new MutableDecimal15f(Decimal15f.TWO); 304 } 305 306 /** 307 * Returns a new {@code MutableDecimal15f} whose value is equal to three. 308 * 309 * @return a new {@code MutableDecimal15f} value initialised with 3. 310 */ 311 public static MutableDecimal15f three() { 312 return new MutableDecimal15f(Decimal15f.THREE); 313 } 314 315 /** 316 * Returns a new {@code MutableDecimal15f} whose value is equal to four. 317 * 318 * @return a new {@code MutableDecimal15f} value initialised with 4. 319 */ 320 public static MutableDecimal15f four() { 321 return new MutableDecimal15f(Decimal15f.FOUR); 322 } 323 324 /** 325 * Returns a new {@code MutableDecimal15f} whose value is equal to five. 326 * 327 * @return a new {@code MutableDecimal15f} value initialised with 5. 328 */ 329 public static MutableDecimal15f five() { 330 return new MutableDecimal15f(Decimal15f.FIVE); 331 } 332 333 /** 334 * Returns a new {@code MutableDecimal15f} whose value is equal to six. 335 * 336 * @return a new {@code MutableDecimal15f} value initialised with 6. 337 */ 338 public static MutableDecimal15f six() { 339 return new MutableDecimal15f(Decimal15f.SIX); 340 } 341 342 /** 343 * Returns a new {@code MutableDecimal15f} whose value is equal to seven. 344 * 345 * @return a new {@code MutableDecimal15f} value initialised with 7. 346 */ 347 public static MutableDecimal15f seven() { 348 return new MutableDecimal15f(Decimal15f.SEVEN); 349 } 350 351 /** 352 * Returns a new {@code MutableDecimal15f} whose value is equal to eight. 353 * 354 * @return a new {@code MutableDecimal15f} value initialised with 8. 355 */ 356 public static MutableDecimal15f eight() { 357 return new MutableDecimal15f(Decimal15f.EIGHT); 358 } 359 360 /** 361 * Returns a new {@code MutableDecimal15f} whose value is equal to nine. 362 * 363 * @return a new {@code MutableDecimal15f} value initialised with 9. 364 */ 365 public static MutableDecimal15f nine() { 366 return new MutableDecimal15f(Decimal15f.NINE); 367 } 368 369 /** 370 * Returns a new {@code MutableDecimal15f} whose value is equal to ten. 371 * 372 * @return a new {@code MutableDecimal15f} value initialised with 10. 373 */ 374 public static MutableDecimal15f ten() { 375 return new MutableDecimal15f(Decimal15f.TEN); 376 } 377 /** 378 * Returns a new {@code MutableDecimal15f} whose value is equal to one hundred. 379 * 380 * @return a new {@code MutableDecimal15f} value initialised with 100. 381 */ 382 public static MutableDecimal15f hundred() { 383 return new MutableDecimal15f(Decimal15f.HUNDRED); 384 } 385 /** 386 * Returns a new {@code MutableDecimal15f} whose value is equal to one thousand. 387 * 388 * @return a new {@code MutableDecimal15f} value initialised with 1000. 389 */ 390 public static MutableDecimal15f thousand() { 391 return new MutableDecimal15f(Decimal15f.THOUSAND); 392 } 393 394 /** 395 * Returns a new {@code MutableDecimal15f} whose value is equal to minus one. 396 * 397 * @return a new {@code MutableDecimal15f} value initialised with -1. 398 */ 399 public static MutableDecimal15f minusOne() { 400 return new MutableDecimal15f(Decimal15f.MINUS_ONE); 401 } 402 403 /** 404 * Returns a new {@code MutableDecimal15f} whose value is equal to one half. 405 * 406 * @return a new {@code MutableDecimal15f} value initialised with 0.5. 407 */ 408 public static MutableDecimal15f half() { 409 return new MutableDecimal15f(Decimal15f.HALF); 410 } 411 412 /** 413 * Returns a new {@code MutableDecimal15f} whose value is equal to one tenth. 414 * 415 * @return a new {@code MutableDecimal15f} value initialised with 0.1. 416 */ 417 public static MutableDecimal15f tenth() { 418 return new MutableDecimal15f(Decimal15f.TENTH); 419 } 420 421 /** 422 * Returns a new {@code MutableDecimal15f} whose value is equal to one hundredth. 423 * 424 * @return a new {@code MutableDecimal15f} value initialised with 0.01. 425 */ 426 public static MutableDecimal15f hundredth() { 427 return new MutableDecimal15f(Decimal15f.HUNDREDTH); 428 } 429 430 /** 431 * Returns a new {@code MutableDecimal15f} whose value is equal to one thousandth. 432 * 433 * @return a new {@code MutableDecimal15f} value initialised with 0.001. 434 */ 435 public static MutableDecimal15f thousandth() { 436 return new MutableDecimal15f(Decimal15f.THOUSANDTH); 437 } 438 439 /** 440 * Returns a new {@code MutableDecimal15f} whose value is equal to one millionth. 441 * 442 * @return a new {@code MutableDecimal15f} value initialised with 10<sup>-6</sup>. 443 */ 444 public static MutableDecimal15f millionth() { 445 return new MutableDecimal15f(Decimal15f.MILLIONTH); 446 } 447 448 /** 449 * Returns a new {@code MutableDecimal15f} whose value is equal to one billionth. 450 * 451 * @return a new {@code MutableDecimal15f} value initialised with 10<sup>-9</sup>. 452 */ 453 public static MutableDecimal15f billionth() { 454 return new MutableDecimal15f(Decimal15f.BILLIONTH); 455 } 456 457 /** 458 * Returns a new {@code MutableDecimal15f} whose value is equal to one trillionth. 459 * 460 * @return a new {@code MutableDecimal15f} value initialised with 10<sup>-12</sup>. 461 */ 462 public static MutableDecimal15f trillionth() { 463 return new MutableDecimal15f(Decimal15f.TRILLIONTH); 464 } 465 466 /** 467 * Returns a new {@code MutableDecimal15f} whose value is equal to one quadrillionth. 468 * 469 * @return a new {@code MutableDecimal15f} value initialised with 10<sup>-15</sup>. 470 */ 471 public static MutableDecimal15f quadrillionth() { 472 return new MutableDecimal15f(Decimal15f.QUADRILLIONTH); 473 } 474 475 476 /** 477 * Returns this {@code Decimal} as a multipliable factor for exact 478 * typed exact multiplication. The second factor is passed to one of 479 * the {@code by(..)} methods of the returned multiplier. The scale of 480 * the result is the sum of the scales of {@code this} Decimal and the 481 * second factor passed to the {@code by(..)} method. 482 * <p> 483 * The method is similar to {@link #multiplyExact(Decimal) multiplyExact(Decimal)} but the result 484 * is retrieved in exact typed form with the correct result scale. 485 * <p> 486 * For instance one can write: 487 * <pre> 488 * Decimal17f product = this.multiplyExact().by(Decimal2f.FIVE); 489 * </pre> 490 * 491 * @return a multipliable object encapsulating this Decimal as first factor 492 * of an exact multiplication 493 */ 494 public Multipliable15f multiplyExact() { 495 return new Multipliable15f(this); 496 } 497 498 @Override 499 public Decimal15f toImmutableDecimal() { 500 return Decimal15f.valueOf(this); 501 } 502 503 @Override 504 public MutableDecimal15f toMutableDecimal() { 505 return this; 506 } 507}