<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
<p>Hi Reinier,</p>
<p>I see you asked this here as well as on Stack Overflow. I'll
repeat my answer from Stack Overflow here and then continue with
some additional discussion.</p>
<p>Quick recap: Collection::toArray has a requirement that the
returned array be "safe", whereas Stream::toArray has no such
requirement. In my earlier Stack Overflow answer (which you
quoted) I mentioned something like "if [Stream.toArray] were to
violate its spec", and you asked, what spec?</p>
<p>My answer:</p>
<p>
<blockquote type="cite"><span class="comment-copy">I probably
mistakenly assumed that the Stream::toArray spec had the same
"safety" requirements as Collection::toArray. That was our
intent, as I recall, but it didn't make it into the spec.</span>
</blockquote>
</p>
<p>Now to your questions in this email.</p>
<p>The second question, where to report this, is right here! We can
discuss this and file bugs/PRs etc. if necessary depending on the
outcome of the discussion.</p>
<p>The first question has some subtlety to it. Should we not update
the specification for Stream::toArray to have the same "safety"
requirement as Collection::toArray?</p>
<p>I guess a change would serve to clarify the specification. The
developer of a clean-room implementation of streams might
reasonably think that, if the stream source is an array, that this
array can simply be returned from toArray(). However, that
violates the intent (which is pretty clear in my memory) that the
returned array be freshly created. Usually, adding assertions to
interfaces creates a danger of invalidating existing
implementations. However, I don't think returning an existing
array, especially one that might be aliased, was ever considered
to be valid behavior. Thus, a spec change would be more like
filling a gap that shouldn't have been there in the first place,
not adding a new semantic requirement.<br>
</p>
<p>As a practical matter, there are few third-party implementations,
this requirement is almost impossible to test, and any callers of
toArray() won't change. That is, if they're currently using the
returned array, they'll continue using it; but if they want 100%
assurance the array isn't aliased, they'll continue to make a
defensive copy. So, it doesn't seem like changing the spec will
have any practical impact.</p>
<p>Have I answered your questions?</p>
<p>s'marks<br>
</p>
<br>
<div class="moz-cite-prefix">On 12/14/23 5:46 AM, Reinier
Zwitserloot wrote:<br>
</div>
<blockquote type="cite" cite="mid:CAK6PxWMmLWkBWemO2E529TDwc1gGiPq6WUK2n+4v0kuP-_f_YQ@mail.gmail.com">
<div dir="ltr">Hi core libs team,</div>
<div dir="ltr"><br>
</div>
<div dir="ltr">I think I found a rather inconsequential and
esoteric bug, though the term is somewhat less objectively
defined when the problem exists solely in how complete some
method’s javadoc is.<br>
</div>
<div><br>
</div>
<div dir="ltr">Two questions: Is there a plausible argument that
the javadoc as is, shouldn’t be updated? If not, what’s the
right place to report this javadoc ‘bug’?<br>
<div><br>
</div>
<div dir="ltr">The issue:</div>
<div>
<div><br>
</div>
<div dir="ltr">A snippet of the javadoc of Collection.toArray,
from current HEAD jdk22u:</div>
<div dir="ltr"><br>
</div>
<div dir="ltr"> <p>The returned array will be "safe"
in that no references to it are</div>
<div dir="ltr"> * maintained by this collection. (In
other words, this method must</div>
<div dir="ltr"> * allocate a new array even if this
collection is backed by an array).</div>
<div dir="ltr"> * The caller is thus free to modify the
returned array.</div>
<div dir="ltr"><br>
</div>
<div dir="ltr">The javadoc of Stream.toArray, from current
HEAD jdk22u - has no such rider anywhere in its
documentation nor on the javadoc of the Stream interface,
nor on the package javadoc. The javadoc is quite short; the
complete docs on toArray():</div>
<div dir="ltr"><br>
</div>
<div dir="ltr"> /**</div>
<div dir="ltr"> * Returns an array containing the elements
of this stream.</div>
<div dir="ltr"> *</div>
<div dir="ltr"> * <p>This is a <a
href="package-summary.html#StreamOps">terminal</div>
<div dir="ltr"> * operation</a>.</div>
<div dir="ltr"> *</div>
<div dir="ltr"> * @return an array, whose {@linkplain
Class#getComponentType runtime component</div>
<div dir="ltr"> * type} is {@code Object}, containing the
elements of this stream</div>
<div dir="ltr"> */</div>
<div dir="ltr"><br>
</div>
<div dir="ltr">The more usually used variant taking a function
that makes the array has slightly longer javadoc, but it
similarly makes no mention whatsoever about the contract
stipulation that any implementors must not keep a reference.</div>
<div dir="ltr"><br>
</div>
<div dir="ltr">A snippet from Stuart Marks on a stack overflow
question about a to the asker weird choice about stream’s
toList()’s default implementation (<a href="https://stackoverflow.com/questions/77473755/is-it-necessary-to-copy-a-list-to-be-safe/77474199?noredirect=1#comment136909551_77474199" moz-do-not-send="true" class="moz-txt-link-freetext">https://stackoverflow.com/questions/77473755/is-it-necessary-to-copy-a-list-to-be-safe/77474199?noredirect=1#comment136909551_77474199</a>):</div>
<div dir="ltr"><br>
</div>
<div dir="ltr"> <span class="comment-copy" style="margin:0px;padding:0px;border:0px;font-variant-ligatures:normal;font-variant-numeric:inherit;font-variant-east-asian:inherit;font-variant-alternates:inherit;font-stretch:inherit;line-height:inherit;font-family:-apple-system,system-ui,"Segoe
UI Adjusted","Segoe UI","Liberation
Sans",sans-serif;font-kerning:inherit;font-feature-settings:inherit;vertical-align:baseline;box-sizing:inherit;color:rgb(12,13,14);text-decoration-style:initial;text-decoration-color:initial">@Holger
The extra step in the default implementation is there to
force a defensive copy if <code style="margin:0px;padding:1px 5px;border:0px;font-style:inherit;font-variant-ligatures:inherit;font-variant-caps:inherit;font-variant-alternates:inherit;font-variant-numeric:inherit;font-variant-east-asian:inherit;font-stretch:inherit;line-height:inherit;font-family:var(--ff-mono);font-kerning:inherit;font-feature-settings:inherit;vertical-align:baseline;box-sizing:inherit;white-space:pre-wrap">this.toArray</code> were
to violate its spec and keep a reference to the returned
array. Without the defensive copy, it would be possible to
modify the list returned from the default <code style="margin:0px;padding:1px 5px;border:0px;font-style:inherit;font-variant-ligatures:inherit;font-variant-caps:inherit;font-variant-alternates:inherit;font-variant-numeric:inherit;font-variant-east-asian:inherit;font-stretch:inherit;line-height:inherit;font-family:var(--ff-mono);font-kerning:inherit;font-feature-settings:inherit;vertical-align:baseline;box-sizing:inherit;white-space:pre-wrap">toList</code> implementation.</span><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe
UI Adjusted","Segoe UI","Liberation
Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial"> </span></div>
<div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe
UI Adjusted","Segoe UI","Liberation
Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial"><br>
</span></div>
<div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe
UI Adjusted","Segoe UI","Liberation
Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial"><br>
</span></div>
<div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe
UI Adjusted","Segoe UI","Liberation
Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial">Which
leads to the obvious question: Where is that ’spec’ that
Stuart is referring to? Either the javadoc is the spec and
therefore the javadoc is buggy, in that it fails to
mention this stipulation, or the spec is elsewhere, in
which case surely the javadoc should link to it or copy
it.</span></div>
<div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe
UI Adjusted","Segoe UI","Liberation
Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial"><br>
</span></div>
<div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe
UI Adjusted","Segoe UI","Liberation
Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial">Possibly
this is jus filed away as: “Unlike with Collection, Stream
instances are disposable; after a terminal operation (and
toArray is terminal) has been invoked on it, that stream
object has ceased being useful. Therefore, there is no
perceived value to caching any created array, therefore,
it doesn’t need mentioning".</span></div>
<div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe
UI Adjusted","Segoe UI","Liberation
Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial"><br>
</span></div>
<div dir="ltr"><span style="color:rgb(12,13,14);font-family:-apple-system,system-ui,"Segoe
UI Adjusted","Segoe UI","Liberation
Sans",sans-serif;font-variant-ligatures:normal;text-decoration-style:initial;text-decoration-color:initial">Except,
as per Stuart’s comment, actual OpenJDK code is written
partly to deal with any violators of this invisible spec,
and the discrepancy (where Collection.toArray explicitly
mentions the contract stipulation that toArray() must make
safe arrays, but Stream’s toArray() does not) suggests a
fundamental difference where none exists (in fact,
literally: Apparently its a spec violation if your Stream
implementation return a non-safe array from toArray!)</span></div>
<div dir="ltr"><br>
</div>
<div dir="ltr"> --Reinier Zwitserloot<br>
</div>
</div>
</div>
</blockquote>
</body>
</html>