From e98e238afbc77ed275269756ecf2bb644c8f0c84 Mon Sep 17 00:00:00 2001 From: Morten Haraldsen Date: Thu, 8 Feb 2024 15:29:53 +0100 Subject: [PATCH] Take all examples in README from source code --- .editorconfig | 2 +- README.md | 170 ++++++++---------- src/site/README.md | 64 +------ src/site/sample-code.template.md | 17 ++ .../formatting/ITUFormattingSamples.java | 53 ++++++ .../leapsecond/ITULeapSecondSamples.java | 58 ++++++ .../{ => parsing}/ITUParserSamples.java | 2 +- src/test/resources/sample-renderer.html | 33 ---- 8 files changed, 213 insertions(+), 186 deletions(-) create mode 100644 src/site/sample-code.template.md create mode 100644 src/test/java/samples/formatting/ITUFormattingSamples.java create mode 100644 src/test/java/samples/leapsecond/ITULeapSecondSamples.java rename src/test/java/samples/{ => parsing}/ITUParserSamples.java (99%) delete mode 100644 src/test/resources/sample-renderer.html diff --git a/.editorconfig b/.editorconfig index 8322848..ee81075 100644 --- a/.editorconfig +++ b/.editorconfig @@ -4,7 +4,7 @@ end_of_line = lf indent_size = 4 indent_style = space insert_final_newline = false -max_line_length = 120 +max_line_length = 200 tab_width = 4 ij_continuation_indent_size = 8 ij_formatter_off_tag = @formatter:off diff --git a/README.md b/README.md index 02709bf..a7d0e0a 100644 --- a/README.md +++ b/README.md @@ -41,41 +41,31 @@ Add dependency Below you find some samples of usage of this library. Please check out the [javadoc](https://javadoc.io/doc/com.ethlo.time/itu/latest/com/ethlo/time/ITU.html) for more details. -### Parsing - - - -### parseRfc3339 + + +## Parsing + +This is a collection of usage examples for parsing. + + + +#### parseRfc3339 The simplest and fastest way to parse an RFC-3339 (ISO-8601 profile) timestamp by far! + +[» full source](src/test/java/samples/parsing/ITUParserSamples.java#L63C5-L69C5) + ```java final String text = "2012-12-27T19:07:22.123456789-03:00"; final OffsetDateTime dateTime = ITU.parseDateTime(text); assertThat(dateTime.toString()).isEqualTo(text); ``` -[View source code](src/test/java/samples/ITUParserSamples.java#L63C5-L69C5) - -### parseLenient +#### parseLenient Parses a date-time with flexible granularity. Works for anything from a year to a timestamp with nanoseconds, wih or without timezone offset! + +[» full source](src/test/java/samples/parsing/ITUParserSamples.java#L74C5-L83C5) + ```java final String text = "2012-12-27T19:07:23.123"; final DateTime dateTime = ITU.parseLenient(text); @@ -84,22 +74,25 @@ final String formatted = dateTime.toString(); assertThat(formatted).isEqualTo(text); ``` -[View source code](src/test/java/samples/ITUParserSamples.java#L74C5-L83C5) +#### parseLenientWithCustomSeparators +In case you encounter the need for a somewhat different time-separator or fraction separator + you can use the `ParseConfig` to set up you preferred delimiters. + +[» full source](src/test/java/samples/parsing/ITUParserSamples.java#L89C5-L97C5) -### parseLenientWithCustomSeparators -In case you encounter the need for a somewhat different time-separator or fraction separator you can use the `ParseConfig` to set up you preferred delimiters. ```java final ParseConfig config = ParseConfig.DEFAULT.withDateTimeSeparators('T', '|').withFractionSeparators('.', ','); final DateTime result = ITU.parseLenient("1999-11-22|11:22:17,191", config); assertThat(result.toString()).isEqualTo("1999-11-22T11:22:17.191"); ``` -[View source code](src/test/java/samples/ITUParserSamples.java#L89C5-L97C5) - -### parsePosition +#### parsePosition This allows you to track where to start reading. Note that the check for trailing junk is disabled when using ParsePosition. + +[» full source](src/test/java/samples/parsing/ITUParserSamples.java#L102C5-L109C5) + ```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); @@ -107,11 +100,12 @@ assertThat(result.toString()).isEqualTo("1999-11-22T11:22:19+05:30"); assertThat(pos.getIndex()).isEqualTo(35); ``` -[View source code](src/test/java/samples/ITUParserSamples.java#L102C5-L109C5) - -### explicitGranularity +#### explicitGranularity This is useful if you need to handle different granularity with different logic or interpolation. + +[» full source](src/test/java/samples/parsing/ITUParserSamples.java#L114C5-L134C5) + ```java final TemporalHandler handler = new TemporalHandler() { @@ -129,21 +123,25 @@ final OffsetDateTime result = ITU.parse("2017-12-06", handler); assertThat(result.toString()).isEqualTo("2017-12-06T00:00Z"); ``` -[View source code](src/test/java/samples/ITUParserSamples.java#L114C5-L134C5) +#### lenientTimestamp +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. + +[» full source](src/test/java/samples/parsing/ITUParserSamples.java#L141C5-L146C5) -### lenientTimestamp -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(); assertThat(instant.toString()).isEqualTo("2017-12-06T00:00:00Z"); ``` -[View source code](src/test/java/samples/ITUParserSamples.java#L141C5-L146C5) - -### parseCustomFormat +#### parseCustomFormat In case the format is not supported directly, you can build your own parser. + +[» full source](src/test/java/samples/parsing/ITUParserSamples.java#L151C5-L170C5) + ```java final DateTimeParser parser = DateTimeParsers.of(digits(DAY, 2), separators('-'), digits(MONTH, 2), separators('-'), digits(YEAR, 4), separators(' '), digits(HOUR, 2), digits(MINUTE, 2), digits(SECOND, 2), separators(','), fractions()); final String text = "31-12-2000 235937,123456"; @@ -151,11 +149,12 @@ final DateTime result = parser.parse(text); assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456"); ``` -[View source code](src/test/java/samples/ITUParserSamples.java#L151C5-L170C5) - -### parseUsingInterfaceRfc33939 +#### parseUsingInterfaceRfc33939 `DateTimerParser` interface for RFC-3339 + +[» full source](src/test/java/samples/parsing/ITUParserSamples.java#L175C5-L182C5) + ```java final DateTimeParser parser = DateTimeParsers.rfc3339(); final String text = "2000-12-31 23:59:37.123456"; @@ -163,11 +162,12 @@ final DateTime result = parser.parse(text); assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456"); ``` -[View source code](src/test/java/samples/ITUParserSamples.java#L175C5-L182C5) - -### parseUsingInterfaceLocalTime +#### parseUsingInterfaceLocalTime `DateTimerParser` interface for local time + +[» full source](src/test/java/samples/parsing/ITUParserSamples.java#L187C5-L194C5) + ```java final DateTimeParser parser = DateTimeParsers.localTime(); final String text = "23:59:37.123456"; @@ -175,11 +175,12 @@ final LocalTime result = parser.parse(text).toLocalTime(); assertThat(result.toString()).isEqualTo(text); ``` -[View source code](src/test/java/samples/ITUParserSamples.java#L187C5-L194C5) - -### parseUsingInterfaceLocalDate +#### parseUsingInterfaceLocalDate `DateTimerParser` interface for local date + +[» full source](src/test/java/samples/parsing/ITUParserSamples.java#L199C5-L206C5) + ```java final DateTimeParser parser = DateTimeParsers.localDate(); final String text = "2013-12-24"; @@ -187,67 +188,54 @@ final LocalDate result = parser.parse(text).toLocalDate(); assertThat(result.toString()).isEqualTo(text); ``` -[View source code](src/test/java/samples/ITUParserSamples.java#L199C5-L206C5) -### Formatting -
-Format with seconds (no fraction digits) +## Formatting -```java -final String formatted = ITU.formatUtc(dateTime); // 2012-12-27T22:07:22Z -``` -
+This is a collection of usage examples for formatting. + -
-Format with microsecond precision +#### formatRfc3339WithUTC +The simplest and fastest way to format an RFC-3339 (ISO-8601 profile) timestamp by far! + +[» full source](src/test/java/samples/formatting/ITUFormattingSamples.java#L44C5-L52C5) ```java -final String formattedMicro = ITU.formatUtcMicro(dateTime); // 2012-12-27T22:07:22.123457Z +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"); +assertThat(ITU.formatUtcMicro(input)).isEqualTo("2012-12-27T22:07:22.123456Z"); +assertThat(ITU.formatUtcMilli(input)).isEqualTo("2012-12-27T22:07:22.123Z"); +assertThat(ITU.formatUtc(input)).isEqualTo("2012-12-27T22:07:22Z"); ``` -
-### Validate -
-Validate as RFC-3339 date-time -```java -ITU.isValid("2017-12-06"); // false -``` -
-
-Validate as specific type -```java -ITU.isValid("2017-12-06", TemporalType.LOCAL_DATE_TIME); // true -``` -
-### Handle leap-seconds +## Leap-second handling -
-Sample + + +#### parseLeapSecond +Parse a valid leap-second (i.e. it is on a date that would allow for it, and it is also in the list of known actual leap-seconds). + +[» full source](src/test/java/samples/leapsecond/ITULeapSecondSamples.java#L43C5-L57C5) ```java -class Sample { - void parse() { - try { - final OffsetDateTime dateTime = ITU.parseDateTime("1990-12-31T15:59:60-08:00"); - } catch ( - LeapSecondException exc) { - // The following helper methods are available let you decide how to progress - exc.getSecondsInMinute(); // 60 - exc.getNearestDateTime(); // 1991-01-01T00:00:00Z - exc.isVerifiedValidLeapYearMonth(); // true - } - } +try { + ITU.parseDateTime("1990-12-31T15:59:60-08:00"); +} catch (LeapSecondException exc) { + // The following helper methods are available let you decide how to progress + assertThat(exc.getSecondsInMinute()).isEqualTo(60); + assertThat(exc.getNearestDateTime()).isEqualTo(OffsetDateTime.of(1991, 12, 31, 1, 0, 0, 0, ZoneOffset.UTC)); + assertThat(exc.isVerifiedValidLeapYearMonth()).isTrue(); } ``` -
+ + ## Q & A diff --git a/src/site/README.md b/src/site/README.md index 16a4159..d8859b5 100644 --- a/src/site/README.md +++ b/src/site/README.md @@ -33,7 +33,7 @@ Add dependency com.ethlo.time itu - 1.10.0 + ${project.version} small @@ -41,67 +41,11 @@ Add dependency Below you find some samples of usage of this library. Please check out the [javadoc](https://javadoc.io/doc/com.ethlo.time/itu/latest/com/ethlo/time/ITU.html) for more details. -### Parsing +${src/test/java/samples/parsing} -${src/test/java/samples} +${src/test/java/samples/formatting} -### Formatting - -
-Format with seconds (no fraction digits) - -```java -final String formatted = ITU.formatUtc(dateTime); // 2012-12-27T22:07:22Z -``` -
- - -
-Format with microsecond precision - -```java -final String formattedMicro = ITU.formatUtcMicro(dateTime); // 2012-12-27T22:07:22.123457Z -``` -
- -### Validate - -
- -Validate as RFC-3339 date-time -```java -ITU.isValid("2017-12-06"); // false -``` -
- -
-Validate as specific type -```java -ITU.isValid("2017-12-06", TemporalType.LOCAL_DATE_TIME); // true -``` -
- -### Handle leap-seconds - -
-Sample - -```java -class Sample { - void parse() { - try { - final OffsetDateTime dateTime = ITU.parseDateTime("1990-12-31T15:59:60-08:00"); - } catch ( - LeapSecondException exc) { - // The following helper methods are available let you decide how to progress - exc.getSecondsInMinute(); // 60 - exc.getNearestDateTime(); // 1991-01-01T00:00:00Z - exc.isVerifiedValidLeapYearMonth(); // true - } - } -} -``` -
+${src/test/java/samples/leapsecond} ## Q & A diff --git a/src/site/sample-code.template.md b/src/site/sample-code.template.md new file mode 100644 index 0000000..a7ee395 --- /dev/null +++ b/src/site/sample-code.template.md @@ -0,0 +1,17 @@ +{{class.description}} + +{% for method in methods %} + +#### {{method.name}} + +{{method.description | trim | raw }} + + +[» full source]({{class.path}}/{{class.name}}.java#L{{method.range.begin.line}}C{{method.range.begin.column}}-L{{method.range.end.line}}C{{method.range.end.column}}) + +```java +{{method.body | trim | raw }} + +``` + +{% endfor %} diff --git a/src/test/java/samples/formatting/ITUFormattingSamples.java b/src/test/java/samples/formatting/ITUFormattingSamples.java new file mode 100644 index 0000000..5f9783b --- /dev/null +++ b/src/test/java/samples/formatting/ITUFormattingSamples.java @@ -0,0 +1,53 @@ +package samples.formatting; + +/*- + * #%L + * Internet Time Utility + * %% + * Copyright (C) 2017 - 2024 Morten Haraldsen (ethlo) + * %% + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * #L% + */ + +import static org.assertj.core.api.Assertions.assertThat; + +import java.time.OffsetDateTime; +import java.time.ZoneOffset; + +import org.junit.jupiter.api.Test; + +import com.ethlo.time.ITU; + +/* + +## Formatting + +This is a collection of usage examples for formatting. + + */ +class ITUFormattingSamples +{ + /* + The simplest and fastest way to format an RFC-3339 (ISO-8601 profile) timestamp by far! + */ + @Test + void formatRfc3339WithUTC() + { + 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"); + assertThat(ITU.formatUtcMicro(input)).isEqualTo("2012-12-27T22:07:22.123456Z"); + assertThat(ITU.formatUtcMilli(input)).isEqualTo("2012-12-27T22:07:22.123Z"); + assertThat(ITU.formatUtc(input)).isEqualTo("2012-12-27T22:07:22Z"); + } +} diff --git a/src/test/java/samples/leapsecond/ITULeapSecondSamples.java b/src/test/java/samples/leapsecond/ITULeapSecondSamples.java new file mode 100644 index 0000000..68076e7 --- /dev/null +++ b/src/test/java/samples/leapsecond/ITULeapSecondSamples.java @@ -0,0 +1,58 @@ +package samples.leapsecond; + +/*- + * #%L + * Internet Time Utility + * %% + * Copyright (C) 2017 - 2024 Morten Haraldsen (ethlo) + * %% + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * #L% + */ + +import static org.assertj.core.api.Assertions.assertThat; + +import java.time.OffsetDateTime; +import java.time.ZoneOffset; + +import org.junit.jupiter.api.Test; + +import com.ethlo.time.ITU; +import com.ethlo.time.LeapSecondException; + +/* + +## Leap-second handling + + */ +class ITULeapSecondSamples +{ + /* + Parse a valid leap-second (i.e. it is on a date that would allow for it, and it is also in the list of known actual leap-seconds). + */ + @Test + void parseLeapSecond() + { + try + { + ITU.parseDateTime("1990-12-31T15:59:60-08:00"); + } + catch (LeapSecondException exc) + { + // The following helper methods are available let you decide how to progress + assertThat(exc.getSecondsInMinute()).isEqualTo(60); + assertThat(exc.getNearestDateTime()).isEqualTo(OffsetDateTime.of(1991, 12, 31, 1, 0, 0, 0, ZoneOffset.UTC)); + assertThat(exc.isVerifiedValidLeapYearMonth()).isTrue(); + } + } +} diff --git a/src/test/java/samples/ITUParserSamples.java b/src/test/java/samples/parsing/ITUParserSamples.java similarity index 99% rename from src/test/java/samples/ITUParserSamples.java rename to src/test/java/samples/parsing/ITUParserSamples.java index 2f7d86f..90bf397 100644 --- a/src/test/java/samples/ITUParserSamples.java +++ b/src/test/java/samples/parsing/ITUParserSamples.java @@ -1,4 +1,4 @@ -package samples; +package samples.parsing; /*- * #%L diff --git a/src/test/resources/sample-renderer.html b/src/test/resources/sample-renderer.html deleted file mode 100644 index 930d932..0000000 --- a/src/test/resources/sample-renderer.html +++ /dev/null @@ -1,33 +0,0 @@ - -{% for method in methods %} - -### {{method.name}} - -{{method.description | trim | raw }} - -```java -{{method.body | trim | raw }} - -``` - -[View source code]({{class.path}}/{{class.name}}.java#L{{method.range.begin.line}}C{{method.range.begin.column}}-L{{method.range.end.line}}C{{method.range.end.column}}) - -{% endfor %}