RFR: 8247373: ArraysSupport.newLength doc, test, and exception message

[Stuart Marks]

On Mon, 7 Dec 2020 16:05:11 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> The origin of this code is in collections like ArrayList that have an existing array (hence oldLength >= 0) and that need it to grow (hence minGrowth > 0). Those were the prevailing assumptions in the code from which this was derived, so they turn into preconditions here. I don't see the need to try to make this handle any more cases than it currently does. Doing so complicates the analysis and possibly the code as well. Certainly a bug in a caller might be difficult to track down, but I don't want to add argument checking or to provide "reasonable" behavior in the face of unreasonable inputs. This is an internal method; bugs in callers should be fixed.
>
> The algorithm can be well defined for minGrowth and prefGrowth == 0 without extra checks or exceptions with a careful look at the inequality checks.
> For example, as currently coded, if both are zero, it returns SOFT_MAX_ARRAY_LENGTH. 
> Changing the `0 < prefLength` to `0 <= prefLength` would return minGrowth and avoid a very large but unintentional allocation.

That's only true if oldLength is zero. The behavior is different if oldLength is positive. In any case, this method is called when the array needs to **grow**, which means the caller needs to reallocate and copy. If the caller passes zero for both minGrowth and prefGrowth, the caller doesn't need to reallocate and copy, and there's no point in it calling this method in the first place.

-------------

PR: https://git.openjdk.java.net/jdk/pull/1617