Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
Morten Haraldsen committed Feb 11, 2024
1 parent 1c6ab8a commit b448712
Show file tree
Hide file tree
Showing 2 changed files with 41 additions and 40 deletions.
76 changes: 38 additions & 38 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -48,7 +48,8 @@ This is a collection of usage examples for parsing.



#### parseRfc3339 <span style="font-weight: normal">[&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L60C5-L69C6)</span>
#### parseRfc3339
<smaller style="float:right;">[source &raquo;](src/test/java/samples/parsing/ITUParserSamples.java#L60C5-L69C6)</smaller>

The simplest and fastest way to parse an RFC-3339 timestamp by far!
```java
Expand All @@ -57,8 +58,8 @@ final OffsetDateTime dateTime = ITU.parseDateTime(text);
assertThat(dateTime.toString()).isEqualTo(text);
```


#### parseLenient <span style="font-weight: normal">[&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L71C5-L83C6)</span>
#### parseLenient
<smaller style="float:right;">[source &raquo;](src/test/java/samples/parsing/ITUParserSamples.java#L71C5-L83C6)</smaller>

Parses a date-time with flexible granularity. Works for anything from a year to a timestamp with nanoseconds, with or without timezone offset.
```java
Expand All @@ -68,8 +69,8 @@ final String formatted = dateTime.toString();
assertThat(formatted).isEqualTo(text);
```


#### parseLenientWithCustomSeparators <span style="font-weight: normal">[&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L85C5-L97C6)</span>
#### parseLenientWithCustomSeparators
<smaller style="float:right;">[source &raquo;](src/test/java/samples/parsing/ITUParserSamples.java#L85C5-L97C6)</smaller>

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.
Expand All @@ -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 <span style="font-weight: normal">[&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L99C5-L109C6)</span>
#### parsePosition
<smaller style="float:right;">[source &raquo;](src/test/java/samples/parsing/ITUParserSamples.java#L99C5-L109C6)</smaller>

This allows you to track where to start reading. Note that the check for trailing junk is disabled when using `ParsePosition`.
```java
Expand All @@ -92,8 +93,8 @@ assertThat(result.toString()).isEqualTo("1999-11-22T11:22:19+05:30");
assertThat(pos.getIndex()).isEqualTo(35);
```


#### explicitGranularity <span style="font-weight: normal">[&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L111C5-L134C6)</span>
#### explicitGranularity
<smaller style="float:right;">[source &raquo;](src/test/java/samples/parsing/ITUParserSamples.java#L111C5-L134C6)</smaller>

This is useful if you need to handle different granularity with different logic or interpolation.
```java
Expand All @@ -115,8 +116,8 @@ final OffsetDateTime result = ITU.parse("2017-12-06", handler);
assertThat(result.toString()).isEqualTo("2017-12-06T00:00Z");
```


#### lenientTimestamp <span style="font-weight: normal">[&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L136C5-L146C6)</span>
#### lenientTimestamp
<smaller style="float:right;">[source &raquo;](src/test/java/samples/parsing/ITUParserSamples.java#L136C5-L146C6)</smaller>

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`.

Expand All @@ -126,8 +127,8 @@ final Instant instant = ITU.parseLenient("2017-12-06").toInstant();
assertThat(instant.toString()).isEqualTo("2017-12-06T00:00:00Z");
```


#### parseCustomFormat <span style="font-weight: normal">[&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L148C5-L170C6)</span>
#### parseCustomFormat
<smaller style="float:right;">[source &raquo;](src/test/java/samples/parsing/ITUParserSamples.java#L148C5-L170C6)</smaller>

In case the format is not supported directly, you can build your own parser.
```java
Expand All @@ -149,8 +150,8 @@ final DateTime result = parser.parse(text);
assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456");
```


#### parseUsingInterfaceRfc33939 <span style="font-weight: normal">[&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L172C5-L182C6)</span>
#### parseUsingInterfaceRfc33939
<smaller style="float:right;">[source &raquo;](src/test/java/samples/parsing/ITUParserSamples.java#L172C5-L182C6)</smaller>

`DateTimerParser` interface for RFC-3339.
```java
Expand All @@ -160,8 +161,8 @@ final DateTime result = parser.parse(text);
assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456");
```


#### parseUsingInterfaceLocalTime <span style="font-weight: normal">[&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L184C5-L194C6)</span>
#### parseUsingInterfaceLocalTime
<smaller style="float:right;">[source &raquo;](src/test/java/samples/parsing/ITUParserSamples.java#L184C5-L194C6)</smaller>

`DateTimerParser` interface for local time.
```java
Expand All @@ -171,8 +172,8 @@ final LocalTime result = parser.parse(text).toLocalTime();
assertThat(result.toString()).isEqualTo(text);
```


#### parseUsingInterfaceLocalDate <span style="font-weight: normal">[&raquo; source](src/test/java/samples/parsing/ITUParserSamples.java#L196C5-L206C6)</span>
#### parseUsingInterfaceLocalDate
<smaller style="float:right;">[source &raquo;](src/test/java/samples/parsing/ITUParserSamples.java#L196C5-L206C6)</smaller>

`DateTimerParser` interface for local date.
```java
Expand All @@ -185,14 +186,14 @@ assertThat(result.toString()).isEqualTo(text);




## Formatting

This is a collection of usage examples for formatting.



#### formatRfc3339WithUTC <span style="font-weight: normal">[&raquo; source](src/test/java/samples/formatting/ITUFormattingSamples.java#L43C5-L54C6)</span>
#### formatRfc3339WithUTC
<smaller style="float:right;">[source &raquo;](src/test/java/samples/formatting/ITUFormattingSamples.java#L43C5-L54C6)</smaller>

The simplest and fastest way to format an RFC-3339 timestamp by far!
```java
Expand All @@ -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 <span style="font-weight: normal">[&raquo; source](src/test/java/samples/formatting/ITUFormattingSamples.java#L56C5-L65C6)</span>
#### formatWithDateTime
<smaller style="float:right;">[source &raquo;](src/test/java/samples/formatting/ITUFormattingSamples.java#L56C5-L65C6)</smaller>

Format with `DateTime`.
```java
Expand All @@ -216,30 +217,29 @@ assertThat(input.toString(Field.SECOND)).isEqualTo("2020-11-27T12:39:19");




## Leap-second handling



#### parseLeapSecond <span style="font-weight: normal">[&raquo; source](src/test/java/samples/leapsecond/ITULeapSecondSamples.java#L40C5-L57C6)</span>
#### parseLeapSecond
<smaller style="float:right;">[source &raquo;](src/test/java/samples/leapsecond/ITULeapSecondSamples.java#L40C5-L57C6)</smaller>

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?
Expand Down Expand Up @@ -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`.
5 changes: 3 additions & 2 deletions src/site/sample-code.template.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,14 @@

{% for method in methods %}

#### {{method.name}} <span style="font-weight: normal">[&raquo; 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}})</span>
#### {{method.name}}

<smaller style="float:right;">[source &raquo;]({{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}})</smaller>

{{method.description | trim | raw }}

```java
{{method.body | trim | raw }}

```

{% endfor %}

0 comments on commit b448712

Please sign in to comment.