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

[Roger Riggs]

On Fri, 16 Oct 2020 14:24:41 GMT, Chris Hegarty <chegar at openjdk.org> wrote:

>>> Maybe I'm being too pedantic, but is the use of the term _copy_ for the withers overly prescriptive, and possibly
>>> limiting an implementation? For example, for `withDelimiter` does _copy_ preclude such an implementation:
>>> ```
>>>      /**
>>>       * Returns a copy of this {@code HexFormat} with the delimiter.
>>>       * @param delimiter the delimiter, non-null, may be empty
>>>       * @return a copy of this {@code HexFormat} with the delimiter
>>>       */
>>>      public HexFormat withDelimiter(String delimiter) {
>>> +        if (delimiter.equals(this.delimiter))
>>> +            return this;
>>>          return new HexFormat(delimiter, this.prefix, this.suffix, this.digits);
>>>      }
>>> ```
>> 
>> 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. The "copy"
>> phrasing was used throughout java.time. 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.
>
>> 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?

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

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