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.
63 lines
2.6 KiB
Plaintext
63 lines
2.6 KiB
Plaintext
== Why is this an issue?
|
|
|
|
Few developers are aware of the difference between ``++Y++`` for "Week year" and ``++y++`` for Year when formatting and parsing a date with ``++SimpleDateFormat++`` or ``++DateTimeFormatter++``. That's likely because for most dates, Week year and Year are the same, so testing at any time other than the first or last week of the year will yield the same value for both ``++y++`` and ``++Y++``. But in the last week of December and the first week of January, you may get unexpected results.
|
|
|
|
|
|
According to the http://docs.oracle.com/javase/8/docs/api/java/util/GregorianCalendar.html#week_year[Javadoc]:
|
|
|
|
____
|
|
A week year is in sync with a WEEK_OF_YEAR cycle. All weeks between the first and last weeks (inclusive) have the same week year value. Therefore, the first and last days of a week year may have different calendar year values.
|
|
|
|
|
|
For example, January 1, 1998 is a Thursday. If getFirstDayOfWeek() is MONDAY and getMinimalDaysInFirstWeek() is 4 (ISO 8601 standard compatible setting), then week 1 of 1998 starts on December 29, 1997, and ends on January 4, 1998. The week year is 1998 for the last three days of calendar year 1997. If, however, getFirstDayOfWeek() is SUNDAY, then week 1 of 1998 starts on January 4, 1998, and ends on January 10, 1998; the first three days of 1998 then are part of week 53 of 1997 and their week year is 1997.
|
|
|
|
____
|
|
|
|
|
|
=== Noncompliant code example
|
|
|
|
[source,java]
|
|
----
|
|
Date date = new SimpleDateFormat("yyyy/MM/dd").parse("2015/12/31");
|
|
String result = new SimpleDateFormat("YYYY/MM/dd").format(date); //Noncompliant; yields '2016/12/31'
|
|
result = DateTimeFormatter.ofPattern("YYYY/MM/dd").format(date); //Noncompliant; yields '2016/12/31'
|
|
----
|
|
|
|
|
|
=== Compliant solution
|
|
|
|
[source,java]
|
|
----
|
|
Date date = new SimpleDateFormat("yyyy/MM/dd").parse("2015/12/31");
|
|
String result = new SimpleDateFormat("yyyy/MM/dd").format(date); //Yields '2015/12/31' as expected
|
|
result = DateTimeFormatter.ofPattern("yyyy/MM/dd").format(date); //Yields '2015/12/31' as expected
|
|
----
|
|
|
|
|
|
=== Exceptions
|
|
|
|
[source,java]
|
|
----
|
|
Date date = new SimpleDateFormat("yyyy/MM/dd").parse("2015/12/31");
|
|
String result = new SimpleDateFormat("YYYY-ww").format(date); //compliant, 'Week year' is used along with 'Week of year'. result = '2016-01'
|
|
DateTimeFormatter.ofPattern("YYYY-ww").format(date); //compliant; yields '2016-01' as expected
|
|
----
|
|
|
|
ifdef::env-github,rspecator-view[]
|
|
|
|
'''
|
|
== Implementation Specification
|
|
(visible only on this page)
|
|
|
|
=== Message
|
|
|
|
Make sure that Week Year ("[YYYY|YY]") is expected here instead of Year ("[yyyy|yy]").
|
|
|
|
|
|
=== Highlighting
|
|
|
|
The sequence of 'Y' letters
|
|
|
|
|
|
endif::env-github,rspecator-view[]
|