Java 8 Date/Time API Extensions Methods [GROOVY-8334]

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
19 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Java 8 Date/Time API Extensions Methods [GROOVY-8334]

Joe Wolf
I've finally gotten around to adding extension methods to the Groovy JDK for the java.time types. See https://issues.apache.org/jira/browse/GROOVY-8334 for reference.

I've generated a copy of the Groovy JDK apidocs with my current changes here: http://bdkosher.github.io/groovy-3.0-alpha/groovy-jdk/ 

The additions are in the java.time and java.time.temporal packages, obviously, as well as some "since 3.0" methods in java.util.Date and java.util.Calendar

I thought it was worthwhile to open up these API changes for discussion here before submitting a PR. There may be things included which should not be or things not included that should.

-Joe
Reply | Threaded
Open this post in threaded view
|

Re: Java 8 Date/Time API Extensions Methods [GROOVY-8334]

Guillaume Laforge
Administrator
This looks very complete, at first sight, that's really wonderful!
I'm really looking forward to seeing that integrated.

Did you also have a pointer to a doc / page / blog which shows those methods in action?
(which we could potentially add to our online documentation)

Guillaume

On Mon, Feb 19, 2018 at 12:16 AM, Joe Wolf <[hidden email]> wrote:
I've finally gotten around to adding extension methods to the Groovy JDK for the java.time types. See https://issues.apache.org/jira/browse/GROOVY-8334 for reference.

I've generated a copy of the Groovy JDK apidocs with my current changes here: http://bdkosher.github.io/groovy-3.0-alpha/groovy-jdk/ 

The additions are in the java.time and java.time.temporal packages, obviously, as well as some "since 3.0" methods in java.util.Date and java.util.Calendar

I thought it was worthwhile to open up these API changes for discussion here before submitting a PR. There may be things included which should not be or things not included that should.

-Joe



--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform

Reply | Threaded
Open this post in threaded view
|

Re: Java 8 Date/Time API Extensions Methods [GROOVY-8334]

Joe Wolf
Good idea--I should have thought of that earlier! I'll draft up some documentation in a new section of the core-gdk.adoc file and post a link for review.

-Joe

On Mon, Feb 19, 2018 at 4:50 AM, Guillaume Laforge <[hidden email]> wrote:
This looks very complete, at first sight, that's really wonderful!
I'm really looking forward to seeing that integrated.

Did you also have a pointer to a doc / page / blog which shows those methods in action?
(which we could potentially add to our online documentation)

Guillaume

On Mon, Feb 19, 2018 at 12:16 AM, Joe Wolf <[hidden email]> wrote:
I've finally gotten around to adding extension methods to the Groovy JDK for the java.time types. See https://issues.apache.org/jira/browse/GROOVY-8334 for reference.

I've generated a copy of the Groovy JDK apidocs with my current changes here: http://bdkosher.github.io/groovy-3.0-alpha/groovy-jdk/ 

The additions are in the java.time and java.time.temporal packages, obviously, as well as some "since 3.0" methods in java.util.Date and java.util.Calendar

I thought it was worthwhile to open up these API changes for discussion here before submitting a PR. There may be things included which should not be or things not included that should.

-Joe



--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform


Reply | Threaded
Open this post in threaded view
|

Re: Java 8 Date/Time API Extensions Methods [GROOVY-8334]

Guillaume Laforge
Administrator
Sounds awesome!
Anyhow, I already like what I see, those methods sound very useful to me!

On Mon, Feb 19, 2018 at 4:37 PM, Joe Wolf <[hidden email]> wrote:
Good idea--I should have thought of that earlier! I'll draft up some documentation in a new section of the core-gdk.adoc file and post a link for review.

-Joe

On Mon, Feb 19, 2018 at 4:50 AM, Guillaume Laforge <[hidden email]> wrote:
This looks very complete, at first sight, that's really wonderful!
I'm really looking forward to seeing that integrated.

Did you also have a pointer to a doc / page / blog which shows those methods in action?
(which we could potentially add to our online documentation)

Guillaume

On Mon, Feb 19, 2018 at 12:16 AM, Joe Wolf <[hidden email]> wrote:
I've finally gotten around to adding extension methods to the Groovy JDK for the java.time types. See https://issues.apache.org/jira/browse/GROOVY-8334 for reference.

I've generated a copy of the Groovy JDK apidocs with my current changes here: http://bdkosher.github.io/groovy-3.0-alpha/groovy-jdk/ 

The additions are in the java.time and java.time.temporal packages, obviously, as well as some "since 3.0" methods in java.util.Date and java.util.Calendar

