From b448712ca4a46d46fcfb1a902ee5ad076de69ae3 Mon Sep 17 00:00:00 2001 From: Morten Haraldsen Date: Sun, 11 Feb 2024 22:36:21 +0100 Subject: [PATCH] Update README.md --- README.md | 76 ++++++++++++++++---------------- src/site/sample-code.template.md | 5 ++- 2 files changed, 41 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 5b2cf42..52e807d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![Maven Central](https://img.shields.io/maven-central/v/com.ethlo.time/itu.svg)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.ethlo.time%22%20a%3A%22itu%22) [![javadoc](https://javadoc.io/badge2/com.ethlo.time/itu/javadoc.svg)](https://javadoc.io/doc/com.ethlo.time/itu/latest/com/ethlo/time/ITU.html) -[![Hex.pm](https://img.shields.io/hexpm/l/plug.svg)](LICENSE) +[![Hex.pm](https://img.shields.io/hexpm/l/plug.svg)](../../LICENSE) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/598913bc1fe9405c82be73d9a4f105c8)](https://app.codacy.com/gh/ethlo/itu/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![codecov](https://codecov.io/gh/ethlo/itu/graph/badge.svg?token=V3H15LKC5V)](https://codecov.io/gh/ethlo/itu) @@ -48,7 +48,8 @@ This is a collection of usage examples for parsing. -#### parseRfc3339 [» source](src/test/java/samples/parsing/ITUParserSamples.java#L60C5-L69C6) +#### parseRfc3339 +[source »](src/test/java/samples/parsing/ITUParserSamples.java#L60C5-L69C6) The simplest and fastest way to parse an RFC-3339 timestamp by far! ```java @@ -57,8 +58,8 @@ final OffsetDateTime dateTime = ITU.parseDateTime(text); assertThat(dateTime.toString()).isEqualTo(text); ``` - -#### parseLenient [» source](src/test/java/samples/parsing/ITUParserSamples.java#L71C5-L83C6) +#### parseLenient +[source »](src/test/java/samples/parsing/ITUParserSamples.java#L71C5-L83C6) Parses a date-time with flexible granularity. Works for anything from a year to a timestamp with nanoseconds, with or without timezone offset. ```java @@ -68,8 +69,8 @@ final String formatted = dateTime.toString(); assertThat(formatted).isEqualTo(text); ``` - -#### parseLenientWithCustomSeparators [» source](src/test/java/samples/parsing/ITUParserSamples.java#L85C5-L97C6) +#### parseLenientWithCustomSeparators +[source »](src/test/java/samples/parsing/ITUParserSamples.java#L85C5-L97C6) 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. @@ -81,8 +82,8 @@ final DateTime result = ITU.parseLenient("1999-11-22|11:22:17,191", config); assertThat(result.toString()).isEqualTo("1999-11-22T11:22:17.191"); ``` - -#### parsePosition [» source](src/test/java/samples/parsing/ITUParserSamples.java#L99C5-L109C6) +#### parsePosition +[source »](src/test/java/samples/parsing/ITUParserSamples.java#L99C5-L109C6) This allows you to track where to start reading. Note that the check for trailing junk is disabled when using `ParsePosition`. ```java @@ -92,8 +93,8 @@ assertThat(result.toString()).isEqualTo("1999-11-22T11:22:19+05:30"); assertThat(pos.getIndex()).isEqualTo(35); ``` - -#### explicitGranularity [» source](src/test/java/samples/parsing/ITUParserSamples.java#L111C5-L134C6) +#### explicitGranularity +[source »](src/test/java/samples/parsing/ITUParserSamples.java#L111C5-L134C6) This is useful if you need to handle different granularity with different logic or interpolation. ```java @@ -115,8 +116,8 @@ final OffsetDateTime result = ITU.parse("2017-12-06", handler); assertThat(result.toString()).isEqualTo("2017-12-06T00:00Z"); ``` - -#### lenientTimestamp [» source](src/test/java/samples/parsing/ITUParserSamples.java#L136C5-L146C6) +#### lenientTimestamp +[source »](src/test/java/samples/parsing/ITUParserSamples.java#L136C5-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`. @@ -126,8 +127,8 @@ final Instant instant = ITU.parseLenient("2017-12-06").toInstant(); assertThat(instant.toString()).isEqualTo("2017-12-06T00:00:00Z"); ``` - -#### parseCustomFormat [» source](src/test/java/samples/parsing/ITUParserSamples.java#L148C5-L170C6) +#### parseCustomFormat +[source »](src/test/java/samples/parsing/ITUParserSamples.java#L148C5-L170C6) In case the format is not supported directly, you can build your own parser. ```java @@ -149,8 +150,8 @@ final DateTime result = parser.parse(text); assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456"); ``` - -#### parseUsingInterfaceRfc33939 [» source](src/test/java/samples/parsing/ITUParserSamples.java#L172C5-L182C6) +#### parseUsingInterfaceRfc33939 +[source »](src/test/java/samples/parsing/ITUParserSamples.java#L172C5-L182C6) `DateTimerParser` interface for RFC-3339. ```java @@ -160,8 +161,8 @@ final DateTime result = parser.parse(text); assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456"); ``` - -#### parseUsingInterfaceLocalTime [» source](src/test/java/samples/parsing/ITUParserSamples.java#L184C5-L194C6) +#### parseUsingInterfaceLocalTime +[source »](src/test/java/samples/parsing/ITUParserSamples.java#L184C5-L194C6) `DateTimerParser` interface for local time. ```java @@ -171,8 +172,8 @@ final LocalTime result = parser.parse(text).toLocalTime(); assertThat(result.toString()).isEqualTo(text); ``` - -#### parseUsingInterfaceLocalDate [» source](src/test/java/samples/parsing/ITUParserSamples.java#L196C5-L206C6) +#### parseUsingInterfaceLocalDate +[source »](src/test/java/samples/parsing/ITUParserSamples.java#L196C5-L206C6) `DateTimerParser` interface for local date. ```java @@ -185,14 +186,14 @@ assertThat(result.toString()).isEqualTo(text); - ## Formatting This is a collection of usage examples for formatting. -#### formatRfc3339WithUTC [» source](src/test/java/samples/formatting/ITUFormattingSamples.java#L43C5-L54C6) +#### formatRfc3339WithUTC +[source »](src/test/java/samples/formatting/ITUFormattingSamples.java#L43C5-L54C6) The simplest and fastest way to format an RFC-3339 timestamp by far! ```java @@ -203,8 +204,8 @@ assertThat(ITU.formatUtcMilli(input)).isEqualTo("2012-12-27T22:07:22.123Z"); assertThat(ITU.formatUtc(input)).isEqualTo("2012-12-27T22:07:22Z"); ``` - -#### formatWithDateTime [» source](src/test/java/samples/formatting/ITUFormattingSamples.java#L56C5-L65C6) +#### formatWithDateTime +[source »](src/test/java/samples/formatting/ITUFormattingSamples.java#L56C5-L65C6) Format with `DateTime`. ```java @@ -216,30 +217,29 @@ assertThat(input.toString(Field.SECOND)).isEqualTo("2020-11-27T12:39:19"); - ## Leap-second handling -#### parseLeapSecond [» source](src/test/java/samples/leapsecond/ITULeapSecondSamples.java#L40C5-L57C6) +#### parseLeapSecond +[source »](src/test/java/samples/leapsecond/ITULeapSecondSamples.java#L40C5-L57C6) 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). ```java 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(1990, 12, 31, 16, 0, 0, 0, ZoneOffset.ofHours(-8))); - assertThat(exc.isVerifiedValidLeapYearMonth()).isTrue(); -} + { + 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(1990, 12, 31, 16, 0, 0, 0, ZoneOffset.ofHours(-8))); + assertThat(exc.isVerifiedValidLeapYearMonth()).isTrue(); + } ``` - ## Q & A ### Why this little project? @@ -303,4 +303,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/sample-code.template.md b/src/site/sample-code.template.md index 827b567..a1390ff 100644 --- a/src/site/sample-code.template.md +++ b/src/site/sample-code.template.md @@ -2,7 +2,9 @@ {% for method in methods %} -#### {{method.name}} [» 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 + 1}}) +#### {{method.name}} + +[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 + 1}}) {{method.description | trim | raw }} @@ -10,5 +12,4 @@ {{method.body | trim | raw }} ``` - {% endfor %}