16f6c0aecf
Inline adoc files when they are included exactly once. Also fix language tags because this inlining gives us better information on what language the code is written in.
103 lines
3.4 KiB
Plaintext
103 lines
3.4 KiB
Plaintext
== Why is this an issue?
|
|
|
|
When creating a ``++DateTimeFormatter++`` using the ``++WeekFields.weekBasedYear()++`` temporal field, the resulting year number may be off by 1 at the beginning of a new year (when the date to format is in a week that is shared by two consecutive years).
|
|
|
|
Using this year number in combination with an incompatible week temporal field yields a result that may be confused with the first week of the previous year.
|
|
|
|
|
|
Instead, when paired with a week temporal field, the week-based year should only be used with the week of week-based year temporal field ``++WeekFields.weekOfWeekBasedYear()++``.
|
|
|
|
|
|
Alternatively the temporal field ``++ChronoField.ALIGNED_WEEK_OF_YEAR++`` can be used together with a regular year (but not the week based year).
|
|
|
|
|
|
=== Noncompliant code example
|
|
|
|
[source,java]
|
|
----
|
|
new DateTimeFormatterBuilder()
|
|
.appendValue(ChronoField.YEAR, 4) // Noncompliant: using week of week-based year with regular year
|
|
.appendLiteral('-')
|
|
.appendValue(WeekFields.ISO.weekOfWeekBasedYear(), 2)
|
|
.toFormatter();
|
|
|
|
new DateTimeFormatterBuilder()
|
|
.appendValue(ChronoField.YEAR_OF_ERA, 4) // Noncompliant: using week of week-based year with regular year
|
|
.appendLiteral('-')
|
|
.appendValue(WeekFields.ISO.weekOfWeekBasedYear(), 2)
|
|
.toFormatter();
|
|
|
|
new DateTimeFormatterBuilder()
|
|
.appendValue(WeekFields.ISO.weekBasedYear(), 4) // Noncompliant: using aligned week of year with week-based year
|
|
.appendLiteral('-')
|
|
.appendValue(ChronoField.ALIGNED_WEEK_OF_YEAR, 2)
|
|
.toFormatter();
|
|
----
|
|
|
|
Here the first two formatters would wrongly format the 1st of January 2016 as "2016-53" while the last one would format it as "2015-01"
|
|
|
|
|
|
=== Compliant solution
|
|
|
|
[source,java]
|
|
----
|
|
new DateTimeFormatterBuilder()
|
|
.appendValue(WeekFields.ISO.weekBasedYear(), 4)
|
|
.appendLiteral('-')
|
|
.appendValue(WeekFields.ISO.weekOfWeekBasedYear(), 2)
|
|
.toFormatter();
|
|
|
|
new DateTimeFormatterBuilder()
|
|
.appendValue(ChronoField.YEAR, 4)
|
|
.appendLiteral('-')
|
|
.appendValue(ChronoField.ALIGNED_WEEK_OF_YEAR, 2)
|
|
.toFormatter();
|
|
|
|
new DateTimeFormatterBuilder()
|
|
.appendValue(ChronoField.YEAR_OF_ERA, 4)
|
|
.appendLiteral('-')
|
|
.appendValue(ChronoField.ALIGNED_WEEK_OF_YEAR, 2)
|
|
.toFormatter();
|
|
----
|
|
|
|
Here the first formatter would format the 1st of January 2016 as "2015-53" while the last two would produce "2016-01", both of which are correct depending on how you count the weeks.
|
|
|
|
|
|
=== Exceptions
|
|
|
|
No issue is raised when week-based year is not used in combination with a week temporal field.
|
|
|
|
Similarly, no issue is raised if week of week-based year is not used in combination with a year temporal field.
|
|
|
|
|
|
ifdef::env-github,rspecator-view[]
|
|
|
|
'''
|
|
== Implementation Specification
|
|
(visible only on this page)
|
|
|
|
=== Message
|
|
|
|
Change this year format to use the week-based year instead.
|
|
|
|
or (when using ALIGNED_WEEK_OF_YEAR):
|
|
|
|
Change this year format to use ChronoField.YEAR instead
|
|
|
|
|
|
=== Highlighting
|
|
|
|
Primary: The use of yy/YEAR/YY/WEEK_BASED_YEAR/weakBasedYear()
|
|
|
|
Secondary: The use of ww/WEEK_OF_WEEK_BASED_YEAR/weekOfWeekBasedYear()/ALIGNED_WEEK_OF_YEAR
|
|
|
|
|
|
'''
|
|
== Comments And Links
|
|
(visible only on this page)
|
|
|
|
=== on 24 Jul 2020, 15:59:48 Ann Campbell wrote:
|
|
\[~sebastian.hungerecker] this Noncompliant example would benefit IMO from a comment showing the incorrect output. I.e. make it concrete like our initial, internal example.
|
|
|
|
endif::env-github,rspecator-view[]
|