I thought it was worthwhile to open up these API changes for discussion here before submitting a PR. There may be things included which should not be or things not included that should.

-Joe



--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform





--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform

Reply | Threaded
Open this post in threaded view
|

Re: Java 8 Date/Time API Extensions Methods [GROOVY-8334]

Joe Wolf
Here's a first stab at the documentation for the Date/Time API extensions: http://bdkosher.github.io/groovy-3.0-alpha/html5/#_working_with_date_time_types 

And in writing the documentation (as with writing unit tests), I got feedback, prompting some minor changes:

1) using the DateTimeFormatter.ISO* formatters for implementing getDateString(), getTimeString(), and getDateTimeString() instead of using a localized FormatStyle.SHORT style. Besides making it easier to document examples, I personally prefer "2018-03-17" to "3/17/18", even as an American.

2) changing the behavior of the upto method (and downto) so that, when using a custom unit of iteration that prevents the start value from being incremented exactly to the end value, the method returns as soon as the current value becomes strictly later than the end value. In my first stab at it, the method returned when the current iteration value became later than the end value _by at least one unit_. As a result, the closure could be called with a value later than the end parameter, which seemed undesirable. e.g. 

def from = LocalDate.of(2018, Month.MARCH, 1)
def to =   LocalDate.of(2018, Month.MARCH, 2)

from.upto(to, ChronoUnit.MONTH) { date -> // iterate by one month at a time
    println date
}

would print

2018-03-01
2018-04-01

This was because April 1st is less than a month after March 2nd: march2nd.until(april1st, ChronoUnit.MONTH) == 0, as explained in the docs https://docs.oracle.com/javase/8/docs/api/java/time/temporal/Temporal.html#until-java.time.temporal.Temporal-java.time.temporal.TemporalUnit- 

Anyways, the updated GDK docs are here, temporarily: http://bdkosher.github.io/groovy-3.0-alpha/groovy-jdk/ 

Barring any substantial disagreement with inclusions or exclusions, I can submit a PR and where we can discuss any minor implementation or documentation details.

-Joe

On Mon, Feb 19, 2018 at 11:26 AM, Guillaume Laforge <[hidden email]> wrote:
Sounds awesome!
Anyhow, I already like what I see, those methods sound very useful to me!

On Mon, Feb 19, 2018 at 4:37 PM, Joe Wolf <[hidden email]> wrote:
Good idea--I should have thought of that earlier! I'll draft up some documentation in a new section of the core-gdk.adoc file and post a link for review.

-Joe

On Mon, Feb 19, 2018 at 4:50 AM, Guillaume Laforge <[hidden email]> wrote:
This looks very complete, at first sight, that's really wonderful!
I'm really looking forward to seeing that integrated.

Did you also have a pointer to a doc / page / blog which shows those methods in action?
(which we could potentially add to our online documentation)

Guillaume

On Mon, Feb 19, 2018 at 12:16 AM, Joe Wolf <[hidden email]> wrote:
I've finally gotten around to adding extension methods to the Groovy JDK for the java.time types. See https://issues.apache.org/jira/browse/GROOVY-8334 for reference.

I've generated a copy of the Groovy JDK apidocs with my current changes here: http://bdkosher.github.io/groovy-3.0-alpha/groovy-jdk/ 

The additions are in the java.time and java.time.temporal packages, obviously, as well as some "since 3.0" methods in java.util.Date and java.util.Calendar

I thought it was worthwhile to open up these API changes for discussion here before submitting a PR. There may be things included which should not be or things not included that should.

-Joe



--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform





--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform


Reply | Threaded
Open this post in threaded view
|

Re: Java 8 Date/Time API Extensions Methods [GROOVY-8334]

paulk_asert
Looks good at first glance. Please go ahead with the PR. 

On 18 Mar. 2018 5:37 am, "Joe Wolf" <[hidden email]> wrote:
Here's a first stab at the documentation for the Date/Time API extensions: http://bdkosher.github.io/groovy-3.0-alpha/html5/#_working_with_date_time_types 

And in writing the documentation (as with writing unit tests), I got feedback, prompting some minor changes:

1) using the DateTimeFormatter.ISO* formatters for implementing getDateString(), getTimeString(), and getDateTimeString() instead of using a localized FormatStyle.SHORT style. Besides making it easier to document examples, I personally prefer "2018-03-17" to "3/17/18", even as an American.

2) changing the behavior of the upto method (and downto) so that, when using a custom unit of iteration that prevents the start value from being incremented exactly to the end value, the method returns as soon as the current value becomes strictly later than the end value. In my first stab at it, the method returned when the current iteration value became later than the end value _by at least one unit_. As a result, the closure could be called with a value later than the end parameter, which seemed undesirable. e.g. 

