RFR: 8251989: Hex formatting and parsing utility [v4]

[Roger Riggs]

On Fri, 16 Oct 2020 14:46:11 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>>> Since the instances are immutable, it seemed useful to emphasize that only the instance returned has the requested
>>> change. Discarding the return value was incorrect programming. The original instance is not modified.
>> 
>> Understood, and agree.
>> 
>>> The "copy" phrasing was used throughout java.time.
>> 
>> Ok, but that does not mean that it is appropriate or correct.
>> 
>>> Since reference equality is specifically dis-allowed for value-based objects, there is no way to discover a difference
>>> between a copy and the original with the same parameters.
>> 
>> A _copy_ implies that something identical or similar is _created_ or _made_, but that does not *always* have to be the
>> case here, but the spec *requires* it. Why not just; "Returns a formatter similar to this formatter with the given
>> delimiter". OR something along those lines.
>
> The HexFormat API currently uses an indexing model for arrays and strings based on an index and a length.
> Many other APIs in the JDK use an index model of `fromIndex` and `toIndex` (exclusive).
> 
> They are equivalent and convertible but many programming bugs occur in corners of APIs like this.
> Which indexing convention should HexFormat follow?

> A copy implies that something identical or similar is created or made, but that does not always have to be the case
> here, but the spec requires it. Why not just; "Returns a formatter similar to this formatter with the given delimiter".
> OR something along those lines.

With value-based objects, copies are *always* made, two references to the value are indistinguishable.
The phrasing needs to express that what you get is the same as the original with the parameter requested.
The wording has been a bike-shedding topic in Valhalla for a couple of years.

The usage of 'copy' in java.time did receive a lot of attention and review and is a precedent.

The 'similar to' phrasing is too ambiguous.

How about:
`Returns a HexFormat with the xxx and other parameters from this HexFormat.`

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

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