< prev index next >

src/java.base/share/classes/java/lang/Math.java

Print this page




1257      *   <li>If the signs of the arguments are different, the results differ from the {@code %} operator.<br>
1258      *      <ul>
1259      *      <li>{@code floorMod(+4, -3) == -2}; &nbsp; and {@code (+4 % -3) == +1} </li>
1260      *      <li>{@code floorMod(-4, +3) == +2}; &nbsp; and {@code (-4 % +3) == -1} </li>
1261      *      <li>{@code floorMod(-4, -3) == -1}; &nbsp; and {@code (-4 % -3) == -1 } </li>
1262      *      </ul>
1263      *   </li>
1264      * </ul>
1265      * <p>
1266      * If the signs of arguments are unknown and a positive modulus
1267      * is needed it can be computed as {@code (floorMod(x, y) + abs(y)) % abs(y)}.
1268      *
1269      * @param x the dividend
1270      * @param y the divisor
1271      * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
1272      * @throws ArithmeticException if the divisor {@code y} is zero
1273      * @see #floorDiv(int, int)
1274      * @since 1.8
1275      */
1276     public static int floorMod(int x, int y) {
1277         int mod = x % y;
1278         // if the signs are different and modulo not zero, adjust result
1279         if ((mod ^ y) < 0 && mod != 0) {
1280             mod += y;
1281         }
1282         return mod;
1283     }
1284 
1285     /**
1286      * Returns the floor modulus of the {@code long} and {@code int} arguments.
1287      * <p>
1288      * The floor modulus is {@code x - (floorDiv(x, y) * y)},
1289      * has the same sign as the divisor {@code y}, and
1290      * is in the range of {@code -abs(y) < r < +abs(y)}.
1291      *
1292      * <p>
1293      * The relationship between {@code floorDiv} and {@code floorMod} is such that:
1294      * <ul>
1295      *   <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
1296      * </ul>
1297      * <p>
1298      * For examples, see {@link #floorMod(int, int)}.
1299      *
1300      * @param x the dividend
1301      * @param y the divisor
1302      * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
1303      * @throws ArithmeticException if the divisor {@code y} is zero
1304      * @see #floorDiv(long, int)
1305      * @since 9
1306      */
1307     public static int floorMod(long x, int y) {
1308         // Result cannot overflow the range of int.
1309         return (int)floorMod(x, (long)y);
1310     }
1311 
1312     /**
1313      * Returns the floor modulus of the {@code long} arguments.
1314      * <p>
1315      * The floor modulus is {@code x - (floorDiv(x, y) * y)},
1316      * has the same sign as the divisor {@code y}, and
1317      * is in the range of {@code -abs(y) < r < +abs(y)}.
1318      *
1319      * <p>
1320      * The relationship between {@code floorDiv} and {@code floorMod} is such that:
1321      * <ul>
1322      *   <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
1323      * </ul>
1324      * <p>
1325      * For examples, see {@link #floorMod(int, int)}.
1326      *
1327      * @param x the dividend
1328      * @param y the divisor
1329      * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
1330      * @throws ArithmeticException if the divisor {@code y} is zero
1331      * @see #floorDiv(long, long)
1332      * @since 1.8
1333      */
1334     public static long floorMod(long x, long y) {
1335         long mod = x % y;
1336         // if the signs are different and modulo not zero, adjust result
1337         if ((x ^ y) < 0 && mod != 0) {
1338             mod += y;
1339         }
1340         return mod;
1341     }
1342 
1343     /**
1344      * Returns the absolute value of an {@code int} value.
1345      * If the argument is not negative, the argument is returned.
1346      * If the argument is negative, the negation of the argument is returned.
1347      *
1348      * <p>Note that if the argument is equal to the value of
1349      * {@link Integer#MIN_VALUE}, the most negative representable
1350      * {@code int} value, the result is that same value, which is
1351      * negative.
1352      *
1353      * @param   a   the argument whose absolute value is to be determined
1354      * @return  the absolute value of the argument.
1355      */
1356     @HotSpotIntrinsicCandidate
1357     public static int abs(int a) {
1358         return (a < 0) ? -a : a;
1359     }
1360 
1361     /**
1362      * Returns the absolute value of a {@code long} value.
1363      * If the argument is not negative, the argument is returned.
1364      * If the argument is negative, the negation of the argument is returned.
1365      *
1366      * <p>Note that if the argument is equal to the value of
1367      * {@link Long#MIN_VALUE}, the most negative representable
1368      * {@code long} value, the result is that same value, which
1369      * is negative.
1370      *
1371      * @param   a   the argument whose absolute value is to be determined
1372      * @return  the absolute value of the argument.
1373      */
1374     @HotSpotIntrinsicCandidate
1375     public static long abs(long a) {
1376         return (a < 0) ? -a : a;
1377     }
1378 
1379     /**
1380      * Returns the absolute value of a {@code float} value.
1381      * If the argument is not negative, the argument is returned.
1382      * If the argument is negative, the negation of the argument is returned.
1383      * Special cases:
1384      * <ul><li>If the argument is positive zero or negative zero, the
1385      * result is positive zero.
1386      * <li>If the argument is infinite, the result is positive infinity.
1387      * <li>If the argument is NaN, the result is NaN.</ul>
1388      *
1389      * @apiNote As implied by the above, one valid implementation of
1390      * this method is given by the expression below which computes a
1391      * {@code float} with the same exponent and significand as the
1392      * argument but with a guaranteed zero sign bit indicating a
1393      * positive value:<br>
1394      * {@code Float.intBitsToFloat(0x7fffffff & Float.floatToRawIntBits(a))}
1395      *
1396      * @param   a   the argument whose absolute value is to be determined
1397      * @return  the absolute value of the argument.
1398      */
1399     @HotSpotIntrinsicCandidate
1400     public static float abs(float a) {
1401         return (a <= 0.0F) ? 0.0F - a : a;
1402     }
1403 
1404     /**
1405      * Returns the absolute value of a {@code double} value.
1406      * If the argument is not negative, the argument is returned.
1407      * If the argument is negative, the negation of the argument is returned.
1408      * Special cases:
1409      * <ul><li>If the argument is positive zero or negative zero, the result
1410      * is positive zero.
1411      * <li>If the argument is infinite, the result is positive infinity.
1412      * <li>If the argument is NaN, the result is NaN.</ul>
1413      *
1414      * @apiNote As implied by the above, one valid implementation of
1415      * this method is given by the expression below which computes a
1416      * {@code double} with the same exponent and significand as the
1417      * argument but with a guaranteed zero sign bit indicating a
1418      * positive value:<br>
1419      * {@code Double.longBitsToDouble((Double.doubleToRawLongBits(a)<<1)>>>1)}




1257      *   <li>If the signs of the arguments are different, the results differ from the {@code %} operator.<br>
1258      *      <ul>
1259      *      <li>{@code floorMod(+4, -3) == -2}; &nbsp; and {@code (+4 % -3) == +1} </li>
1260      *      <li>{@code floorMod(-4, +3) == +2}; &nbsp; and {@code (-4 % +3) == -1} </li>
1261      *      <li>{@code floorMod(-4, -3) == -1}; &nbsp; and {@code (-4 % -3) == -1 } </li>
1262      *      </ul>
1263      *   </li>
1264      * </ul>
1265      * <p>
1266      * If the signs of arguments are unknown and a positive modulus
1267      * is needed it can be computed as {@code (floorMod(x, y) + abs(y)) % abs(y)}.
1268      *
1269      * @param x the dividend
1270      * @param y the divisor
1271      * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
1272      * @throws ArithmeticException if the divisor {@code y} is zero
1273      * @see #floorDiv(int, int)
1274      * @since 1.8
1275      */
1276     public static int floorMod(int x, int y) {
1277         return x - floorDiv(x, y) * y;





1278     }
1279 
1280     /**
1281      * Returns the floor modulus of the {@code long} and {@code int} arguments.
1282      * <p>
1283      * The floor modulus is {@code x - (floorDiv(x, y) * y)},
1284      * has the same sign as the divisor {@code y}, and
1285      * is in the range of {@code -abs(y) < r < +abs(y)}.
1286      *
1287      * <p>
1288      * The relationship between {@code floorDiv} and {@code floorMod} is such that:
1289      * <ul>
1290      *   <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
1291      * </ul>
1292      * <p>
1293      * For examples, see {@link #floorMod(int, int)}.
1294      *
1295      * @param x the dividend
1296      * @param y the divisor
1297      * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
1298      * @throws ArithmeticException if the divisor {@code y} is zero
1299      * @see #floorDiv(long, int)
1300      * @since 9
1301      */
1302     public static int floorMod(long x, int y) {
1303         // Result cannot overflow the range of int.
1304         return (int)(x - floorDiv(x, y) * y);
1305     }
1306 
1307     /**
1308      * Returns the floor modulus of the {@code long} arguments.
1309      * <p>
1310      * The floor modulus is {@code x - (floorDiv(x, y) * y)},
1311      * has the same sign as the divisor {@code y}, and
1312      * is in the range of {@code -abs(y) < r < +abs(y)}.
1313      *
1314      * <p>
1315      * The relationship between {@code floorDiv} and {@code floorMod} is such that:
1316      * <ul>
1317      *   <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
1318      * </ul>
1319      * <p>
1320      * For examples, see {@link #floorMod(int, int)}.
1321      *
1322      * @param x the dividend
1323      * @param y the divisor
1324      * @return the floor modulus {@code x - (floorDiv(x, y) * y)}
1325      * @throws ArithmeticException if the divisor {@code y} is zero
1326      * @see #floorDiv(long, long)
1327      * @since 1.8
1328      */
1329     public static long floorMod(long x, long y) {
1330         return x - floorDiv(x, y) * y;





1331     }
1332 
1333     /**
1334      * Returns the absolute value of an {@code int} value.
1335      * If the argument is not negative, the argument is returned.
1336      * If the argument is negative, the negation of the argument is returned.
1337      *
1338      * <p>Note that if the argument is equal to the value of
1339      * {@link Integer#MIN_VALUE}, the most negative representable
1340      * {@code int} value, the result is that same value, which is
1341      * negative.
1342      *
1343      * @param   a   the argument whose absolute value is to be determined
1344      * @return  the absolute value of the argument.
1345      */

