[vector] java doc for iota()

[Viswanathan, Sandhya]

Hi Paul,

This change looks good to me.

Best Regards,
Sandhya


From: Paul Sandoz <paul.sandoz at oracle.com>
Sent: Monday, November 18, 2019 1:01 PM
To: Viswanathan, Sandhya <sandhya.viswanathan at intel.com>
Cc: panama-dev at openjdk.java.net
Subject: Re: [vector] java doc for iota()

Hi Sandhya,

How about this:

diff -r 4e1b42f04b63 src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorShuffle.java
--- a/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorShuffle.java    Fri Nov 15 16:13:16 2019 +0800
+++ b/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorShuffle.java    Mon Nov 18 12:59:22 2019 -0800
@@ -346,14 +346,19 @@
      * Creates a shuffle using source indexes set to sequential
      * values starting from {@code start} and stepping
      * by the given {@code step}.
-     * If {@code wrap} is true, also reduce each index (as if
-     * by {@link VectorShuffle#wrapIndex(int) wrapIndex})
-     * to the valid range {@code [0..VLENGTH-1]}.
      * <p>
      * This method returns the value of the expression
      * {@code VectorShuffle.fromOp(species, i -> R(start + i * step))},
      * where {@code R} is {@code wrapIndex} if {@code wrap} is true,
      * and is the identity function otherwise.
+     * <p>
+     * If {@code wrap} is false each index is validated
+     * against the species {@code VLENGTH}, and (if invalid)
+     * is partially wrapped to an exceptional index in the
+     * range {@code [-VLENGTH..-1]}.
+     * Otherwise, if {@code wrap} is true, also reduce each index, as if
+     * by {@link VectorShuffle#wrapIndex(int) wrapIndex},
+     * to the valid range {@code [0..VLENGTH-1]}.
      *
      * @apiNote The {@code wrap} parameter should be set to {@code
      * true} if invalid source indexes should be wrapped.  Otherwise,
diff -r 4e1b42f04b63 src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorSpecies.java
--- a/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorSpecies.java    Fri Nov 15 16:13:16 2019 +0800
+++ b/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorSpecies.java    Mon Nov 18 12:59:22 2019 -0800
@@ -645,14 +645,19 @@
      * Creates a shuffle using source indexes set to sequential
      * values starting from {@code start} and stepping
      * by the given {@code step}.
-     * If {@code wrap} is true, also reduce each index, as if
-     * by {@link VectorShuffle#wrapIndex(int) wrapIndex},
-     * to the valid range {@code [0..VLENGTH-1]}.
      * <p>
      * This method returns the value of the expression
      * {@code shuffleFromOp(i -> R(start + i * step))},
      * where {@code R} is {@code wrapIndex} if {@code wrap} is true,
      * and is the identity function otherwise.
+     * <p>
+     * If {@code wrap} is false each index is validated
+     * against the species {@code VLENGTH}, and (if invalid)
+     * is partially wrapped to an exceptional index in the
+     * range {@code [-VLENGTH..-1]}.
+     * Otherwise, if {@code wrap} is true, also reduce each index, as if
+     * by {@link VectorShuffle#wrapIndex(int) wrapIndex},
+     * to the valid range {@code [0..VLENGTH-1]}.
      *
      * @apiNote The {@code wrap} parameter should be set to {@code
      * true} if invalid source indexes should be wrapped.  Otherwise,


Thanks,
Paul.


On Nov 12, 2019, at 2:53 PM, Viswanathan, Sandhya <sandhya.viswanathan at intel.com<mailto:sandhya.viswanathan at intel.com>> wrote:

Hi Paul,

There is another place, where the java doc may need to change.

The Java implementation of iota() performs full wrapping when “wrap” is passed as true, otherwise it does partial wrapping.
Whereas the java doc below in VectorShuffle.java doesn’t mention partial wrapping at all:
    /**
     * Creates a shuffle using source indexes set to sequential
     * values starting from {@code start} and stepping
     * by the given {@code step}.
     * If {@code wrap} is true, also reduce each index (as if
     * by {@link VectorShuffle#wrapIndex(int) wrapIndex})
     * to the valid range {@code [0..VLENGTH-1]}.
     * <p>
     * This method returns the value of the expression
     * {@code VectorShuffle.fromOp(species, i -> R(start + i * step))},
     * where {@code R} is {@code wrapIndex} if {@code wrap} is true,
     * and is the identity function otherwise.
     * ......
     */
public static <E> VectorShuffle<E> iota(VectorSpecies<E> species,
                                            int start, int step,
                                            boolean wrap) {

There is mention of partial wrapping in java doc of fromValues in VectorShuffle.java:
    *
     * <p> For each shuffle lane, where {@code N} is the shuffle lane
     * index, the {@code N}th index value is validated
     * against the species {@code VLENGTH}, and (if invalid)
     * is partially wrapped to an exceptional index in the
     * range {@code [-VLENGTH..-1]}.

Best Regards,
Sandhya