53 * {@code e}). The methods which require {@code fdlibm}
54 * semantics are {@code sin}, {@code cos}, {@code tan},
55 * {@code asin}, {@code acos}, {@code atan},
56 * {@code exp}, {@code log}, {@code log10},
57 * {@code cbrt}, {@code atan2}, {@code pow},
58 * {@code sinh}, {@code cosh}, {@code tanh},
59 * {@code hypot}, {@code expm1}, and {@code log1p}.
60 *
61 * <p>
62 * The platform uses signed two's complement integer arithmetic with
63 * int and long primitive types. The developer should choose
64 * the primitive type to ensure that arithmetic operations consistently
65 * produce correct results, which in some cases means the operations
66 * will not overflow the range of values of the computation.
67 * The best practice is to choose the primitive type and algorithm to avoid
68 * overflow. In cases where the size is {@code int} or {@code long} and
69 * overflow errors need to be detected, the methods {@code addExact},
70 * {@code subtractExact}, {@code multiplyExact}, and {@code toIntExact}
71 * throw an {@code ArithmeticException} when the results overflow.
72 * For other arithmetic operations such as divide, absolute value,
73 * increment, decrement, and negation overflow occurs only with
74 * a specific minimum or maximum value and should be checked against
75 * the minimum or maximum as appropriate.
76 *
77 * @author unascribed
78 * @author Joseph D. Darcy
79 * @since 1.3
80 */
81
82 public final class StrictMath {
83
84 /**
85 * Don't let anyone instantiate this class.
86 */
87 private StrictMath() {}
88
89 /**
90 * The {@code double} value that is closer than any other to
91 * <i>e</i>, the base of the natural logarithms.
92 */
93 public static final double E = 2.7182818284590452354;
784 public static long subtractExact(long x, long y) {
785 return Math.subtractExact(x, y);
786 }
787
788 /**
789 * Returns the product of the arguments,
790 * throwing an exception if the result overflows an {@code int}.
791 *
792 * @param x the first value
793 * @param y the second value
794 * @return the result
795 * @throws ArithmeticException if the result overflows an int
796 * @see Math#multiplyExact(int,int)
797 * @since 1.8
798 */
799 public static int multiplyExact(int x, int y) {
800 return Math.multiplyExact(x, y);
801 }
802
803 /**
804 * Returns the product of the arguments,
805 * throwing an exception if the result overflows a {@code long}.
806 *
807 * @param x the first value
808 * @param y the second value
809 * @return the result
810 * @throws ArithmeticException if the result overflows a long
811 * @see Math#multiplyExact(long,long)
812 * @since 1.8
813 */
814 public static long multiplyExact(long x, long y) {
815 return Math.multiplyExact(x, y);
816 }
817
818 /**
819 * Returns the value of the {@code long} argument;
820 * throwing an exception if the value overflows an {@code int}.
821 *
822 * @param value the long value
823 * @return the argument as an int
842 *
843 * @param x the dividend
844 * @param y the divisor
845 * @return the largest (closest to positive infinity)
846 * {@code int} value that is less than or equal to the algebraic quotient.
847 * @throws ArithmeticException if the divisor {@code y} is zero
848 * @see Math#floorDiv(int, int)
849 * @see Math#floor(double)
850 * @since 1.8
851 */
852 public static int floorDiv(int x, int y) {
853 return Math.floorDiv(x, y);
854 }
855
856 /**
857 * Returns the largest (closest to positive infinity)
858 * {@code long} value that is less than or equal to the algebraic quotient.
859 * There is one special case, if the dividend is the
860 * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1},
861 * then integer overflow occurs and
862 * the result is equal to the {@code Long.MIN_VALUE}.
863 * <p>
864 * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and
865 * a comparison to the integer division {@code /} operator.
866 *
867 * @param x the dividend
868 * @param y the divisor
869 * @return the largest (closest to positive infinity)
870 * {@code long} value that is less than or equal to the algebraic quotient.
871 * @throws ArithmeticException if the divisor {@code y} is zero
872 * @see Math#floorDiv(long, long)
873 * @see Math#floor(double)
874 * @since 1.8
875 */
876 public static long floorDiv(long x, long y) {
877 return Math.floorDiv(x, y);
878 }
879
880 /**
881 * Returns the floor modulus of the {@code int} arguments.
886 * <p>
887 * The relationship between {@code floorDiv} and {@code floorMod} is such that:
888 * <ul>
889 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
890 * </ul>
891 * <p>
892 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and
893 * a comparison to the {@code %} operator.
894 *
895 * @param x the dividend
896 * @param y the divisor
897 * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
898 * @throws ArithmeticException if the divisor {@code y} is zero
899 * @see Math#floorMod(int, int)
900 * @see StrictMath#floorDiv(int, int)
901 * @since 1.8
902 */
903 public static int floorMod(int x, int y) {
904 return Math.floorMod(x , y);
905 }
906 /**
907 * Returns the floor modulus of the {@code long} arguments.
908 * <p>
909 * The floor modulus is {@code x - (floorDiv(x, y) * y)},
910 * has the same sign as the divisor {@code y}, and
911 * is in the range of {@code -abs(y) < r < +abs(y)}.
912 * <p>
913 * The relationship between {@code floorDiv} and {@code floorMod} is such that:
914 * <ul>
915 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
916 * </ul>
917 * <p>
918 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and
919 * a comparison to the {@code %} operator.
920 *
921 * @param x the dividend
922 * @param y the divisor
923 * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
924 * @throws ArithmeticException if the divisor {@code y} is zero
925 * @see Math#floorMod(long, long)
|
53 * {@code e}). The methods which require {@code fdlibm}
54 * semantics are {@code sin}, {@code cos}, {@code tan},
55 * {@code asin}, {@code acos}, {@code atan},
56 * {@code exp}, {@code log}, {@code log10},
57 * {@code cbrt}, {@code atan2}, {@code pow},
58 * {@code sinh}, {@code cosh}, {@code tanh},
59 * {@code hypot}, {@code expm1}, and {@code log1p}.
60 *
61 * <p>
62 * The platform uses signed two's complement integer arithmetic with
63 * int and long primitive types. The developer should choose
64 * the primitive type to ensure that arithmetic operations consistently
65 * produce correct results, which in some cases means the operations
66 * will not overflow the range of values of the computation.
67 * The best practice is to choose the primitive type and algorithm to avoid
68 * overflow. In cases where the size is {@code int} or {@code long} and
69 * overflow errors need to be detected, the methods {@code addExact},
70 * {@code subtractExact}, {@code multiplyExact}, and {@code toIntExact}
71 * throw an {@code ArithmeticException} when the results overflow.
72 * For other arithmetic operations such as divide, absolute value,
73 * increment by one, decrement by one, and negation overflow occurs only with
74 * a specific minimum or maximum value and should be checked against
75 * the minimum or maximum as appropriate.
76 *
77 * @author unascribed
78 * @author Joseph D. Darcy
79 * @since 1.3
80 */
81
82 public final class StrictMath {
83
84 /**
85 * Don't let anyone instantiate this class.
86 */
87 private StrictMath() {}
88
89 /**
90 * The {@code double} value that is closer than any other to
91 * <i>e</i>, the base of the natural logarithms.
92 */
93 public static final double E = 2.7182818284590452354;
784 public static long subtractExact(long x, long y) {
785 return Math.subtractExact(x, y);
786 }
787
788 /**
789 * Returns the product of the arguments,
790 * throwing an exception if the result overflows an {@code int}.
791 *
792 * @param x the first value
793 * @param y the second value
794 * @return the result
795 * @throws ArithmeticException if the result overflows an int
796 * @see Math#multiplyExact(int,int)
797 * @since 1.8
798 */
799 public static int multiplyExact(int x, int y) {
800 return Math.multiplyExact(x, y);
801 }
802
803 /**
804 * Returns the product of the arguments, throwing an exception if the result
805 * overflows a {@code long}.
806 *
807 * @param x the first value
808 * @param y the second value
809 * @return the result
810 * @throws ArithmeticException if the result overflows a long
811 * @see Math#multiplyExact(long,int)
812 * @since 1.9
813 */
814 public static long multiplyExact(long x, int y) {
815 return Math.multiplyExact(x, y);
816 }
817
818 /**
819 * Returns the product of the arguments,
820 * throwing an exception if the result overflows a {@code long}.
821 *
822 * @param x the first value
823 * @param y the second value
824 * @return the result
825 * @throws ArithmeticException if the result overflows a long
826 * @see Math#multiplyExact(long,long)
827 * @since 1.8
828 */
829 public static long multiplyExact(long x, long y) {
830 return Math.multiplyExact(x, y);
831 }
832
833 /**
834 * Returns the value of the {@code long} argument;
835 * throwing an exception if the value overflows an {@code int}.
836 *
837 * @param value the long value
838 * @return the argument as an int
857 *
858 * @param x the dividend
859 * @param y the divisor
860 * @return the largest (closest to positive infinity)
861 * {@code int} value that is less than or equal to the algebraic quotient.
862 * @throws ArithmeticException if the divisor {@code y} is zero
863 * @see Math#floorDiv(int, int)
864 * @see Math#floor(double)
865 * @since 1.8
866 */
867 public static int floorDiv(int x, int y) {
868 return Math.floorDiv(x, y);
869 }
870
871 /**
872 * Returns the largest (closest to positive infinity)
873 * {@code long} value that is less than or equal to the algebraic quotient.
874 * There is one special case, if the dividend is the
875 * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1},
876 * then integer overflow occurs and
877 * the result is equal to {@code Long.MIN_VALUE}.
878 * <p>
879 * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and
880 * a comparison to the integer division {@code /} operator.
881 *
882 * @param x the dividend
883 * @param y the divisor
884 * @return the largest (closest to positive infinity)
885 * {@code int} value that is less than or equal to the algebraic quotient.
886 * @throws ArithmeticException if the divisor {@code y} is zero
887 * @see Math#floorDiv(long, int)
888 * @see Math#floor(double)
889 * @since 1.9
890 */
891 public static long floorDiv(long x, int y) {
892 return Math.floorDiv(x, y);
893 }
894
895 /**
896 * Returns the largest (closest to positive infinity)
897 * {@code long} value that is less than or equal to the algebraic quotient.
898 * There is one special case, if the dividend is the
899 * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1},
900 * then integer overflow occurs and
901 * the result is equal to the {@code Long.MIN_VALUE}.
902 * <p>
903 * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and
904 * a comparison to the integer division {@code /} operator.
905 *
906 * @param x the dividend
907 * @param y the divisor
908 * @return the largest (closest to positive infinity)
909 * {@code long} value that is less than or equal to the algebraic quotient.
910 * @throws ArithmeticException if the divisor {@code y} is zero
911 * @see Math#floorDiv(long, long)
912 * @see Math#floor(double)
913 * @since 1.8
914 */
915 public static long floorDiv(long x, long y) {
916 return Math.floorDiv(x, y);
917 }
918
919 /**
920 * Returns the floor modulus of the {@code int} arguments.
925 * <p>
926 * The relationship between {@code floorDiv} and {@code floorMod} is such that:
927 * <ul>
928 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
929 * </ul>
930 * <p>
931 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and
932 * a comparison to the {@code %} operator.
933 *
934 * @param x the dividend
935 * @param y the divisor
936 * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
937 * @throws ArithmeticException if the divisor {@code y} is zero
938 * @see Math#floorMod(int, int)
939 * @see StrictMath#floorDiv(int, int)
940 * @since 1.8
941 */
942 public static int floorMod(int x, int y) {
943 return Math.floorMod(x , y);
944 }
945
946 /**
947 * Returns the floor modulus of the {@code long} and {@int} arguments.
948 * <p>
949 * The floor modulus is {@code x - (floorDiv(x, y) * y)},
950 * has the same sign as the divisor {@code y}, and
951 * is in the range of {@code -abs(y) < r < +abs(y)}.
952 *
953 * <p>
954 * The relationship between {@code floorDiv} and {@code floorMod} is such that:
955 * <ul>
956 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
957 * </ul>
958 * <p>
959 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and
960 * a comparison to the {@code %} operator.
961 *
962 * @param x the dividend
963 * @param y the divisor
964 * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
965 * @throws ArithmeticException if the divisor {@code y} is zero
966 * @see Math#floorMod(long, int)
967 * @see StrictMath#floorDiv(long, int)
968 * @since 1.9
969 */
970 public static int floorMod(long x, int y) {
971 return Math.floorMod(x , y);
972 }
973
974 /**
975 * Returns the floor modulus of the {@code long} arguments.
976 * <p>
977 * The floor modulus is {@code x - (floorDiv(x, y) * y)},
978 * has the same sign as the divisor {@code y}, and
979 * is in the range of {@code -abs(y) < r < +abs(y)}.
980 * <p>
981 * The relationship between {@code floorDiv} and {@code floorMod} is such that:
982 * <ul>
983 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
984 * </ul>
985 * <p>
986 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and
987 * a comparison to the {@code %} operator.
988 *
989 * @param x the dividend
990 * @param y the divisor
991 * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
992 * @throws ArithmeticException if the divisor {@code y} is zero
993 * @see Math#floorMod(long, long)
|