diff --git a/src/java.base/share/classes/java/lang/Integral.java b/src/java.base/share/classes/java/lang/Integral.java new file mode 100644 index 00000000000..52e17bd2a39 --- /dev/null +++ b/src/java.base/share/classes/java/lang/Integral.java @@ -0,0 +1,96 @@ +/* + * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package java.lang; + +/** + * Indicates a type supports integer-related bit-wise operators and + * shifts ({@code &}, {@code |}, {@code ^}, {@code ~}, {@code <<}, + * {@code >>}, {@code >>>}) and participates in operator overloading + * of those operators. + * + * @param The integral type + */ +public interface Integral> + extends Numerics, OrderedComparison { + + /** + * {@return the AND-ing of the two operands} + * + * @param op1 the first operand + * @param op2 the second operand + */ + /*static*/ IT and(IT op1, IT op2); + + /** + * {@return the OR-ing of the two operands} + * + * @param op1 the first operand + * @param op2 the second operand + */ + /*static*/ IT or(IT op1, IT op2); + + /** + * {@return the XOR-ing of the two operands} + * + * @param op1 the first operand + * @param op2 the second operand + */ + /*static*/ IT xor(IT op1, IT op2); + + /** + * {@return the complement of the operand} + * + * @param op1 the operand + */ + /*static*/ IT complement(IT op1); + + /** + * {@return the first operand left shifted by the distance + * indicated by the second operand} + * + * @param op1 the operand to be shifted + * @param shiftDistance the shift distance + */ + /*static*/ IT leftShift(IT op1, int shiftDistance); + + /** + * {@return the first operand right shifted by the distance + * indicated by the second operand} + * + * @param op1 the operand to be shifted + * @param shiftDistance the shift distance + */ + /*static*/ IT rightShift(IT op1, int shiftDistance); + + /** + * {@return the first operand right shifted, unsigned, by the + * distance indicated by the second operand} + * + * @param op1 the operand to be shifted + * @param shiftDistance the shift distance + */ + /*static*/ IT rightShiftUnsigned(IT op1, int shiftDistance); +} diff --git a/src/java.base/share/classes/java/lang/OrderedComparison.java b/src/java.base/share/classes/java/lang/OrderedComparison.java new file mode 100644 index 00000000000..196dd8aba85 --- /dev/null +++ b/src/java.base/share/classes/java/lang/OrderedComparison.java @@ -0,0 +1,96 @@ +/* + * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package java.lang; + +/** + * Indicates a type supports ordered comparison operations ({@code + * <}, {@code <=}, {@code >}, {@code >=}) and participates in operator + * overloading of those operators. + * + * @param The type supporting ordered comparison + */ +public interface OrderedComparison> { + /** + * {@return {@code true} if the first operand is less than the second + * operand; {@code false} otherwise} + * + * @param op1 the first operand + * @param op2 the second operand + */ + /*static*/ boolean lessThan(OC op1, OC op2); + + /** + * {@return {@code true} if the first operand is less than or + * equal to the second operand; {@code false} otherwise} + * + * @param op1 the first operand + * @param op2 the second operand + */ + /*static*/ boolean lessThanEqual(OC op1, OC op2); + + /** + * {@return {@code true} if the first operand is greater than the second + * operand; {@code false} otherwise} + * + * @param op1 the first operand + * @param op2 the second operand + */ + /*static*/ boolean greaterThan(OC op1, OC op2); + + /** + * {@return {@code true} if the first operand is greater than or + * equal to the second operand; {@code false} otherwise} + * + * @param op1 the first operand + * @param op2 the second operand + */ + /*static*/ boolean greaterThanEqual(OC op1, OC op2); + + + /** + * {@return the smaller of the two operands} + * + * @apiNote + * Subtypes of this interface can define policies concerning which + * operand to return if they are the same size. + * + * @param op1 the first operand + * @param op2 the second operand + */ + /*static*/ OC min(OC op1, OC op2); + + /** + * {@return the larger of the two operands} + * + * @apiNote + * Subtypes of this interface can define policies concerning which + * operand to return if they are the same size. + * + * @param op1 the first operand + * @param op2 the second operand + */ + /*static*/ OC max(OC op1, OC op2); +} diff --git a/src/java.base/share/classes/java/lang/StandardFloatingPoint.java b/src/java.base/share/classes/java/lang/StandardFloatingPoint.java new file mode 100644 index 00000000000..1bc899d218a --- /dev/null +++ b/src/java.base/share/classes/java/lang/StandardFloatingPoint.java @@ -0,0 +1,163 @@ +/* + * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package java.lang; + +/** + * Indicate a floating-point type in the style of a IEEE 754 standard + * floating-point type. + * + * @param The standard floating-point type + */ +public interface StandardFloatingPoint> + extends Numerics, OrderedComparison { + + // todo: overrides for <, <=, >, >= + + /** + * {@return the smaller of the two operands} + * + * @apiNote + * Explain all the IEEE 754-isms + * + * @param op1 the first operand + * @param op2 the second operand + */ + @Override + /*static*/ SFP min(SFP op1, SFP op2); + + /** + * {@return the larger of the two operands} + * + * @apiNote + * Explain all the IEEE 754-isms + * + * @param op1 the first operand + * @param op2 the second operand + */ + @Override + /*static*/ SFP max(SFP op1, SFP op2); + + /** + * {@return the square root of the operand} The square root is + * computed using the round to nearest rounding policy. + * + * @apiNote + * This method corresponds to the squareRoot operation defined in + * IEEE 754. + * + * @param radicand the argument to have its square root taken + * + */ + /*static*/ SFP sqrt(SFP radicand); + + /** + * Returns the fused multiply add of the three arguments; that is, + * returns the exact product of the first two arguments summed + * with the third argument and then rounded once to the nearest + * floating-point value. + * + * @apiNote This method corresponds to the fusedMultiplyAdd + * operation defined in IEEE 754. + * + * @param a a value + * @param b a value + * @param c a value + * + * @return (a × b + c) + * computed, as if with unlimited range and precision, and rounded + * once to the nearest floating-point value + */ + /*static*/ SFP fma(SFP a, SFP b, SFP c); + + /** + * Returns {@code true} if the specified number is a + * Not-a-Number (NaN) value, {@code false} otherwise. + * + * @apiNote + * This method corresponds to the isNaN operation defined in IEEE + * 754. + * + * @param operand the value to be tested. + * @return {@code true} if the argument is NaN; + * {@code false} otherwise. + */ + /*static*/ boolean isNaN(SFP operand); + + /** + * Returns {@code true} if the specified number is infinitely + * large in magnitude, {@code false} otherwise. + * + * @apiNote + * This method corresponds to the isInfinite operation defined in + * IEEE 754. + * + * @param operand the value to be tested. + * @return {@code true} if the argument is positive infinity or + * negative infinity; {@code false} otherwise. + */ + /*static*/ boolean isInfinite(SFP operand); + + /** + * Returns {@code true} if the argument is a finite floating-point + * value; returns {@code false} otherwise (for NaN and infinity + * arguments). + * + * @apiNote + * This method corresponds to the isFinite operation defined in + * IEEE 754. + * + * @param operand the {@code SFP} value to be tested + * @return {@code true} if the argument is a finite + * floating-point value, {@code false} otherwise. + */ + /*static*/ boolean isFinite(SFP operand); + + /** + * Returns the size of an ulp of the argument. + * + *

Special Cases: + *

    + *
  • If the argument is NaN, then the result is NaN. + *
  • If the argument is positive or negative infinity, then the + * result is positive infinity. + *
  • If the argument is positive or negative zero, then the result is + * the minimum value of the format. + *
+ * + * @param operand the floating-point value whose ulp is to be returned + * @return the size of an ulp of the argument + */ + /*static*/ SFP ulp(SFP operand); + + /** + * Returns a hexadecimal string representation of the argument. + * + * @param operand the value to be converted. + * @return a hex string representation of the argument. + * + */ + /*static*/ String toHexString(SFP operand); +}