Skip to content

8364752: java.time.Instant should be able to parse ISO 8601 offsets of the form HH:mm:ss #26708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 9 commits into
base: master
Choose a base branch
from
+71 −9
Open

8364752: java.time.Instant should be able to parse ISO 8601 offsets of the form HH:mm:ss #26708

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7fc267a
initial commit
naotoj Aug 8, 2025
5658f25
allow hour-only offsets
naotoj Aug 14, 2025
048f5ea
allow all ISO 8601 offsets
naotoj Aug 14, 2025
fa198b8
test cases
naotoj Aug 14, 2025
7523e34
copyright year update
naotoj Aug 15, 2025
8bc222a
Update src/java.base/share/classes/java/time/format/DateTimeFormatter…
naotoj Aug 18, 2025
a68b855
Merge branch 'master' into JDK-8364752-Instant-ISO8601
naotoj Aug 18, 2025
cd1507d
Added non-zero offset test cases
naotoj Aug 18, 2025
0d78a52
DateTimeFormatterBuilder wording
naotoj Aug 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions src/java.base/share/classes/java/time/format/DateTimeFormatter.java
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't copyright year need a bump?

Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2025, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -1199,8 +1199,10 @@ public static DateTimeFormatter ofLocalizedPattern(String requestedTemplate) {
* When formatting, the instant will always be suffixed by 'Z' to indicate UTC.
* The second-of-minute is always output.
* The nano-of-second outputs zero, three, six or nine digits as necessary.
* When parsing, the behaviour of {@link DateTimeFormatterBuilder#appendOffsetId()}
* will be used to parse the offset, converting the instant to UTC as necessary.
* When parsing, the lenient mode behavior of
* {@link DateTimeFormatterBuilder#appendOffset(String, String)
* appendOffset("+HH", "Z")} will be used to parse the offset,
* converting the instant to UTC as necessary.
* The time to at least the seconds field is required.
* Fractional seconds from zero to nine are parsed.
* The localized decimal style is not used.
Expand Down
11 changes: 7 additions & 4 deletions src/java.base/share/classes/java/time/format/DateTimeFormatterBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -894,8 +894,10 @@ public Iterator<Entry<String, Long>> getTextIterator(TemporalField field,
* {@link DateTimeFormatter#parsedLeapSecond()} for full details.
* <p>
* When formatting, the instant will always be suffixed by 'Z' to indicate UTC.
* When parsing, the behaviour of {@link DateTimeFormatterBuilder#appendOffsetId()}
* will be used to parse the offset, converting the instant to UTC as necessary.
* When parsing, the lenient mode behaviour of
* {@link DateTimeFormatterBuilder#appendOffset(String, String)
* appendOffset("+HH", "Z")} will be used to parse the offset,
* converting the instant to UTC as necessary.
* <p>
* An alternative to this method is to format/parse the instant as a single
* epoch-seconds value. That is achieved using {@code appendValue(INSTANT_SECONDS)}.
Expand Down Expand Up @@ -956,7 +958,7 @@ public DateTimeFormatterBuilder appendInstant(int fractionalDigits) {
* Appends the zone offset, such as '+01:00', to the formatter.
* <p>
* This appends an instruction to format/parse the offset ID to the builder.
* This is equivalent to calling {@code appendOffset("+HH:mm:ss", "Z")}.
* This is equivalent to calling {@code appendOffset("+HH:MM:ss", "Z")}.
* See {@link #appendOffset(String, String)} for details on formatting
* and parsing.
*
Expand Down Expand Up @@ -3887,7 +3889,8 @@ public int parse(DateTimeParseContext context, CharSequence text, int position)
.appendValue(MINUTE_OF_HOUR, 2).appendLiteral(':')
.appendValue(SECOND_OF_MINUTE, 2)
.appendFraction(NANO_OF_SECOND, minDigits, maxDigits, true)
.appendOffsetId()
.parseLenient()
.appendOffset("+HH", "Z")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "+HH" pattern is supposed to be ignoring minutes and seconds but it does not appear to. In jshell, I see:

jshell> Instant.parse("2017-01-01T00:00:00.000-02:10:12")
$8 ==> 2017-01-01T02:10:12Z

It would be more consistent with the original pattern to use "+HH:mm:ss"

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC, "ignoring minutes and seconds" refers to formatting, i.e, "-02:10:12" only prints "-02" Parsing offsets in lenient mode always parses minute/seconds.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True, but you have to read further into the appendOffset prose to know that the minutes and sections can be present. Using the full pattern would convey more quickly the full syntax being parsed.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the full pattern means the colons may not be optional. The appendOffset spec reads:

If the specified pattern is "+HH", the presence of colons is determined by whether the character after the hour digits is a colon or not.

Among the supported patterns, only "+HH" (and I believe "+H" too) take the colons optional in lenient mode, i.e, both "+02:00" and "+0200" are allowed, which suits the ISO 8601 offset format.

.toFormatter().toPrinterParser(false);
DateTimeParseContext newContext = context.copy();
int pos = parser.parse(newContext, text, position);
Expand Down
61 changes: 59 additions & 2 deletions test/jdk/java/time/test/java/time/TestInstant.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2024, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2025, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -61,6 +61,9 @@

import java.time.Duration;
import java.time.Instant;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;
import java.time.format.DateTimeParseException;
import java.time.temporal.ChronoUnit;

import org.testng.annotations.Test;
Expand All @@ -70,7 +73,7 @@

/**
* Test Instant.
* @bug 8273369 8331202
* @bug 8273369 8331202 8364752
*/
@Test
public class TestInstant extends AbstractTest {
Expand Down Expand Up @@ -151,4 +154,58 @@ public void test_until_1arg_NPE() {
Instant.now().until(null);
});
}

@DataProvider
private Object[][] valid_instants() {
var I1 = OffsetDateTime.of(2017, 1, 1, 0, 0, 0, 0, ZoneOffset.of("+02")).toInstant();
var I2 = OffsetDateTime.of(2017, 1, 1, 0, 0, 0, 0, ZoneOffset.of("+02:02")).toInstant();
var I3 = OffsetDateTime.of(2017, 1, 1, 0, 0, 0, 0, ZoneOffset.of("+02:02:02")).toInstant();
var I4 = OffsetDateTime.of(2017, 1, 1, 0, 0, 0, 0, ZoneOffset.of("Z")).toInstant();
return new Object[][] {
{"2017-01-01T00:00:00.000+02", I1},
{"2017-01-01T00:00:00.000+0200", I1},
{"2017-01-01T00:00:00.000+02:00", I1},
{"2017-01-01T00:00:00.000+020000", I1},
{"2017-01-01T00:00:00.000+02:00:00", I1},

{"2017-01-01T00:00:00.000+0202", I2},
{"2017-01-01T00:00:00.000+02:02", I2},

{"2017-01-01T00:00:00.000+020202", I3},
{"2017-01-01T00:00:00.000+02:02:02", I3},

{"2017-01-01T00:00:00.000Z", I4},
};
}

@Test(dataProvider = "valid_instants")
public void test_parse_valid(String instant, Instant expected) {
assertEquals(Instant.parse(instant), expected);
}

@DataProvider
private Object[][] invalid_instants() {
return new Object[][] {
{"2017-01-01T00:00:00.000"},
{"2017-01-01T00:00:00.000+0"},
{"2017-01-01T00:00:00.000+0:"},
{"2017-01-01T00:00:00.000+02:"},
Copy link
Contributor

@vy vy Aug 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is nice that leniency allows 0200 (i.e., missing white space), but not 02: or 02:00: (i.e., trailing separators).

{"2017-01-01T00:00:00.000+020"},
{"2017-01-01T00:00:00.000+02:0"},
{"2017-01-01T00:00:00.000+02:0:"},
{"2017-01-01T00:00:00.000+02:00:"},
{"2017-01-01T00:00:00.000+02:000"},
{"2017-01-01T00:00:00.000+02:00:0"},
{"2017-01-01T00:00:00.000+02:00:0:"},
{"2017-01-01T00:00:00.000+0200000"},
{"2017-01-01T00:00:00.000+02:00:000"},
{"2017-01-01T00:00:00.000+02:00:00:"},
{"2017-01-01T00:00:00.000UTC"},
};
}

@Test(dataProvider = "invalid_instants")
public void test_parse_invalid(String instant) {
assertThrows(DateTimeParseException.class, () -> Instant.parse(instant));
}
}