diff --git a/README.md b/README.md index bea0924..5eae2b7 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ This is a collection of usage examples for parsing. #### parseRfc3339 [» source](src/test/java/samples/parsing/ITUParserSamples.java#L63C5-L69C6) -The simplest and fastest way to parse an RFC-3339 (ISO-8601 profile) timestamp by far! +The simplest and fastest way to parse an RFC-3339 timestamp by far! ```java final String text = "2012-12-27T19:07:22.123456789-03:00"; final OffsetDateTime dateTime = ITU.parseDateTime(text); @@ -61,7 +61,7 @@ assertThat(dateTime.toString()).isEqualTo(text); #### parseLenient [» source](src/test/java/samples/parsing/ITUParserSamples.java#L74C5-L83C6) -Parses a date-time with flexible granularity. Works for anything from a year to a timestamp with nanoseconds, wih or without timezone offset! +Parses a date-time with flexible granularity. Works for anything from a year to a timestamp with nanoseconds, with or without timezone offset. ```java final String text = "2012-12-27T19:07:23.123"; final DateTime dateTime = ITU.parseLenient(text); @@ -84,7 +84,7 @@ assertThat(result.toString()).isEqualTo("1999-11-22T11:22:17.191"); #### parsePosition [» source](src/test/java/samples/parsing/ITUParserSamples.java#L102C5-L109C6) -This allows you to track where to start reading. Note that the check for trailing junk is disabled when using ParsePosition. +This allows you to track where to start reading. Note that the check for trailing junk is disabled when using `ParsePosition`. ```java final ParsePosition pos = new ParsePosition(10); final OffsetDateTime result = ITU.parseDateTime("some-data,1999-11-22T11:22:19+05:30,some-other-data", pos); @@ -114,9 +114,10 @@ assertThat(result.toString()).isEqualTo("2017-12-06T00:00Z"); ``` -#### lenientTimestamp [» source](src/test/java/samples/parsing/ITUParserSamples.java#L140C5-L145C6) +#### lenientTimestamp [» source](src/test/java/samples/parsing/ITUParserSamples.java#L141C5-L146C6) In some real world scenarios, it is useful to parse a best-effort timestamp. To ease usage, we can easily convert a raw `DateTime` instance into `Instant`. + Note the limitations and the assumption of UTC time-zone, as mentioned in the javadoc. ```java final Instant instant = ITU.parseLenient("2017-12-06").toInstant(); @@ -124,7 +125,7 @@ assertThat(instant.toString()).isEqualTo("2017-12-06T00:00:00Z"); ``` -#### parseCustomFormat [» source](src/test/java/samples/parsing/ITUParserSamples.java#L150C5-L169C6) +#### parseCustomFormat [» source](src/test/java/samples/parsing/ITUParserSamples.java#L151C5-L170C6) In case the format is not supported directly, you can build your own parser. ```java @@ -135,9 +136,9 @@ assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456"); ``` -#### parseUsingInterfaceRfc33939 [» source](src/test/java/samples/parsing/ITUParserSamples.java#L174C5-L181C6) +#### parseUsingInterfaceRfc33939 [» source](src/test/java/samples/parsing/ITUParserSamples.java#L175C5-L182C6) -`DateTimerParser` interface for RFC-3339 +`DateTimerParser` interface for RFC-3339. ```java final DateTimeParser parser = DateTimeParsers.rfc3339(); final String text = "2000-12-31 23:59:37.123456"; @@ -146,9 +147,9 @@ assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456"); ``` -#### parseUsingInterfaceLocalTime [» source](src/test/java/samples/parsing/ITUParserSamples.java#L186C5-L193C6) +#### parseUsingInterfaceLocalTime [» source](src/test/java/samples/parsing/ITUParserSamples.java#L187C5-L194C6) -`DateTimerParser` interface for local time +`DateTimerParser` interface for local time. ```java final DateTimeParser parser = DateTimeParsers.localTime(); final String text = "23:59:37.123456"; @@ -157,9 +158,9 @@ assertThat(result.toString()).isEqualTo(text); ``` -#### parseUsingInterfaceLocalDate [» source](src/test/java/samples/parsing/ITUParserSamples.java#L198C5-L205C6) +#### parseUsingInterfaceLocalDate [» source](src/test/java/samples/parsing/ITUParserSamples.java#L199C5-L206C6) -`DateTimerParser` interface for local date +`DateTimerParser` interface for local date. ```java final DateTimeParser parser = DateTimeParsers.localDate(); final String text = "2013-12-24"; @@ -177,9 +178,9 @@ This is a collection of usage examples for formatting. -#### formatRfc3339WithUTC [» source](src/test/java/samples/formatting/ITUFormattingSamples.java#L44C5-L52C6) +#### formatRfc3339WithUTC [» source](src/test/java/samples/formatting/ITUFormattingSamples.java#L46C5-L54C6) -The simplest and fastest way to format an RFC-3339 (ISO-8601 profile) timestamp by far! +The simplest and fastest way to format an RFC-3339 timestamp by far! ```java final OffsetDateTime input = OffsetDateTime.of(2012, 12, 27, 19, 7, 22, 123456789, ZoneOffset.ofHoursMinutes(-3, 0)); assertThat(ITU.formatUtcNano(input)).isEqualTo("2012-12-27T22:07:22.123456789Z"); @@ -189,6 +190,16 @@ assertThat(ITU.formatUtc(input)).isEqualTo("2012-12-27T22:07:22Z"); ``` +#### formatWithDateTime [» source](src/test/java/samples/formatting/ITUFormattingSamples.java#L59C5-L65C6) + +Format with `DateTime`. +```java +final DateTime input = DateTime.of(2020, 11, 27, 12, 39, 19, null); +assertThat(input.toString(Field.MINUTE)).isEqualTo("2020-11-27T12:39"); +assertThat(input.toString(Field.SECOND)).isEqualTo("2020-11-27T12:39:19"); +``` + + @@ -219,12 +230,12 @@ try { There are an endless amount of APIs with non-standard date/time exchange, and the goal of this project is to make it a no-brainer to do-the-right-thing(c). -### Why the performance docus? +### Why the performance focus? Some projects use epoch time-stamps for date-time exchange, and from a performance perspective this *may* make sense -in *some* cases. With this project one can do-the-right-thing and maintain performance in date-time handling. +in some cases. With this project one can do-the-right-thing and maintain performance in date-time handling. -This project is _not_ a premature optimization! In real-life scenarios there are examples of date-time parsing hindering optimal performance. The samples include data ingestion into databases and search engines, to importing/exporting data on less powerful devices, like cheaper Android devices. +Importantly, this project is _not_ a premature optimization. In real-life scenarios there are examples of date-time parsing hindering optimal performance. The samples include data ingestion into databases and search engines, to importing/exporting data on less powerful devices, like cheaper Android devices. ### What is wrong with epoch timestamps? @@ -275,4 +286,4 @@ well. Since Java's `java.time` classes do not support storing leap seconds, ITU will throw a `LeapSecondException` if one is encountered to signal that this is a leap second. The exception can then be queried for the second-value. Storing such values is not possible in a `java.time.OffsetDateTime`, the `60` is therefore abandoned and the date-time will use `59` -instead of `60`. +instead of `60`. \ No newline at end of file diff --git a/src/site/README.md b/src/site/README.md index d8859b5..bbfd875 100644 --- a/src/site/README.md +++ b/src/site/README.md @@ -54,12 +54,12 @@ ${src/test/java/samples/leapsecond} There are an endless amount of APIs with non-standard date/time exchange, and the goal of this project is to make it a no-brainer to do-the-right-thing(c). -### Why the performance optimized version? +### Why the performance focus? Some projects use epoch time-stamps for date-time exchange, and from a performance perspective this *may* make sense -in *some* cases. With this project one can do-the-right-thing and maintain performance in date-time handling. +in some cases. With this project one can do-the-right-thing and maintain performance in date-time handling. -This project is _not_ a premature optimization! In real-life scenarios there are examples of date-time parsing hindering optimal performance. The samples include data ingestion into databases and search engines, to importing/exporting data on less powerful devices, like cheaper Android devices. +Importantly, this project is _not_ a premature optimization. In real-life scenarios there are examples of date-time parsing hindering optimal performance. The samples include data ingestion into databases and search engines, to importing/exporting data on less powerful devices, like cheaper Android devices. ### What is wrong with epoch timestamps? diff --git a/src/test/java/samples/formatting/ITUFormattingSamples.java b/src/test/java/samples/formatting/ITUFormattingSamples.java index 5f9783b..6ea430f 100644 --- a/src/test/java/samples/formatting/ITUFormattingSamples.java +++ b/src/test/java/samples/formatting/ITUFormattingSamples.java @@ -27,6 +27,8 @@ import org.junit.jupiter.api.Test; +import com.ethlo.time.DateTime; +import com.ethlo.time.Field; import com.ethlo.time.ITU; /* @@ -39,7 +41,7 @@ class ITUFormattingSamples { /* - The simplest and fastest way to format an RFC-3339 (ISO-8601 profile) timestamp by far! + The simplest and fastest way to format an RFC-3339 timestamp by far! */ @Test void formatRfc3339WithUTC() @@ -50,4 +52,15 @@ void formatRfc3339WithUTC() assertThat(ITU.formatUtcMilli(input)).isEqualTo("2012-12-27T22:07:22.123Z"); assertThat(ITU.formatUtc(input)).isEqualTo("2012-12-27T22:07:22Z"); } + + /* + Format with `DateTime`. + */ + @Test + void formatWithDateTime() + { + final DateTime input = DateTime.of(2020, 11, 27, 12, 39, 19, null); + assertThat(input.toString(Field.MINUTE)).isEqualTo("2020-11-27T12:39"); + assertThat(input.toString(Field.SECOND)).isEqualTo("2020-11-27T12:39:19"); + } } diff --git a/src/test/java/samples/parsing/ITUParserSamples.java b/src/test/java/samples/parsing/ITUParserSamples.java index ca41879..c6739be 100644 --- a/src/test/java/samples/parsing/ITUParserSamples.java +++ b/src/test/java/samples/parsing/ITUParserSamples.java @@ -58,7 +58,7 @@ class ITUParserSamples { /* - The simplest and fastest way to parse an RFC-3339 (ISO-8601 profile) timestamp by far! + The simplest and fastest way to parse an RFC-3339 timestamp by far! */ @Test void parseRfc3339() @@ -69,7 +69,7 @@ void parseRfc3339() } /* - Parses a date-time with flexible granularity. Works for anything from a year to a timestamp with nanoseconds, wih or without timezone offset! + Parses a date-time with flexible granularity. Works for anything from a year to a timestamp with nanoseconds, with or without timezone offset. */ @Test void parseLenient() @@ -97,7 +97,7 @@ void parseLenientWithCustomSeparators() } /* - This allows you to track where to start reading. Note that the check for trailing junk is disabled when using ParsePosition. + This allows you to track where to start reading. Note that the check for trailing junk is disabled when using `ParsePosition`. */ @Test void parsePosition() @@ -135,6 +135,7 @@ public OffsetDateTime handle(final OffsetDateTime offsetDateTime) /* In some real world scenarios, it is useful to parse a best-effort timestamp. To ease usage, we can easily convert a raw `DateTime` instance into `Instant`. + Note the limitations and the assumption of UTC time-zone, as mentioned in the javadoc. */ @Test @@ -169,7 +170,7 @@ void parseCustomFormat() } /* - `DateTimerParser` interface for RFC-3339 + `DateTimerParser` interface for RFC-3339. */ @Test void parseUsingInterfaceRfc33939() @@ -181,7 +182,7 @@ void parseUsingInterfaceRfc33939() } /* - `DateTimerParser` interface for local time + `DateTimerParser` interface for local time. */ @Test void parseUsingInterfaceLocalTime() @@ -193,7 +194,7 @@ void parseUsingInterfaceLocalTime() } /* - `DateTimerParser` interface for local date + `DateTimerParser` interface for local date. */ @Test void parseUsingInterfaceLocalDate()