1346     public static int abs(int a) {
1347         return (a < 0) ? -a : a;
1348     }
1349 
1350     /**
1351      * Returns the absolute value of a {@code long} value.
1352      * If the argument is not negative, the argument is returned.
1353      * If the argument is negative, the negation of the argument is returned.
1354      *
1355      * <p>Note that if the argument is equal to the value of
1356      * {@link Long#MIN_VALUE}, the most negative representable
1357      * {@code long} value, the result is that same value, which
1358      * is negative.
1359      *
1360      * @param   a   the argument whose absolute value is to be determined
1361      * @return  the absolute value of the argument.
1362      */

1363     public static long abs(long a) {
1364         return (a < 0) ? -a : a;
1365     }
1366 
1367     /**
1368      * Returns the absolute value of a {@code float} value.
1369      * If the argument is not negative, the argument is returned.
1370      * If the argument is negative, the negation of the argument is returned.
1371      * Special cases:
1372      * <ul><li>If the argument is positive zero or negative zero, the
1373      * result is positive zero.
1374      * <li>If the argument is infinite, the result is positive infinity.
1375      * <li>If the argument is NaN, the result is NaN.</ul>
1376      *
1377      * @apiNote As implied by the above, one valid implementation of
1378      * this method is given by the expression below which computes a
1379      * {@code float} with the same exponent and significand as the
1380      * argument but with a guaranteed zero sign bit indicating a
1381      * positive value:<br>
1382      * {@code Float.intBitsToFloat(0x7fffffff & Float.floatToRawIntBits(a))}
1383      *
1384      * @param   a   the argument whose absolute value is to be determined
1385      * @return  the absolute value of the argument.
1386      */

1387     public static float abs(float a) {
1388         return (a <= 0.0F) ? 0.0F - a : a;
1389     }
1390 
1391     /**
1392      * Returns the absolute value of a {@code double} value.
1393      * If the argument is not negative, the argument is returned.
1394      * If the argument is negative, the negation of the argument is returned.
1395      * Special cases:
1396      * <ul><li>If the argument is positive zero or negative zero, the result
1397      * is positive zero.
1398      * <li>If the argument is infinite, the result is positive infinity.
1399      * <li>If the argument is NaN, the result is NaN.</ul>
1400      *
1401      * @apiNote As implied by the above, one valid implementation of
1402      * this method is given by the expression below which computes a
1403      * {@code double} with the same exponent and significand as the
1404      * argument but with a guaranteed zero sign bit indicating a
1405      * positive value:<br>
1406      * {@code Double.longBitsToDouble((Double.doubleToRawLongBits(a)<<1)>>>1)}


< prev index next >