(bf) Add ByteBuffer.slice(int index, int length)

Summary

Add a slice method to Buffer and its type specific subclasses to create a subsequence given an absolute position and size.

Problem

The java.nio.Buffer and java.nio.$Type$Buffer classes, where $Type$ is in {Byte, Char, Double, Float, Int, Long, Short}, currently define a slice() method to create a sub-sequence of the buffer delimited by the current position and limit. There is however no method to create such a view defined by an absolute position and size. This is asymmetric with the put() and get() methods which both have variants which use the absolute position.

Solution

Add a slice(int,int) which which creates a sub-sequence of a specified size at a specified absolute offset. The only API changes are to the java.nio.*Buffer classes.

java.nio.Buffer

Modify "additional operations" section of class-level javadoc:

@@ -134,8 +134,9 @@
  *   it already contains: It leaves the limit unchanged and sets the position
  *   to zero.  </p></li>
  *
- *   <li><p> {@link #slice} creates a subsequence of a buffer: It leaves the
- *   limit and the position unchanged. </p></li>
+ *   <li><p> The {@link #slice} and {@link #slice(int,int) slice(index,length)}
+ *   methods create a subsequence of a buffer: They leave the limit and the
+ *   position unchanged. </p></li>
  *
  *   <li><p> {@link #duplicate} creates a shallow copy of a buffer: It leaves
  *   the limit and the position unchanged. </p></li>
@

Method specification:

/**
     * Creates a new buffer whose content is a shared subsequence of
     * this buffer's content.
     *
     * <p> The content of the new buffer will start at position {@code index}
     * in this buffer, and will contain {@code length} elements. Changes to
     * this buffer's content will be visible in the new buffer, and vice versa;
     * the two buffers' position, limit, and mark values will be independent.
     *
     * <p> The new buffer's position will be zero, its capacity and its limit
     * will be {@code length}, its mark will be undefined. The new buffer will
     * be direct if, and only if, this buffer is direct, and it will be
     * read-only if, and only if, this buffer is read-only.  </p>
     *
     * @param   index
     *          The position in this buffer at which the content of the new
     *          buffer will start; must be non-negative and no larger than
     *          {@link #limit() limit()}
     *
     * @param   length
     *          The number of elements the new buffer will contain; must be
     *          non-negative and no larger than {@code limit() - index}
     *
     * @return  The new buffer
     *
     * @throws  IndexOutOfBoundsException
     *          If {@code index} is negative or greater than {@code limit()},
     *          {@code length} is negative, or {@code length > limit() - index}
     *
     * @since 13
     */
    public abstract Buffer slice(int index, int length);

java.nio.$Type$Buffer

For java.nio.$TypeBuffer$, $Type$ is in {Byte, Char, Double, Float, Int, Short} and, respectively, $type$ is in {byte, char, double, float, int, short}.

    /**
     * Creates a new $type$ buffer whose content is a shared subsequence of
     * this buffer's content.
     *
     * <p> The content of the new buffer will start at position {@code index}
     * in this buffer, and will contain {@code length} elements. Changes to
     * this buffer's content will be visible in the new buffer, and vice versa;
     * the two buffers' position, limit, and mark values will be independent.
     *
     * <p> The new buffer's position will be zero, its capacity and its limit
     * will be {@code length}, its mark will be undefined, and its byte order
     * will be
<h1>if[byte]</h1>

     * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
<h1>else[byte]</h1>

     * identical to that of this buffer.
<h1>end[byte]</h1>

     * The new buffer will be direct if, and only if, this buffer is direct,
     * and it will be read-only if, and only if, this buffer is read-only. </p>
     *
     * @param   index
     *          The position in this buffer at which the content of the new
     *          buffer will start; must be non-negative and no larger than
     *          {@link #limit() limit()}
     *
     * @param   length
     *          The number of elements the new buffer will contain; must be
     *          non-negative and no larger than {@code limit() - index}
     *
     * @return  The new buffer
     *
     * @throws  IndexOutOfBoundsException
     *          If {@code index} is negative or greater than {@code limit()},
     *          {@code length} is negative, or {@code length > limit() - index}
     *
     * @since 13
     */
    @Override
    public abstract $Type$Buffer slice(int index, int length);