On Fri, 16 Oct 2020 14:24:41 GMT, Chris Hegarty <che...@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
