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.truncate;
025
026import java.math.RoundingMode;
027import java.util.Collections;
028import java.util.LinkedHashSet;
029import java.util.Set;
030
031/**
032 * Policy defining how to handle truncation due to overflow or rounding. A
033 * {@code TruncationPolicy} is uniquely defined by the two elements
034 * {@link #getOverflowMode overflow mode} and {@link #getRoundingMode() rounding
035 * mode}.
036 * <p>
037 * Truncation policies are are defined by {@link UncheckedRounding} and {@link CheckedRounding}.
038 * Some special truncation policies are also defined by
039 * <ul>
040 * <li>{@link #DEFAULT}</li>
041 * <li>{@link #VALUES}</li>
042 * <li>{@link UncheckedRounding#VALUES}</li>
043 * <li>{@link CheckedRounding#VALUES}</li>
044 * </ul>
045 */
046public interface TruncationPolicy {
047        /**
048         * Default truncation policy: {@link UncheckedRounding#HALF_UP}.
049         */
050        TruncationPolicy DEFAULT = UncheckedRounding.HALF_UP;
051
052        /**
053         * Unmodifiable set with all possible truncation policies.
054         */
055        Set<TruncationPolicy> VALUES = Collections.unmodifiableSet(new LinkedHashSet<TruncationPolicy>(UncheckedRounding.VALUES.size(), 2f) {
056                private static final long serialVersionUID = 1L;
057                {
058                        addAll(UncheckedRounding.VALUES);
059                        addAll(CheckedRounding.VALUES);
060                }
061        });
062
063        /**
064         * Returns the overflow mode which defines how to deal the situation when an
065         * operation that causes an overflow.
066         * 
067         * @return the mode to apply if an arithmetic operation causes an overflow
068         */
069        OverflowMode getOverflowMode();
070
071        /**
072         * Returns the rounding mode which defines how to deal the situation when an
073         * operation leads to truncation or rounding.
074         * 
075         * @return the rounding mode indicating how the least significant returned
076         *         digit of a rounded result is to be calculated
077         */
078        RoundingMode getRoundingMode();
079}