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

Incorrect @throws doc for MemorySegment::getString

XMLWordPrintable

    • Icon: CSR CSR
    • Resolution: Approved
    • Icon: P3 P3
    • 24
    • core-libs
    • None
    • behavioral
    • minimal
    • The exception type remains the same, but the specified triggering condition is updated to reflect the implementation. The old triggering condition referred to a parameter that did not exist, so it is highly unlikely this will imply any incompatibilities.
    • Java API
    • SE

      Summary

      Correct specification errors in the MemroySegment::getString overloads.

      Problem

      Two of the @throws clauses were erroneously copied from MemorySegment::setString specification.

      Solution

      Correct the specification to reflect the actual behavior.

      Specification

      diff --git a/src/java.base/share/classes/java/lang/foreign/MemorySegment.java b/src/java.base/share/classes/java/lang/foreign/MemorySegment.java
      index cd38bd1922775..024dfacb71b7e 100644
      --- a/src/java.base/share/classes/java/lang/foreign/MemorySegment.java
      +++ b/src/java.base/share/classes/java/lang/foreign/MemorySegment.java
      @@ -1277,9 +1277,9 @@ MemorySegment reinterpret(long newSize,
            * @throws IllegalArgumentException if the size of the string is greater than the
            *         largest string supported by the platform
            * @throws IndexOutOfBoundsException if {@code offset < 0}
      -     * @throws IndexOutOfBoundsException if {@code offset > byteSize() - (B + 1)}, where
      -     *         {@code B} is the size, in bytes, of the string encoded using UTF-8 charset
      -     *         {@code str.getBytes(StandardCharsets.UTF_8).length})
      +     * @throws IndexOutOfBoundsException if no string terminator (e.g. {@code '\0'}) is
      +     *         present in this segment between the given {@code offset} and the end of
      +     *         this segment.
            * @throws IllegalStateException if the {@linkplain #scope() scope} associated with
            *         this segment is not {@linkplain Scope#isAlive() alive}
            * @throws WrongThreadException if this method is called from a thread {@code T},
      @@ -1315,14 +1315,11 @@ MemorySegment reinterpret(long newSize,
            * @throws IllegalArgumentException  if the size of the string is greater than the
            *         largest string supported by the platform
            * @throws IndexOutOfBoundsException if {@code offset < 0}
      -     * @throws IndexOutOfBoundsException if {@code offset > byteSize() - (B + N)}, where:
      -     *         <ul>
      -     *             <li>{@code B} is the size, in bytes, of the string encoded using the
      -     *             provided charset (e.g. {@code str.getBytes(charset).length});</li>
      -     *             <li>{@code N} is the size (in bytes) of the terminator char according
      -     *             to the provided charset. For instance, this is 1 for
      -     *             {@link StandardCharsets#US_ASCII} and 2 for {@link StandardCharsets#UTF_16}.</li>
      -     *         </ul>
      +     * @throws IndexOutOfBoundsException if no string terminator (e.g. {@code '\0'}) is
      +     *         present in this segment between the given {@code offset} and the end of
      +     *         this segment. The byte size of the string terminator depends on the
      +     *         selected {@code charset}. For instance, this is 1 for
      +     *         {@link StandardCharsets#US_ASCII} and 2 for {@link StandardCharsets#UTF_16}
            * @throws IllegalStateException if the {@linkplain #scope() scope} associated with
            *         this segment is not {@linkplain Scope#isAlive() alive}
            * @throws WrongThreadException if this method is called from a thread {@code T},

            pminborg Per-Ake Minborg
            pminborg Per-Ake Minborg
            Jorn Vernee, Maurizio Cimadamore
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved: