public final class WeekFields extends Object implements Serializable
A standard week is seven days long, but cultures have different definitions for some
other aspects of a week. This class represents the definition of the week, for the
purpose of providing TemporalField
instances.
WeekFields provides five fields,
dayOfWeek()
, weekOfMonth()
, weekOfYear()
,
weekOfWeekBasedYear()
, and weekBasedYear()
that provide access to the values from any temporal object.
The computations for dayofweek, weekofmonth, and weekofyear are based on the prolepticyear, monthofyear, dayofmonth, and ISO dayofweek which are based on the epochday and the chronology. The values may not be aligned with the yearofEra depending on the Chronology.
A week is defined by:
Date  Dayofweek  First day: Monday Minimal days: 4  First day: Monday Minimal days: 5 

20081231  Wednesday  Week 5 of December 2008  Week 5 of December 2008 
20090101  Thursday  Week 1 of January 2009  Week 0 of January 2009 
20090104  Sunday  Week 1 of January 2009  Week 0 of January 2009 
20090105  Monday  Week 2 of January 2009  Week 1 of January 2009 
weekofweekbasedyear
and one for
weekbasedyear
. In a weekbasedyear, each week
belongs to only a single year. Week 1 of a year is the first week that
starts on the first dayofweek and has at least the minimum number of days.
The first and last weeks of a year may contain days from the
previous calendar year or next calendar year respectively.
Date  Dayofweek  First day: Monday Minimal days: 4  First day: Monday Minimal days: 5 

20081231  Wednesday  Week 1 of 2009  Week 53 of 2008 
20090101  Thursday  Week 1 of 2009  Week 53 of 2008 
20090104  Sunday  Week 1 of 2009  Week 53 of 2008 
20090105  Monday  Week 2 of 2009  Week 1 of 2009 
Modifier and Type  Field and Description 

static WeekFields 
ISO
The ISO8601 definition, where a week starts on Monday and the first week
has a minimum of 4 days.

static WeekFields 
SUNDAY_START
The common definition of a week that starts on Sunday and the first week
has a minimum of 1 day.

static TemporalUnit 
WEEK_BASED_YEARS
The unit that represents weekbasedyears for the purpose of addition and subtraction.

Modifier and Type  Method and Description 

TemporalField 
dayOfWeek()
Returns a field to access the day of week based on this
WeekFields . 
boolean 
equals(Object object)
Checks if this
WeekFields is equal to the specified object. 
DayOfWeek 
getFirstDayOfWeek()
Gets the first dayofweek.

int 
getMinimalDaysInFirstWeek()
Gets the minimal number of days in the first week.

int 
hashCode()
A hash code for this
WeekFields . 
static WeekFields 
of(DayOfWeek firstDayOfWeek,
int minimalDaysInFirstWeek)
Obtains an instance of
WeekFields from the first dayofweek and minimal days. 
static WeekFields 
of(Locale locale)
Obtains an instance of
WeekFields appropriate for a locale. 
String 
toString()
A string representation of this
WeekFields instance. 
TemporalField 
weekBasedYear()
Returns a field to access the year of a weekbasedyear based on this
WeekFields . 
TemporalField 
weekOfMonth()
Returns a field to access the week of month based on this
WeekFields . 
TemporalField 
weekOfWeekBasedYear()
Returns a field to access the week of a weekbasedyear based on this
WeekFields . 
TemporalField 
weekOfYear()
Returns a field to access the week of year based on this
WeekFields . 
public static final WeekFields ISO
The ISO8601 standard defines a calendar system based on weeks. It uses the weekbasedyear and weekofweekbasedyear concepts to split up the passage of days instead of the standard year/month/day.
Note that the first week may start in the previous calendar year. Note also that the first few days of a calendar year may be in the weekbasedyear corresponding to the previous calendar year.
public static final WeekFields SUNDAY_START
Defined as starting on Sunday and with a minimum of 1 day in the month. This week definition is in use in the US and other European countries.
public static final TemporalUnit WEEK_BASED_YEARS
This allows a number of weekbasedyears to be added to, or subtracted from, a date.
The unit is equal to either 52 or 53 weeks.
The estimated duration of a weekbasedyear is the same as that of a standard ISO
year at 365.2425 Days
.
The rules for addition add the number of weekbasedyears to the existing value for the weekbasedyear field retaining the weekofweekbasedyear and dayofweek, unless the week number it too large for the target year. In that case, the week is set to the last week of the year with the same dayofweek.
This unit is an immutable and threadsafe singleton.
public static WeekFields of(Locale locale)
WeekFields
appropriate for a locale.
This will look up appropriate values from the provider of localization data.
locale
 the locale to use, not nullpublic static WeekFields of(DayOfWeek firstDayOfWeek, int minimalDaysInFirstWeek)
WeekFields
from the first dayofweek and minimal days.
The first dayofweek defines the ISO DayOfWeek
that is day 1 of the week.
The minimal number of days in the first week defines how many days must be present
in a month or year, starting from the first dayofweek, before the week is counted
as the first week. A value of 1 will count the first day of the month or year as part
of the first week, whereas a value of 7 will require the whole seven days to be in
the new month or year.
WeekFields instances are singletons; for each unique combination
of firstDayOfWeek
and minimalDaysInFirstWeek
the
the same instance will be returned.
firstDayOfWeek
 the first day of the week, not nullminimalDaysInFirstWeek
 the minimal number of days in the first week, from 1 to 7IllegalArgumentException
 if the minimal days value is less than one
or greater than 7public DayOfWeek getFirstDayOfWeek()
The first dayofweek varies by culture.
For example, the US uses Sunday, while France and the ISO8601 standard use Monday.
This method returns the first day using the standard DayOfWeek
enum.
public int getMinimalDaysInFirstWeek()
The number of days considered to define the first week of a month or year varies by culture. For example, the ISO8601 requires 4 days (more than half a week) to be present before counting the first week.
public TemporalField dayOfWeek()
WeekFields
.
This is similar to ChronoField.DAY_OF_WEEK
but uses values for
the dayofweek based on this WeekFields
.
The days are numbered from 1 to 7 where the
first dayofweek
is assigned the value 1.
For example, if the first dayofweek is Sunday, then that will have the value 1, with other days ranging from Monday as 2 to Saturday as 7.
In the resolving phase of parsing, a localized dayofweek will be converted
to a standardized ChronoField
dayofweek.
The dayofweek must be in the valid range 1 to 7.
Other fields in this class build dates using the standardized dayofweek.
public TemporalField weekOfMonth()
WeekFields
.
This represents the concept of the count of weeks within the month where weeks
start on a fixed dayofweek, such as Monday.
This field is typically used with dayOfWeek()
.
Week one (1) is the week starting on the getFirstDayOfWeek()
where there are at least getMinimalDaysInFirstWeek()
days in the month.
Thus, week one may start up to minDays
days before the start of the month.
If the first week starts after the start of the month then the period before is week zero (0).
For example:
 if the 1st day of the month is a Monday, week one starts on the 1st and there is no week zero
 if the 2nd day of the month is a Monday, week one starts on the 2nd and the 1st is in week zero
 if the 4th day of the month is a Monday, week one starts on the 4th and the 1st to 3rd is in week zero
 if the 5th day of the month is a Monday, week two starts on the 5th and the 1st to 4th is in week one
This field can be used with any calendar system.
In the resolving phase of parsing, a date can be created from a year, weekofmonth, monthofyear and dayofweek.
In strict mode, all four fields are validated against their range of valid values. The weekofmonth field is validated to ensure that the resulting month is the month requested.
In smart mode, all four fields are validated against their range of valid values. The weekofmonth field is validated from 0 to 6, meaning that the resulting date can be in a different month to that specified.
In lenient mode, the year and dayofweek are validated against the range of valid values. The resulting date is calculated equivalent to the following four stage approach. First, create a date on the first day of the first week of January in the requested year. Then take the monthofyear, subtract one, and add the amount in months to the date. Then take the weekofmonth, subtract one, and add the amount in weeks to the date. Finally, adjust to the correct dayofweek within the localized week.
public TemporalField weekOfYear()
WeekFields
.
This represents the concept of the count of weeks within the year where weeks
start on a fixed dayofweek, such as Monday.
This field is typically used with dayOfWeek()
.
Week one(1) is the week starting on the getFirstDayOfWeek()
where there are at least getMinimalDaysInFirstWeek()
days in the year.
Thus, week one may start up to minDays
days before the start of the year.
If the first week starts after the start of the year then the period before is week zero (0).
For example:
 if the 1st day of the year is a Monday, week one starts on the 1st and there is no week zero
 if the 2nd day of the year is a Monday, week one starts on the 2nd and the 1st is in week zero
 if the 4th day of the year is a Monday, week one starts on the 4th and the 1st to 3rd is in week zero
 if the 5th day of the year is a Monday, week two starts on the 5th and the 1st to 4th is in week one
