On Fri, 16 Oct 2020 15:22:37 GMT, Roger Riggs <rri...@openjdk.org> wrote:
>> 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.` > > 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.` If _copy_ has been bikeshedded a number of previous times and discussed elsewhere, then I'm ok with that. Please leave it as is ( use _copy_ ), since there will be just one common term for developers to learn. Just so long as we agree that it would not preclude an implementation that returns the same instance where all state is the same. ------------- PR: https://git.openjdk.java.net/jdk/pull/482
