== 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[]