On Fri, 16 Oct 2020 14:46:11 GMT, Roger Riggs <rri...@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