def from = LocalDate.of(2018, Month.MARCH, 1)
def to =   LocalDate.of(2018, Month.MARCH, 2)

from.upto(to, ChronoUnit.MONTH) { date -> // iterate by one month at a time
    println date
}

would print

2018-03-01
2018-04-01

This was because April 1st is less than a month after March 2nd: march2nd.until(april1st, ChronoUnit.MONTH) == 0, as explained in the docs https://docs.oracle.com/javase/8/docs/api/java/time/temporal/Temporal.html#until-java.time.temporal.Temporal-java.time.temporal.TemporalUnit- 

Anyways, the updated GDK docs are here, temporarily: http://bdkosher.github.io/groovy-3.0-alpha/groovy-jdk/ 

Barring any substantial disagreement with inclusions or exclusions, I can submit a PR and where we can discuss any minor implementation or documentation details.

-Joe

On Mon, Feb 19, 2018 at 11:26 AM, Guillaume Laforge <[hidden email]> wrote:
Sounds awesome!
Anyhow, I already like what I see, those methods sound very useful to me!

On Mon, Feb 19, 2018 at 4:37 PM, Joe Wolf <[hidden email]> wrote:
Good idea--I should have thought of that earlier! I'll draft up some documentation in a new section of the core-gdk.adoc file and post a link for review.

-Joe

On Mon, Feb 19, 2018 at 4:50 AM, Guillaume Laforge <[hidden email]> wrote:
This looks very complete, at first sight, that's really wonderful!
I'm really looking forward to seeing that integrated.

Did you also have a pointer to a doc / page / blog which shows those methods in action?
(which we could potentially add to our online documentation)

Guillaume

On Mon, Feb 19, 2018 at 12:16 AM, Joe Wolf <[hidden email]> wrote:
I've finally gotten around to adding extension methods to the Groovy JDK for the java.time types. See https://issues.apache.org/jira/browse/GROOVY-8334 for reference.

I've generated a copy of the Groovy JDK apidocs with my current changes here: http://bdkosher.github.io/groovy-3.0-alpha/groovy-jdk/ 

The additions are in the java.time and java.time.temporal packages, obviously, as well as some "since 3.0" methods in java.util.Date and java.util.Calendar

I thought it was worthwhile to open up these API changes for discussion here before submitting a PR. There may be things included which should not be or things not included that should.

-Joe



--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform





--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform


Reply | Threaded
Open this post in threaded view
|

Re: Java 8 Date/Time API Extensions Methods [GROOVY-8334]

Daniel.Sun
In reply to this post by Joe Wolf
Nice!

I see a Groovy Champion candidate here ;-)

Cheers,
Daniel.Sun




--
Sent from: http://groovy.329449.n5.nabble.com/Groovy-Dev-f372993.html
Daniel Sun
Apache Groovy committer

Blog: http://blog.sunlan.me
Twitter: @daniel_sun
Reply | Threaded
Open this post in threaded view
|

Re: Java 8 Date/Time API Extensions Methods [GROOVY-8334]

Alexander Veit-2
In reply to this post by Joe Wolf
Hi,

> 2) changing the behavior of the upto method (and downto) so that, when
> using a custom unit of iteration that prevents the start value from being
> incremented exactly to the end value, the method returns as soon as the
> current value becomes strictly later than the end value. In my first stab
> at it, the method returned when the current iteration value became later
> than the end value _by at least one unit_. As a result, the closure could
> be called with a value later than the end parameter, which seemed
> undesirable. e.g.

Judging from my experience in dealing with time intervals, the most
natural way for defining them is as half-open intervals with the lower
bound included and the upper bound excluded. This allows the whole
timeline to be completely and non-overlapping covered with such
intervals. This is not only a mathematically desireable property, but
also helps making code simpler in many cases.

I do not know, if this approach is in accordance with the general design
rules of this API, but if so, it would suggest that an ascending
iteration should not yield values greater or equal the upper bound.


--
Just my 2 cents,
Alex
MG
Reply | Threaded
Open this post in threaded view
|

Re: Java 8 Date/Time API Extensions Methods [GROOVY-8334]

MG
In general I agree that the half-open interval [TS_FROM, TS_TO) should
be the default behavior for intervals due to the reasons given -
whatever detailed influence that has on discrete iterations /
upto/downto :-)
Cheers,
mg


On 18.03.2018 17:45, Alexander Veit wrote:

