Summary

Add vector and scalar binary operations to support signed and unsigned saturating addition and subtraction. Add vector and scalar binary operations for computing the unsigned minimum and maximum of two operands.

Problem

Certain SIMD algorithms require the use of signed and unsigned saturating arithmetic, and unsigned minimum and maximum of two operands. Vector hardware instructions exist on common hardware for such operations but the Vector API cannot express those operations.

Solution

Add new constants to VectorOperators corresponding to the new vector binary operations. Define the equivalent scalar binary operations in the class VectorMath in support of those vector binary operations.

Specification

The following static methods will be added to class VectorMath, where P is an integral primitive type of byte, short, int, or long.

P VectorMath.addSaturating(P a, P b)
P VectorMath.subSaturating(P a, P b)
P VectorMath.addSaturatingUnsigned(P a, P b)
P VectorMath.subSaturatingUnsigned(P a, P b)
P VectorMath.minUnsigned(P a, P b)
P VectorMath.maxUnsigned(P a, P b)

The following presents the specifications when P is long. For the other integral types the specification is almost identical except for the upper and lower bounds that are specified in accordance with the integral type.

    /**
     * Adds two {@code long} values using saturation
     * arithemetic. The lower and upper (inclusive) bounds are
     * {@code Long.MIN_VALUE} and {@code Long.MAX_VALUE}, respectively.
     * <p>
     * If the result of the addition would otherwise overflow from
     * a positive value to a negative value then the result is clamped
     * to the upper bound {@code Long.MAX_VALUE}.
     * If the result of the addition would otherwise underflow from
     * a negative value to a positive value then the result is clamped
     * to lower bound {@code Long.MIN_VALUE}.
     *
     * @param a the first operand.
     * @param b the second operand.
     * @return the saturating addition of the operands.
     * @see VectorOperators#SADD
     */
    public static long addSaturating(long a, long b)

    /**
     * Subtracts two {@code long} values using saturation
     * arithemetic. The lower and upper (inclusive) bounds are
     * {@code Long.MIN_VALUE} and {@code Long.MAX_VALUE}, respectively.
     * <p>
     * If the result of the subtraction would otherwise overflow from
     * a positive value to a negative value then the result is clamped
     * to the upper bound {@code Long.MAX_VALUE}.
     * If the result of the subtraction would otherwise underflow from
     * a negative value to a positive value then the result is clamped
     * to lower bound {@code Long.MIN_VALUE}.
     *
     * @param a the first operand.
     * @param b the second operand.
     * @return the saturating difference of the operands.
     * @see VectorOperators#SSUB
     */
    public static long subSaturating(long a, long b)

    /**
     * Adds two {@code long} values using saturation
     * arithemetic and numerically treating the values
     * as unsigned. The lower and upper (inclusive) bounds
     * are {@code 0L} and {@code 0xFFFFFFFF_FFFFFFFFL}, respectively,
     * numerically treating them as unsigned.
     * <p>
     * If the result of the unsigned addition would otherwise overflow
     * from the greater of the two operands to a lesser value then the
     * result is clamped to the upper bound {@code 0xFFFFFFFF_FFFFFFFFL}.
     *
     * @param a the first operand.
     * @param b the second operand.
     * @return the saturating addition of the operands.
     * @see VectorOperators#SUADD
     */
    public static long addSaturatingUnsigned(long a, long b)

    /**
     * Subtracts two {@code long} values using saturation
     * arithemetic and numerically treating the values
     * as unsigned. The lower and upper (inclusive) bounds
     * are {@code 0L} and {@code 0xFFFFFFFF_FFFFFFFFL}, respectively,
     * numerically treating them as unsigned.
     * <p>
     * If the result of the unsigned subtraction would otherwise underflow
     * from the lesser of the two operands to a greater value then the
     * result is clamped to the lower bound {@code 0L}.
     *
     * @param a the first operand.
     * @param b the second operand.
     * @return the saturating difference of the operands.
     * @see VectorOperators#SUSUB
     */
    public static long subSaturatingUnsigned(long a, long b)

    /**
     * Returns the smaller of two {@code long} values numerically treating
     * the values as unsigned. That is, the result is the operand closer
     * to the value of the expression {@code 0L}. If the operands have the
     * same value, the result is that same value.
     *
     * @param a the first operand.
     * @param b the second operand.
     * @return the smaller of {@code a} and {@code b}.
     * @see VectorOperators#UMIN
     */
    public static long minUnsigned(long a, long b)

    /**
     * Returns the greater of two {@code long} values numerically treating
     * the values as unsigned. That is, the result is the operand closer
     * to the value of the expression {@code 0xFFFFFFFF_FFFFFFFFL} numerically
     * treating it as unsigned. If the operands have the same value,
     * the result is that same value.
     *
     * @param a the first operand.
     * @param b the second operand.
     * @return the larger of {@code a} and {@code b}.
     * @see VectorOperators#UMAX
     */
    public static long maxUnsigned(long a, long b)

The following static final constants, operators, are added to class VectorOperators for integral only vectors.

    /** Produce saturating {@code a+b}.  Integral only.
     * @see VectorMath#addSaturating(int, int)
     */
    public static final Binary SADD = ...;
    /** Produce saturating unsigned {@code a+b}.  Integral only.
     * @see VectorMath#addSaturatingUnsigned(int, int)
     */
    public static final Binary SUADD = ...;
    /** Produce saturating {@code a-b}.  Integral only.
     * @see VectorMath#subSaturating(int, int)
     */
    public static final Binary SSUB = ...;
    /** Produce saturating unsigned {@code a-b}.  Integral only.
     * @see VectorMath#subSaturatingUnsigned(int, int)
     */
    public static final Binary SUSUB = ...;
    /** Produce unsigned {@code min(a,b)}.  Integral only.
     * @see VectorMath#minUnsigned(int, int)
     */
    public static final Associative UMIN = ...;
    /** Produce unsigned {@code max(a,b)}.  Integral only.
     * @see VectorMath#maxUnsigned(int, int)
     */
    public static final Associative UMAX = ...;

Only the last two are associative.

In addition the existing unsigned comparison operators have been renamed using the same convention as above:

• UNSIGNED_LT was renamed to ULT.
• UNSIGNED_LE was renamed to ULE.
• UNSIGNED_GT was renamed to UGT.
• UNSIGNED_GE was renamed to UGE.