001/* 002 * The MIT License (MIT) 003 * 004 * Copyright (c) 2015-2023 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}