> Hi,
>
>> 2) changing the behavior of the upto method (and downto) so that, when
>> using a custom unit of iteration that prevents the start value from being
>> incremented exactly to the end value, the method returns as soon as the
>> current value becomes strictly later than the end value. In my first stab
>> at it, the method returned when the current iteration value became later
>> than the end value _by at least one unit_. As a result, the closure could
>> be called with a value later than the end parameter, which seemed
>> undesirable. e.g.
> Judging from my experience in dealing with time intervals, the most
> natural way for defining them is as half-open intervals with the lower
> bound included and the upper bound excluded. This allows the whole
> timeline to be completely and non-overlapping covered with such
> intervals. This is not only a mathematically desireable property, but
> also helps making code simpler in many cases.
>
> I do not know, if this approach is in accordance with the general design
> rules of this API, but if so, it would suggest that an ascending
> iteration should not yield values greater or equal the upper bound.
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Java 8 Date/Time API Extensions Methods [GROOVY-8334]

Guillaume Laforge
Administrator
In reply to this post by paulk_asert
+1!

I've just read the documentation and it's clear and elegant. Great job!
Really looking forward to seeing it integrated!
It's a very nice and needed addition to the GDK :-)

Guillaume


On Sun, Mar 18, 2018 at 6:03 AM, Paul King <[hidden email]> wrote:
Looks good at first glance. Please go ahead with the PR. 

On 18 Mar. 2018 5:37 am, "Joe Wolf" <[hidden email]> wrote:
Here's a first stab at the documentation for the Date/Time API extensions: http://bdkosher.github.io/groovy-3.0-alpha/html5/#_working_with_date_time_types 

And in writing the documentation (as with writing unit tests), I got feedback, prompting some minor changes:

1) using the DateTimeFormatter.ISO* formatters for implementing getDateString(), getTimeString(), and getDateTimeString() instead of using a localized FormatStyle.SHORT style. Besides making it easier to document examples, I personally prefer "2018-03-17" to "3/17/18", even as an American.

2) changing the behavior of the upto method (and downto) so that, when using a custom unit of iteration that prevents the start value from being incremented exactly to the end value, the method returns as soon as the current value becomes strictly later than the end value. In my first stab at it, the method returned when the current iteration value became later than the end value _by at least one unit_. As a result, the closure could be called with a value later than the end parameter, which seemed undesirable. e.g. 

def from = LocalDate.of(2018, Month.MARCH, 1)
def to =   LocalDate.of(2018, Month.MARCH, 2)

from.upto(to, ChronoUnit.MONTH) { date -> // iterate by one month at a time
    println date
}

would print

2018-03-01
2018-04-01

This was because April 1st is less than a month after March 2nd: march2nd.until(april1st, ChronoUnit.MONTH) == 0, as explained in the docs https://docs.oracle.com/javase/8/docs/api/java/time/temporal/Temporal.html#until-java.time.temporal.Temporal-java.time.temporal.TemporalUnit- 

Anyways, the updated GDK docs are here, temporarily: http://bdkosher.github.io/groovy-3.0-alpha/groovy-jdk/ 

Barring any substantial disagreement with inclusions or exclusions, I can submit a PR and where we can discuss any minor implementation or documentation details.

-Joe

On Mon, Feb 19, 2018 at 11:26 AM, Guillaume Laforge <[hidden email]> wrote:
Sounds awesome!
Anyhow, I already like what I see, those methods sound very useful to me!

On Mon, Feb 19, 2018 at 4:37 PM, Joe Wolf <[hidden email]> wrote:
Good idea--I should have thought of that earlier! I'll draft up some documentation in a new section of the core-gdk.adoc file and post a link for review.

-Joe

On Mon, Feb 19, 2018 at 4:50 AM, Guillaume Laforge <[hidden email]> wrote:
This looks very complete, at first sight, that's really wonderful!
I'm really looking forward to seeing that integrated.

Did you also have a pointer to a doc / page / blog which shows those methods in action?
(which we could potentially add to our online documentation)

Guillaume

On Mon, Feb 19, 2018 at 12:16 AM, Joe Wolf <[hidden email]> wrote:
I've finally gotten around to adding extension methods to the Groovy JDK for the java.time types. See https://issues.apache.org/jira/browse/GROOVY-8334 for reference.

I've generated a copy of the Groovy JDK apidocs with my current changes here: http://bdkosher.github.io/groovy-3.0-alpha/groovy-jdk/ 

The additions are in the java.time and java.time.temporal packages, obviously, as well as some "since 3.0" methods in java.util.Date and java.util.Calendar

I thought it was worthwhile to open up these API changes for discussion here before submitting a PR. There may be things included which should not be or things not included that should.

-Joe



--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform





--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform





--
Guillaume Laforge
Apache Groovy committer & PMC Vice-President
Developer Advocate @ Google Cloud Platform

12