This field can be used with any calendar system.
In the resolving phase of parsing, a date can be created from a year, weekofyear and dayofweek.
In strict mode, all three fields are validated against their range of valid values. The weekofyear field is validated to ensure that the resulting year is the year requested.
In smart mode, all three fields are validated against their range of valid values. The weekofyear field is validated from 0 to 54, meaning that the resulting date can be in a different year to that specified.
In lenient mode, the year and dayofweek are validated against the range of valid values. The resulting date is calculated equivalent to the following three stage approach. First, create a date on the first day of the first week in the requested year. Then take the weekofyear, subtract one, and add the amount in weeks to the date. Finally, adjust to the correct dayofweek within the localized week.
public TemporalField weekOfWeekBasedYear()
WeekFields
.
This represents the concept of the count of weeks within the year where weeks
start on a fixed dayofweek, such as Monday and each week belongs to exactly one year.
This field is typically used with dayOfWeek()
and
weekBasedYear()
.
Week one(1) is the week starting on the getFirstDayOfWeek()
where there are at least getMinimalDaysInFirstWeek()
days in the year.
If the first week starts after the start of the year then the period before
is in the last week of the previous year.
For example:
 if the 1st day of the year is a Monday, week one starts on the 1st
 if the 2nd day of the year is a Monday, week one starts on the 2nd and
the 1st is in the last week of the previous year
 if the 4th day of the year is a Monday, week one starts on the 4th and
the 1st to 3rd is in the last week of the previous year
 if the 5th day of the year is a Monday, week two starts on the 5th and
the 1st to 4th is in week one
This field can be used with any calendar system.
In the resolving phase of parsing, a date can be created from a weekbasedyear, weekofyear and dayofweek.
In strict mode, all three fields are validated against their range of valid values. The weekofyear field is validated to ensure that the resulting weekbasedyear is the weekbasedyear requested.
In smart mode, all three fields are validated against their range of valid values. The weekofweekbasedyear field is validated from 1 to 53, meaning that the resulting date can be in the following weekbasedyear to that specified.
In lenient mode, the year and dayofweek are validated against the range of valid values. The resulting date is calculated equivalent to the following three stage approach. First, create a date on the first day of the first week in the requested weekbasedyear. Then take the weekofweekbasedyear, subtract one, and add the amount in weeks to the date. Finally, adjust to the correct dayofweek within the localized week.
public TemporalField weekBasedYear()
WeekFields
.
This represents the concept of the year where weeks start on a fixed dayofweek,
such as Monday and each week belongs to exactly one year.
This field is typically used with dayOfWeek()
and
weekOfWeekBasedYear()
.
Week one(1) is the week starting on the getFirstDayOfWeek()
where there are at least getMinimalDaysInFirstWeek()
days in the year.
Thus, week one may start before the start of the year.
If the first week starts after the start of the year then the period before
is in the last week of the previous year.
This field can be used with any calendar system.
In the resolving phase of parsing, a date can be created from a weekbasedyear, weekofyear and dayofweek.
In strict mode, all three fields are validated against their range of valid values. The weekofyear field is validated to ensure that the resulting weekbasedyear is the weekbasedyear requested.
In smart mode, all three fields are validated against their range of valid values. The weekofweekbasedyear field is validated from 1 to 53, meaning that the resulting date can be in the following weekbasedyear to that specified.
In lenient mode, the year and dayofweek are validated against the range of valid values. The resulting date is calculated equivalent to the following three stage approach. First, create a date on the first day of the first week in the requested weekbasedyear. Then take the weekofweekbasedyear, subtract one, and add the amount in weeks to the date. Finally, adjust to the correct dayofweek within the localized week.
public boolean equals(Object object)
WeekFields
is equal to the specified object.
The comparison is based on the entire state of the rules, which is the first dayofweek and minimal days.
equals
in class Object
object
 the other rules to compare to, null returns falseObject.hashCode()
,
HashMap
public int hashCode()
WeekFields
.hashCode
in class Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developertargeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2020, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.