diff --git a/README.md b/README.md
index 05ec271..02709bf 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
[](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.ethlo.time%22%20a%3A%22itu%22)
[](https://javadoc.io/doc/com.ethlo.time/itu/latest/com/ethlo/time/ITU.html)
-[](LICENSE)
+[](../../LICENSE)
[](https://app.codacy.com/gh/ethlo/itu/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://codecov.io/gh/ethlo/itu)
@@ -43,150 +43,153 @@ Below you find some samples of usage of this library. Please check out the [java
### Parsing
-
-RFC-3339 with offset
-
+
+
+### parseRfc3339
+The simplest and fastest way to parse an RFC-3339 (ISO-8601 profile) timestamp by far!
```java
-final OffsetDateTime dateTime = ITU.parseDateTime("2012-12-27T19:07:22.123456789-03:00");
+final String text = "2012-12-27T19:07:22.123456789-03:00";
+final OffsetDateTime dateTime = ITU.parseDateTime(text);
+assertThat(dateTime.toString()).isEqualTo(text);
```
-
-
-Parse leniently
+[View source code](src/test/java/samples/ITUParserSamples.java#L63C5-L69C5)
+
+### parseLenient
+Parses a date-time with flexible granularity. Works for anything from a year to a timestamp with nanoseconds, wih or without timezone offset!
```java
-final DateTime dateTime = ITU.parseLenient("2012-12-27T19:07.23:123");
-final String formatted = dateTime.toString(); // 2012-12-27T19:07:23.123 (Note the tracking of resolution)
+final String text = "2012-12-27T19:07:23.123";
+final DateTime dateTime = ITU.parseLenient(text);
+final String formatted = dateTime.toString();
+//Note the tracking of fractional resolution
+assertThat(formatted).isEqualTo(text);
```
-
-
-Parse leniently, configurable separators
+[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.
```java
-import com.ethlo.time.ITU;
-import com.ethlo.time.ParseConfig;
+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");
+```
-class Sample {
- private final ParseConfig config = ParseConfig.DEFAULT
- .withFractionSeparators('.', ',')
- .withDateTimeSeparators('T', '|');
+[View source code](src/test/java/samples/ITUParserSamples.java#L89C5-L97C5)
- void parse() {
- ITU.parseLenient("1999-11-22|11:22:17,191", config);
- }
-}
+
+### 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);
+assertThat(result.toString()).isEqualTo("1999-11-22T11:22:19+05:30");
+assertThat(pos.getIndex()).isEqualTo(35);
```
-
-
-Parse with ParsePosition
+[View source code](src/test/java/samples/ITUParserSamples.java#L102C5-L109C5)
-This allows you to track where to start reading. Note that the check for trailing junk is disabled when using ParsePosition.
+### explicitGranularity
+This is useful if you need to handle different granularity with different logic or interpolation.
```java
-import com.ethlo.time.ITU;
+final TemporalHandler handler = new TemporalHandler() {
-import java.text.ParsePosition;
+ @Override
+ public OffsetDateTime handle(final LocalDate localDate) {
+ return localDate.atTime(OffsetTime.of(LocalTime.of(0, 0), ZoneOffset.UTC));
+ }
-class Sample {
- void parse() {
- final ParsePosition pos = new ParsePosition(10);
- ITU.parseDateTime("some-data,1999-11-22T11:22:00+05:30,some-other-data", pos);
+ @Override
+ public OffsetDateTime handle(final OffsetDateTime offsetDateTime) {
+ return offsetDateTime;
}
-}
+};
+final OffsetDateTime result = ITU.parse("2017-12-06", handler);
+assertThat(result.toString()).isEqualTo("2017-12-06T00:00Z");
```
-
-
-Handling different levels of granularity explicitly
+[View source code](src/test/java/samples/ITUParserSamples.java#L114C5-L134C5)
-This is useful if you need to handle different granularity with different logic or interpolation.
-
+### 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
-import com.ethlo.time.ITU;
-import com.ethlo.time.TemporalHandler;
+final Instant instant = ITU.parseLenient("2017-12-06").toInstant();
+assertThat(instant.toString()).isEqualTo("2017-12-06T00:00:00Z");
+```
-import java.time.OffsetDateTime;
+[View source code](src/test/java/samples/ITUParserSamples.java#L141C5-L146C5)
-class Sample {
- void parse() {
- ITU.parse("2017-12-06", new TemporalHandler<>() {
- @Override
- public OffsetDateTime handle(final LocalDate localDate) {
- return localDate.atTime(OffsetTime.of(LocalTime.of(0, 0), ZoneOffset.UTC));
- }
-
- @Override
- public OffsetDateTime handle(final OffsetDateTime offsetDateTime) {
- return offsetDateTime;
- }
- });
- }
-}
-```
-
-
-Parsing leniently to a timestamp
+### parseCustomFormat
+In case the format is not supported directly, you can build your own parser.
+```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";
+final DateTime result = parser.parse(text);
+assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456");
+```
-In some real world scenarios, it is useful to parse a best-effort timestamp. To ease usage, we can easily convert a raw `com.ethlo.time.DateTime` instance into `java.time.Instant`. Note the limitations and the assumption of UTC time-zone, as mentioned in the javadoc.
+[View source code](src/test/java/samples/ITUParserSamples.java#L151C5-L170C5)
-We can use `ITU.parseLenient()` with `DateTime.toInstant()` like this:
+### parseUsingInterfaceRfc33939
+`DateTimerParser` interface for RFC-3339
```java
-import com.ethlo.time.ITU;
+final DateTimeParser parser = DateTimeParsers.rfc3339();
+final String text = "2000-12-31 23:59:37.123456";
+final DateTime result = parser.parse(text);
+assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456");
+```
-import java.time.Instant;
+[View source code](src/test/java/samples/ITUParserSamples.java#L175C5-L182C5)
-class Sample {
- final Instant instant = ITU.parseLenient("2017-12-06").toInstant();
-}
+
+### parseUsingInterfaceLocalTime
+`DateTimerParser` interface for local time
+```java
+final DateTimeParser parser = DateTimeParsers.localTime();
+final String text = "23:59:37.123456";
+final LocalTime result = parser.parse(text).toLocalTime();
+assertThat(result.toString()).isEqualTo(text);
```
-
-
-Parse with custom format
+[View source code](src/test/java/samples/ITUParserSamples.java#L187C5-L194C5)
-In case the format is not supported directly, you can build your own parser:
+### parseUsingInterfaceLocalDate
+`DateTimerParser` interface for local date
```java
-import static com.ethlo.time.Field.DAY;
-import static com.ethlo.time.Field.HOUR;
-import static com.ethlo.time.Field.MINUTE;
-import static com.ethlo.time.Field.MONTH;
-import static com.ethlo.time.Field.SECOND;
-import static com.ethlo.time.Field.YEAR;
-import static com.ethlo.time.DateTimeTokens.digits;
-import static com.ethlo.time.DateTimeTokens.fractions;
-import static com.ethlo.time.DateTimeTokens.separators;
-import static com.ethlo.time.DateTimeTokens.zoneOffset;
-
-class Sample
-{
- void parseCustomFormat()
- {
- 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 input = "31-12-2000 235937,123456";
- final DateTime result = parser.parse(input);
- // equals 2000-12-31T23:59:37.123456
- }
-}
+final DateTimeParser parser = DateTimeParsers.localDate();
+final String text = "2013-12-24";
+final LocalDate result = parser.parse(text).toLocalDate();
+assertThat(result.toString()).isEqualTo(text);
```
-
+
+[View source code](src/test/java/samples/ITUParserSamples.java#L199C5-L206C5)
+
+
### Formatting
@@ -309,4 +312,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/test/java/samples/ITUParserSamples.java b/src/test/java/samples/ITUParserSamples.java
index f16e541..2f7d86f 100644
--- a/src/test/java/samples/ITUParserSamples.java
+++ b/src/test/java/samples/ITUParserSamples.java
@@ -48,8 +48,18 @@
import com.ethlo.time.ParseConfig;
import com.ethlo.time.TemporalHandler;
+/*
+
+## Parsing
+
+This is a collection of usage examples for parsing.
+
+ */
class ITUParserSamples
{
+ /*
+ The simplest and fastest way to parse an RFC-3339 (ISO-8601 profile) timestamp by far!
+ */
@Test
void parseRfc3339()
{
@@ -58,6 +68,9 @@ void parseRfc3339()
assertThat(dateTime.toString()).isEqualTo(text);
}
+ /*
+ Parses a date-time with flexible granularity. Works for anything from a year to a timestamp with nanoseconds, wih or without timezone offset!
+ */
@Test
void parseLenient()
{
@@ -69,6 +82,10 @@ void parseLenient()
assertThat(formatted).isEqualTo(text);
}
+ /*
+ 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.
+ */
@Test
void parseLenientWithCustomSeparators()
{
@@ -79,8 +96,8 @@ void parseLenientWithCustomSeparators()
assertThat(result.toString()).isEqualTo("1999-11-22T11:22:17.191");
}
- /**
- * 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()
@@ -91,8 +108,8 @@ void parsePosition()
assertThat(pos.getIndex()).isEqualTo(35);
}
- /**
- * This is useful if you need to handle different granularity with different logic or interpolation.
+ /*
+ This is useful if you need to handle different granularity with different logic or interpolation.
*/
@Test
void explicitGranularity()
@@ -116,11 +133,11 @@ public OffsetDateTime handle(final OffsetDateTime offsetDateTime)
assertThat(result.toString()).isEqualTo("2017-12-06T00:00Z");
}
- /**
- * In some real world scenarios, it is useful to parse a best-effort timestamp. To ease usage, we can easily convert a raw {@link DateTime} instance into {@link Instant}.
- *
- * Note the limitations and the assumption of UTC time-zone, as mentioned in the javadoc.
- */
+ /*
+ 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
void lenientTimestamp()
{
@@ -128,8 +145,8 @@ void lenientTimestamp()
assertThat(instant.toString()).isEqualTo("2017-12-06T00:00:00Z");
}
- /**
- * In case the format is not supported directly, you can build your own parser.
+ /*
+ In case the format is not supported directly, you can build your own parser.
*/
@Test
void parseCustomFormat()
@@ -152,6 +169,9 @@ void parseCustomFormat()
assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456");
}
+ /*
+ `DateTimerParser` interface for RFC-3339
+ */
@Test
void parseUsingInterfaceRfc33939()
{
@@ -161,6 +181,9 @@ void parseUsingInterfaceRfc33939()
assertThat(result.toString()).isEqualTo("2000-12-31T23:59:37.123456");
}
+ /*
+ `DateTimerParser` interface for local time
+ */
@Test
void parseUsingInterfaceLocalTime()
{
@@ -170,6 +193,9 @@ void parseUsingInterfaceLocalTime()
assertThat(result.toString()).isEqualTo(text);
}
+ /*
+ `DateTimerParser` interface for local date
+ */
@Test
void parseUsingInterfaceLocalDate()
{
diff --git a/src/test/resources/sample-renderer.html b/src/test/resources/sample-renderer.html
new file mode 100644
index 0000000..930d932
--- /dev/null
+++ b/src/test/resources/sample-renderer.html
@@ -0,0 +1,33 @@
+
+{% 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 %}