[threeten-dev] [threeten] Reinstate toLocalDate() and friends (#224)

[Stephen Colebourne]

Looks good to me
Stephen


On 30 January 2013 22:22, Roger Riggs <notifications at github.com> wrote:

> Doing a pre-flight on this potential change, please take a look at the
> revised javadoc and comment.
>
> http://cr.openjdk.java.net/~rriggs/javadoc-tolocal-224/
>
> The changes are:
>
> * rename ChronoLocalDateTime.getDate/getTime/getDateTime to
> toLocalDate()/toLocalTime()/toLocalDateTime()
> * rename the corresponding methods in LocalDateTime, OffsetDateTime,
> ZonedDateTime
>
>
> I note that some obviously meaningful methods on ChronoLocalDateTime
> are missing in the javadoc, for example get(field); getLong(field),
> isSupported(field);
> that's a factor of the javadoc not documenting inherited methods.
>
>
>
> On 1/30/2013 5:06 PM, Stephen Colebourne wrote:
> >
> > I would leave the get methods you mentioned there alone.
> >
> > The model to follow is that "get" methods are used for those items
> > that get the state of the type you are working with. Thus,
> > OffsetDateTime has state of offset and the 8 fields, whereas LDT just
> > has the 8 fields.
> >
> > The "to" methods are for converting between the basic types ODT to LD,
> > LDT or LT.
> >
> > So, why draw the boundary there? Well, an offset is clearly part of
> > the state of an ODT, so a "get" method is definitely applicable, and
> > it would be wrong to be other. But the date and time is more interesting.
> >
> > If we didn't have any field-based methods on LDT/ODT/OT/ZDT, then it
> > would be correct to have getDate/getTime. But that isn't the model we
> > adopt in the API. Instead, we expose the fields as the primary
> > representation of date and time (with lots of get/with/plus/minus
> > methods). Thus, it is the field-based methods that stay as "get".
> >
> > (This is a Java language limitation. In
> > psuedo-other-wonderful-language, you would write zdt.{date.year = 6}
> > and it would return a ZDT, not a LD)
> >
> > The second part of the explanation is around how developers use the
> > types. Changing from using one type to using another type is an
> > important choice, and one we want to actively make developers aware
> > of. (These types we refer to here are LDT/LD/LT/ODT/OT/ZDT, not
> > Offset/ZoneId). As a developer if I have a ZDT and I want a LD, I'm
> > making a very specific conversion, where the LD object will be used
> > for a different purpose to the original ZDT. By contrast, the
> > Offset/Zone are just subsidiary parts of the whole, not carrying any
> > date-time informationto convert to.
> >
> > Finally, toMonth and toDayOfWeek could seem appealing, but they would
> > be out of place wrt the other getters. We need to actively encourage
> > developer to use the enums to make their code more readable, and
> > getters are needed for that.
> >
> > —
> > Reply to this email directly or view it on GitHub
> > <https://github.com/ThreeTen/threeten/issues/224#issuecomment-12915284>.
> >
>
> --
> Thanks, Roger
>
> Oracle Java Platform Group
>
> Green Oracle <http://www.oracle.com/commitment> Oracle is committed to
> developing practices and products that help protect the environment
>
> —
> Reply to this email directly or view it on GitHub<https://github.com/ThreeTen/threeten/issues/224#issuecomment-12915985>.
>
>