Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8219608

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

XMLWordPrintable

    • Icon: CSR CSR
    • Resolution: Approved
    • Icon: P4 P4
    • 13
    • core-libs
    • None
    • behavioral
    • minimal
    • New methods in classes that cannot be extended outside of the java.nio package so there is no compatibility risk.
    • Java API
    • SE

      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);

            bpb Brian Burkhalter
            jssunw Jitender S (Inactive)
            Alan Bateman, Roger Riggs
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: