RFR: 8377903: ArraysSupport::mismatch should document that they return the smallest index
A doc only change to clarify that the _smallest_ of many possible mismatch indices is returned. ------------- Commit messages: - 8377903: ArraysSupport::mismatch should document that they return the smallest index. Changes: https://git.openjdk.org/jdk/pull/29997/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=29997&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8377903 Stats: 7 lines in 1 file changed: 0 ins; 0 del; 7 mod Patch: https://git.openjdk.org/jdk/pull/29997.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/29997/head:pull/29997 PR: https://git.openjdk.org/jdk/pull/29997
On Mon, 2 Mar 2026 15:29:32 GMT, Raffaello Giulietti <rgiulietti@openjdk.org> wrote:
A doc only change to clarify that the _smallest_ of many possible mismatch indices is returned.
src/java.base/share/classes/jdk/internal/util/ArraysSupport.java line 481:
479: 480: /** 481: * Find the smallest index of a mismatch between two arrays.
The public javadoc uses "first" to describe the one returned. Its also notable, that only 2 mismatch methods have any javadoc. It would sufficient to document them by referring to the public javadoc in Arrays.java. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/29997#discussion_r2873194296
On Mon, 2 Mar 2026 15:50:07 GMT, Roger Riggs <rriggs@openjdk.org> wrote:
A doc only change to clarify that the _smallest_ of many possible mismatch indices is returned.
src/java.base/share/classes/jdk/internal/util/ArraysSupport.java line 481:
479: 480: /** 481: * Find the smallest index of a mismatch between two arrays.
The public javadoc uses "first" to describe the one returned. Its also notable, that only 2 mismatch methods have any javadoc. It would sufficient to document them by referring to the public javadoc in Arrays.java.
"First" would be OK if the doc stated that the search starts with index 0 (or with the "from" indices in the 5 args variant) but it does not. "Smallest" is unambiguous. I opted for the minimal changes of the current doc that are sharp about the result. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/29997#discussion_r2873221186
On Mon, 2 Mar 2026 15:29:32 GMT, Raffaello Giulietti <rgiulietti@openjdk.org> wrote:
A doc only change to clarify that the _smallest_ of many possible mismatch indices is returned.
Good enough. ------------- Marked as reviewed by rriggs (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/29997#pullrequestreview-3877090487
On Mon, 2 Mar 2026 15:29:32 GMT, Raffaello Giulietti <rgiulietti@openjdk.org> wrote:
A doc only change to clarify that the _smallest_ of many possible mismatch indices is returned.
@rgiulietti, judging from `git grep -C 3 ArraysSupport.mismatch` output, `StringLatin1` is the only call-site using the index returned to locate an element: int k = ArraysSupport.mismatch(value, other, lim); return (k < 0) ? len1 - len2 : getChar(value, k) - getChar(other, k); Other call sites are only interested in how the index compares to 0, e.g.: return ArraysSupport.mismatch(a, a2, length) < 0; Does the finding of _"ArraysSupport::mismatch should return the smallest index"_ warrant a dedicated test verifying this behavior? (I could not find any.) Or it is sufficient to rely on the existing `String` tests? ------------- Marked as reviewed by vyazici (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/29997#pullrequestreview-3878467945
On Mon, 2 Mar 2026 15:29:32 GMT, Raffaello Giulietti <rgiulietti@openjdk.org> wrote:
A doc only change to clarify that the _smallest_ of many possible mismatch indices is returned.
Right, test coverage is weak, so a followup PR will be dedicated to add tests of the internal APIs in ArraysSupport. ------------- PR Comment: https://git.openjdk.org/jdk/pull/29997#issuecomment-3990575349
On Mon, 2 Mar 2026 15:29:32 GMT, Raffaello Giulietti <rgiulietti@openjdk.org> wrote:
A doc only change to clarify that the _smallest_ of many possible mismatch indices is returned.
`java.util.Arrays.mismatch(a, b)` also returns the first index. ------------- PR Comment: https://git.openjdk.org/jdk/pull/29997#issuecomment-3991481862
On Mon, 2 Mar 2026 15:29:32 GMT, Raffaello Giulietti <rgiulietti@openjdk.org> wrote:
A doc only change to clarify that the _smallest_ of many possible mismatch indices is returned.
This pull request has now been integrated. Changeset: 0ea7d890 Author: Raffaello Giulietti <rgiulietti@openjdk.org> URL: https://git.openjdk.org/jdk/commit/0ea7d890d98eda32912e9a8340020ee405042576 Stats: 7 lines in 1 file changed: 0 ins; 0 del; 7 mod 8377903: ArraysSupport::mismatch should document that they return the smallest index Reviewed-by: rriggs, vyazici ------------- PR: https://git.openjdk.org/jdk/pull/29997
participants (3)
-
Raffaello Giulietti
-
Roger Riggs
-
Volkan Yazici