1 /* |
1 /* |
2 * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved. |
2 * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 * |
4 * |
5 * This code is free software; you can redistribute it and/or modify it |
5 * This code is free software; you can redistribute it and/or modify it |
6 * under the terms of the GNU General Public License version 2 only, as |
6 * under the terms of the GNU General Public License version 2 only, as |
7 * published by the Free Software Foundation. Oracle designates this |
7 * published by the Free Software Foundation. Oracle designates this |
65 * produce correct results, which in some cases means the operations |
65 * produce correct results, which in some cases means the operations |
66 * will not overflow the range of values of the computation. |
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 |
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 |
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}, |
69 * overflow errors need to be detected, the methods {@code addExact}, |
70 * {@code subtractExact}, {@code multiplyExact}, and {@code toIntExact} |
70 * {@code subtractExact}, {@code multiplyExact}, {@code toIntExact}, |
|
71 * {@code incrementExact}, {@code decrementExact} and {@code negateExact} |
71 * throw an {@code ArithmeticException} when the results overflow. |
72 * throw an {@code ArithmeticException} when the results overflow. |
72 * For other arithmetic operations such as divide, absolute value, |
73 * For the arithmetic operations divide and absolute value, overflow |
73 * increment by one, decrement by one, and negation overflow occurs only with |
74 * occurs only with a specific minimum or maximum value and |
74 * a specific minimum or maximum value and should be checked against |
75 * should be checked against the minimum or maximum as appropriate. |
75 * the minimum or maximum as appropriate. |
|
76 * |
76 * |
77 * @author unascribed |
77 * @author unascribed |
78 * @author Joseph D. Darcy |
78 * @author Joseph D. Darcy |
79 * @since 1.3 |
79 * @since 1.3 |
80 */ |
80 */ |
833 public static long multiplyExact(long x, long y) { |
833 public static long multiplyExact(long x, long y) { |
834 return Math.multiplyExact(x, y); |
834 return Math.multiplyExact(x, y); |
835 } |
835 } |
836 |
836 |
837 /** |
837 /** |
838 * Returns the value of the {@code long} argument; |
838 * Returns the argument incremented by one, |
839 * throwing an exception if the value overflows an {@code int}. |
839 * throwing an exception if the result overflows an {@code int}. |
|
840 * The overflow only occurs for {@linkplain Integer#MAX_VALUE the maximum value}. |
|
841 * |
|
842 * @param a the value to increment |
|
843 * @return the result |
|
844 * @throws ArithmeticException if the result overflows an int |
|
845 * @see Math#incrementExact(int) |
|
846 * @since 14 |
|
847 */ |
|
848 public static int incrementExact(int a) { |
|
849 return Math.incrementExact(a); |
|
850 } |
|
851 |
|
852 /** |
|
853 * Returns the argument incremented by one, |
|
854 * throwing an exception if the result overflows a {@code long}. |
|
855 * The overflow only occurs for {@linkplain Long#MAX_VALUE the maximum value}. |
|
856 * |
|
857 * @param a the value to increment |
|
858 * @return the result |
|
859 * @throws ArithmeticException if the result overflows a long |
|
860 * @see Math#incrementExact(long) |
|
861 * @since 14 |
|
862 */ |
|
863 public static long incrementExact(long a) { |
|
864 return Math.incrementExact(a); |
|
865 } |
|
866 |
|
867 /** |
|
868 * Returns the argument decremented by one, |
|
869 * throwing an exception if the result overflows an {@code int}. |
|
870 * The overflow only occurs for {@linkplain Integer#MIN_VALUE the minimum value}. |
|
871 * |
|
872 * @param a the value to decrement |
|
873 * @return the result |
|
874 * @throws ArithmeticException if the result overflows an int |
|
875 * @see Math#decrementExact(int) |
|
876 * @since 14 |
|
877 */ |
|
878 public static int decrementExact(int a) { |
|
879 return Math.decrementExact(a); |
|
880 } |
|
881 |
|
882 /** |
|
883 * Returns the argument decremented by one, |
|
884 * throwing an exception if the result overflows a {@code long}. |
|
885 * The overflow only occurs for {@linkplain Long#MIN_VALUE the minimum value}. |
|
886 * |
|
887 * @param a the value to decrement |
|
888 * @return the result |
|
889 * @throws ArithmeticException if the result overflows a long |
|
890 * @see Math#decrementExact(long) |
|
891 * @since 14 |
|
892 */ |
|
893 public static long decrementExact(long a) { |
|
894 return Math.decrementExact(a); |
|
895 } |
|
896 |
|
897 /** |
|
898 * Returns the negation of the argument, |
|
899 * throwing an exception if the result overflows an {@code int}. |
|
900 * The overflow only occurs for {@linkplain Integer#MIN_VALUE the minimum value}. |
|
901 * |
|
902 * @param a the value to negate |
|
903 * @return the result |
|
904 * @throws ArithmeticException if the result overflows an int |
|
905 * @see Math#negateExact(int) |
|
906 * @since 14 |
|
907 */ |
|
908 public static int negateExact(int a) { |
|
909 return Math.negateExact(a); |
|
910 } |
|
911 |
|
912 /** |
|
913 * Returns the negation of the argument, |
|
914 * throwing an exception if the result overflows a {@code long}. |
|
915 * The overflow only occurs for {@linkplain Long#MIN_VALUE the minimum value}. |
|
916 * |
|
917 * @param a the value to negate |
|
918 * @return the result |
|
919 * @throws ArithmeticException if the result overflows a long |
|
920 * @see Math#negateExact(long) |
|
921 * @since 14 |
|
922 */ |
|
923 public static long negateExact(long a) { |
|
924 return Math.negateExact(a); |
|
925 } |
|
926 |
|
927 /** |
|
928 * Returns the value of the {@code long} argument, throwing an exception |
|
929 * if the value overflows an {@code int}. |
840 * |
930 * |
841 * @param value the long value |
931 * @param value the long value |
842 * @return the argument as an int |
932 * @return the argument as an int |
843 * @throws ArithmeticException if the {@code argument} overflows an int |
933 * @throws ArithmeticException if the {@code argument} overflows an int |
844 * @see Math#toIntExact(long) |
934 * @see Math#toIntExact(long) |