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.Multipliable4f; 034import org.decimal4j.factory.Factory4f; 035import org.decimal4j.immutable.Decimal4f; 036import org.decimal4j.scale.Scale4f; 037 038/** 039 * <code>MutableDecimal4f</code> represents a mutable decimal number with a fixed 040 * number of 4 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 MutableDecimal4f extends AbstractMutableDecimal<Scale4f, MutableDecimal4f> implements Cloneable { 046 047 private static final long serialVersionUID = 1L; 048 049 /** 050 * Constructs a new {@code MutableDecimal4f} with value zero. 051 * @see #zero() 052 */ 053 public MutableDecimal4f() { 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 #MutableDecimal4f(long)} 063 */ 064 private MutableDecimal4f(long unscaledValue, Scale4f scale) { 065 super(unscaledValue); 066 } 067 068 /** 069 * Translates the string representation of a {@code Decimal} into a 070 * {@code MutableDecimal4f}. 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 4 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 MutableDecimal4f}. 081 * 082 * @param value 083 * String value to convert into a {@code MutableDecimal4f} 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 MutableDecimal4f} 088 * @see #set(String, RoundingMode) 089 */ 090 public MutableDecimal4f(String value) { 091 this(); 092 set(value); 093 } 094 095 /** 096 * Constructs a {@code MutableDecimal4f} 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 MutableDecimal4f}. 099 * 100 * @param value 101 * long value to convert into a {@code MutableDecimal4f} 102 * @throws IllegalArgumentException 103 * if {@code value} is too large to be represented as a 104 * {@code MutableDecimal4f} 105 */ 106 public MutableDecimal4f(long value) { 107 this(); 108 set(value); 109 } 110 111 /** 112 * Constructs a {@code MutableDecimal4f} whose value is calculated by 113 * rounding the specified {@code double} argument to scale 4 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 MutableDecimal4f}. 116 * 117 * @param value 118 * double value to convert into a {@code MutableDecimal4f} 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 MutableDecimal4f} 122 * @see #set(double, RoundingMode) 123 * @see #set(float) 124 * @see #set(float, RoundingMode) 125 */ 126 public MutableDecimal4f(double value) { 127 this(); 128 set(value); 129 } 130 131 /** 132 * Constructs a {@code MutableDecimal4f} 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 MutableDecimal4f}. 135 * 136 * @param value 137 * {@code BigInteger} value to convert into a {@code MutableDecimal4f} 138 * @throws IllegalArgumentException 139 * if {@code value} is too large to be represented as a {@code MutableDecimal4f} 140 */ 141 public MutableDecimal4f(BigInteger value) { 142 this(); 143 set(value); 144 } 145 146 /** 147 * Constructs a {@code MutableDecimal4f} whose value is calculated by 148 * rounding the specified {@link BigDecimal} argument to scale 4 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 MutableDecimal4f}. 151 * 152 * @param value 153 * {@code BigDecimal} value to convert into a {@code MutableDecimal4f} 154 * @throws IllegalArgumentException 155 * if {@code value} is too large to be represented as a {@code MutableDecimal4f} 156 * @see #set(BigDecimal, RoundingMode) 157 */ 158 public MutableDecimal4f(BigDecimal value) { 159 this(); 160 set(value); 161 } 162 163 /** 164 * Constructs a {@code MutableDecimal4f} whose value is numerically equal to 165 * that of the specified {@link Decimal4f} value. 166 * 167 * @param value 168 * {@code Decimal4f} value to convert into a {@code MutableDecimal4f} 169 */ 170 public MutableDecimal4f(Decimal4f value) { 171 this(value.unscaledValue(), Decimal4f.METRICS); 172 } 173 174 /** 175 * Constructs a {@code MutableDecimal4f} whose value is calculated by 176 * rounding the specified {@link Decimal} argument to scale 4 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 MutableDecimal4f}. 179 * 180 * @param value 181 * Decimal value to convert into a {@code MutableDecimal4f} 182 * @throws IllegalArgumentException 183 * if {@code value} is too large to be represented as a {@code MutableDecimal4f} 184 * @see #set(Decimal, RoundingMode) 185 */ 186 public MutableDecimal4f(Decimal<?> value) { 187 this(); 188 setUnscaled(value.unscaledValue(), value.getScale()); 189 } 190 191 @Override 192 protected final MutableDecimal4f create(long unscaled) { 193 return new MutableDecimal4f(unscaled, Decimal4f.METRICS); 194 } 195 196 @Override 197 protected final MutableDecimal4f[] createArray(int length) { 198 return new MutableDecimal4f[length]; 199 } 200 201 @Override 202 protected final MutableDecimal4f self() { 203 return this; 204 } 205 206 @Override 207 public final Scale4f getScaleMetrics() { 208 return Decimal4f.METRICS; 209 } 210 211 @Override 212 public final int getScale() { 213 return Decimal4f.SCALE; 214 } 215 216 @Override 217 public Factory4f getFactory() { 218 return Decimal4f.FACTORY; 219 } 220 221 @Override 222 protected DecimalArithmetic getDefaultArithmetic() { 223 return Decimal4f.DEFAULT_ARITHMETIC; 224 } 225 226 @Override 227 protected DecimalArithmetic getDefaultCheckedArithmetic() { 228 return Decimal4f.METRICS.getDefaultCheckedArithmetic(); 229 } 230 231 @Override 232 protected DecimalArithmetic getRoundingDownArithmetic() { 233 return Decimal4f.METRICS.getRoundingDownArithmetic(); 234 } 235 236 @Override 237 protected DecimalArithmetic getRoundingFloorArithmetic() { 238 return Decimal4f.METRICS.getRoundingFloorArithmetic(); 239 } 240 241 @Override 242 protected DecimalArithmetic getRoundingHalfEvenArithmetic() { 243 return Decimal4f.METRICS.getRoundingHalfEvenArithmetic(); 244 } 245 246 @Override 247 protected DecimalArithmetic getRoundingUnnecessaryArithmetic() { 248 return Decimal4f.METRICS.getRoundingUnnecessaryArithmetic(); 249 } 250 251 @Override 252 public MutableDecimal4f clone() { 253 return new MutableDecimal4f(unscaledValue(), Decimal4f.METRICS); 254 } 255 256 /** 257 * Returns a new {@code MutableDecimal4f} whose value is equal to 258 * <code>unscaledValue * 10<sup>-4</sup></code>. 259 * 260 * @param unscaledValue 261 * the unscaled decimal value to convert 262 * @return a new {@code MutableDecimal4f} value initialised with <code>unscaledValue * 10<sup>-4</sup></code> 263 * @see #setUnscaled(long, int) 264 * @see #setUnscaled(long, int, RoundingMode) 265 */ 266 public static MutableDecimal4f unscaled(long unscaledValue) { 267 return new MutableDecimal4f(unscaledValue, Decimal4f.METRICS); 268 } 269 270 /** 271 * Returns a new {@code MutableDecimal4f} whose value is equal to zero. 272 * 273 * @return a new {@code MutableDecimal4f} value initialised with 0. 274 */ 275 public static MutableDecimal4f zero() { 276 return new MutableDecimal4f(); 277 } 278 279 /** 280 * Returns a new {@code MutableDecimal4f} whose value is equal to one ULP. 281 * 282 * @return a new {@code MutableDecimal4f} value initialised with 10<sup>-4</sup>. 283 */ 284 public static MutableDecimal4f ulp() { 285 return new MutableDecimal4f(Decimal4f.ULP); 286 } 287 288 /** 289 * Returns a new {@code MutableDecimal4f} whose value is equal to one. 290 * 291 * @return a new {@code MutableDecimal4f} value initialised with 1. 292 */ 293 public static MutableDecimal4f one() { 294 return new MutableDecimal4f(Decimal4f.ONE); 295 } 296 297 /** 298 * Returns a new {@code MutableDecimal4f} whose value is equal to two. 299 * 300 * @return a new {@code MutableDecimal4f} value initialised with 2. 301 */ 302 public static MutableDecimal4f two() { 303 return new MutableDecimal4f(Decimal4f.TWO); 304 } 305 306 /** 307 * Returns a new {@code MutableDecimal4f} whose value is equal to three. 308 * 309 * @return a new {@code MutableDecimal4f} value initialised with 3. 310 */ 311 public static MutableDecimal4f three() { 312 return new MutableDecimal4f(Decimal4f.THREE); 313 } 314 315 /** 316 * Returns a new {@code MutableDecimal4f} whose value is equal to four. 317 * 318 * @return a new {@code MutableDecimal4f} value initialised with 4. 319 */ 320 public static MutableDecimal4f four() { 321 return new MutableDecimal4f(Decimal4f.FOUR); 322 } 323 324 /** 325 * Returns a new {@code MutableDecimal4f} whose value is equal to five. 326 * 327 * @return a new {@code MutableDecimal4f} value initialised with 5. 328 */ 329 public static MutableDecimal4f five() { 330 return new MutableDecimal4f(Decimal4f.FIVE); 331 } 332 333 /** 334 * Returns a new {@code MutableDecimal4f} whose value is equal to six. 335 * 336 * @return a new {@code MutableDecimal4f} value initialised with 6. 337 */ 338 public static MutableDecimal4f six() { 339 return new MutableDecimal4f(Decimal4f.SIX); 340 } 341 342 /** 343 * Returns a new {@code MutableDecimal4f} whose value is equal to seven. 344 * 345 * @return a new {@code MutableDecimal4f} value initialised with 7. 346 */ 347 public static MutableDecimal4f seven() { 348 return new MutableDecimal4f(Decimal4f.SEVEN); 349 } 350 351 /** 352 * Returns a new {@code MutableDecimal4f} whose value is equal to eight. 353 * 354 * @return a new {@code MutableDecimal4f} value initialised with 8. 355 */ 356 public static MutableDecimal4f eight() { 357 return new MutableDecimal4f(Decimal4f.EIGHT); 358 } 359 360 /** 361 * Returns a new {@code MutableDecimal4f} whose value is equal to nine. 362 * 363 * @return a new {@code MutableDecimal4f} value initialised with 9. 364 */ 365 public static MutableDecimal4f nine() { 366 return new MutableDecimal4f(Decimal4f.NINE); 367 } 368 369 /** 370 * Returns a new {@code MutableDecimal4f} whose value is equal to ten. 371 * 372 * @return a new {@code MutableDecimal4f} value initialised with 10. 373 */ 374 public static MutableDecimal4f ten() { 375 return new MutableDecimal4f(Decimal4f.TEN); 376 } 377 /** 378 * Returns a new {@code MutableDecimal4f} whose value is equal to one hundred. 379 * 380 * @return a new {@code MutableDecimal4f} value initialised with 100. 381 */ 382 public static MutableDecimal4f hundred() { 383 return new MutableDecimal4f(Decimal4f.HUNDRED); 384 } 385 /** 386 * Returns a new {@code MutableDecimal4f} whose value is equal to one thousand. 387 * 388 * @return a new {@code MutableDecimal4f} value initialised with 1000. 389 */ 390 public static MutableDecimal4f thousand() { 391 return new MutableDecimal4f(Decimal4f.THOUSAND); 392 } 393 /** 394 * Returns a new {@code MutableDecimal4f} whose value is equal to one million. 395 * 396 * @return a new {@code MutableDecimal4f} value initialised with 10<sup>6</sup>. 397 */ 398 public static MutableDecimal4f million() { 399 return new MutableDecimal4f(Decimal4f.MILLION); 400 } 401 /** 402 * Returns a new {@code MutableDecimal4f} whose value is equal to one billion. 403 * 404 * @return a new {@code MutableDecimal4f} value initialised with 10<sup>9</sup>. 405 */ 406 public static MutableDecimal4f billion() { 407 return new MutableDecimal4f(Decimal4f.BILLION); 408 } 409 /** 410 * Returns a new {@code MutableDecimal4f} whose value is equal to one trillion. 411 * 412 * @return a new {@code MutableDecimal4f} value initialised with 10<sup>12</sup>. 413 */ 414 public static MutableDecimal4f trillion() { 415 return new MutableDecimal4f(Decimal4f.TRILLION); 416 } 417 418 /** 419 * Returns a new {@code MutableDecimal4f} whose value is equal to minus one. 420 * 421 * @return a new {@code MutableDecimal4f} value initialised with -1. 422 */ 423 public static MutableDecimal4f minusOne() { 424 return new MutableDecimal4f(Decimal4f.MINUS_ONE); 425 } 426 427 /** 428 * Returns a new {@code MutableDecimal4f} whose value is equal to one half. 429 * 430 * @return a new {@code MutableDecimal4f} value initialised with 0.5. 431 */ 432 public static MutableDecimal4f half() { 433 return new MutableDecimal4f(Decimal4f.HALF); 434 } 435 436 /** 437 * Returns a new {@code MutableDecimal4f} whose value is equal to one tenth. 438 * 439 * @return a new {@code MutableDecimal4f} value initialised with 0.1. 440 */ 441 public static MutableDecimal4f tenth() { 442 return new MutableDecimal4f(Decimal4f.TENTH); 443 } 444 445 /** 446 * Returns a new {@code MutableDecimal4f} whose value is equal to one hundredth. 447 * 448 * @return a new {@code MutableDecimal4f} value initialised with 0.01. 449 */ 450 public static MutableDecimal4f hundredth() { 451 return new MutableDecimal4f(Decimal4f.HUNDREDTH); 452 } 453 454 /** 455 * Returns a new {@code MutableDecimal4f} whose value is equal to one thousandth. 456 * 457 * @return a new {@code MutableDecimal4f} value initialised with 0.001. 458 */ 459 public static MutableDecimal4f thousandth() { 460 return new MutableDecimal4f(Decimal4f.THOUSANDTH); 461 } 462 463 464 /** 465 * Returns this {@code Decimal} as a multipliable factor for exact 466 * typed exact multiplication. The second factor is passed to one of 467 * the {@code by(..)} methods of the returned multiplier. The scale of 468 * the result is the sum of the scales of {@code this} Decimal and the 469 * second factor passed to the {@code by(..)} method. 470 * <p> 471 * The method is similar to {@link #multiplyExact(Decimal) multiplyExact(Decimal)} but the result 472 * is retrieved in exact typed form with the correct result scale. 473 * <p> 474 * For instance one can write: 475 * <pre> 476 * Decimal6f product = this.multiplyExact().by(Decimal2f.FIVE); 477 * </pre> 478 * 479 * @return a multipliable object encapsulating this Decimal as first factor 480 * of an exact multiplication 481 */ 482 public Multipliable4f multiplyExact() { 483 return new Multipliable4f(this); 484 } 485 486 @Override 487 public Decimal4f toImmutableDecimal() { 488 return Decimal4f.valueOf(this); 489 } 490 491 @Override 492 public MutableDecimal4f toMutableDecimal() { 493 return this; 494 } 495}