Home Reference Source
public class | source

WeekFields

Localized definitions of the day-of-week, week-of-month and week-of-year fields.

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 three fields, {@link #dayOfWeek()}, {@link #weekOfMonth()}, and {@link #weekOfYear()} that provide access to the values from any {@link Temporal temporal object}.

The computations for day-of-week, week-of-month, and week-of-year are based on the {@link ChronoField#YEAR proleptic-year}, {@link ChronoField#MONTH_OF_YEAR month-of-year}, {@link ChronoField#DAY_OF_MONTH day-of-month}, and {@link ChronoField#DAY_OF_WEEK ISO day-of-week} which are based on the {@link ChronoField#EPOCH_DAY epoch-day} and the chronology. The values may not be aligned with the {@link ChronoField#YEAR_OF_ERA year-of-Era} depending on the Chronology.

A week is defined by:

  • The first day-of-week. For example, the ISO-8601 standard considers Monday to be the first day-of-week.
  • The minimal number of days in the first week. For example, the ISO-8601 standard counts the first week as needing at least 4 days.

    Together these two values allow a year or month to be divided into weeks.

    Week of Month

    One field is used: week-of-month. The calculation ensures that weeks never overlap a month boundary. The month is divided into periods where each period starts on the defined first day-of-week. The earliest period is referred to as week 0 if it has less than the minimal number of days and week 1 if it has at least the minimal number of days.
  • <table cellpadding="0" cellspacing="3" border="0" style="text-align: left; width: 50%;">

    <caption>Examples of WeekFields</caption>

    <tr><th>Date</th><td>Day-of-week</td> <td>First day: Monday
    Minimal days: 4</td><td>First day: Monday
    Minimal days: 5</td></tr>

    <tr><th>2008-12-31</th><td>Wednesday</td> <td>Week 5 of December 2008</td><td>Week 5 of December 2008</td></tr>

    <tr><th>2009-01-01</th><td>Thursday</td> <td>Week 1 of January 2009</td><td>Week 0 of January 2009</td></tr>

    <tr><th>2009-01-04</th><td>Sunday</td> <td>Week 1 of January 2009</td><td>Week 0 of January 2009</td></tr>

    <tr><th>2009-01-05</th><td>Monday</td> <td>Week 2 of January 2009</td><td>Week 1 of January 2009</td></tr> </table>

    Week of Year

    One field is used: week-of-year. The calculation ensures that weeks never overlap a year boundary. The year is divided into periods where each period starts on the defined first day-of-week. The earliest period is referred to as week 0 if it has less than the minimal number of days and week 1 if it has at least the minimal number of days.

    This class is immutable and thread-safe.

    Static Method Summary

    Static Public Methods
    public static

    of(firstDayOrLocale: DayOfWeek | Locale, minDays: Number): WeekFields

    function overloading for WeekFields#of

    public static

    ofFirstDayOfWeekMinDays(firstDayOfWeek: DayOfWeek, minimalDaysInFirstWeek: Number): WeekFields

    Obtains an instance of {@code WeekFields} from the first day-of-week and minimal days.

    public static

    ofLocale(locale: Locale): *

    Obtains an instance of {@code WeekFields} appropriate for a locale.

    Method Summary

    Public Methods
    public

    Returns a field to access the day of week based on this {@code WeekFields}.

    public

    equals(other: *): *

    Checks if this {@code WeekFields} is equal to the specified other.

    public

    Gets the first day-of-week.

    public

    hashCode(): *

    A hash code for this {@code WeekFields}.

    public

    Gets the minimal number of days in the first week.

    public

    toString(): *

    A string representation of this {@code WeekFields} instance.

    public

    Returns a field to access the year of a week-based-year based on this {@code WeekFields}.

    public

    Returns a field to access the week of month based on this {@code WeekFields}.

    public

    Returns a field to access the week of a week-based-year based on this {@code WeekFields}.

    public

    Returns a field to access the week of year based on this {@code WeekFields}.

    Static Public Methods

    public static of(firstDayOrLocale: DayOfWeek | Locale, minDays: Number): WeekFields source

    function overloading for WeekFields#of

    if called with 1 arguments then WeekFields.ofLocale is executed.

    Otherwise WeekFields.ofFirstDayOfWeekMinDays is executed.

    Params:

    NameTypeAttributeDescription
    firstDayOrLocale DayOfWeek | Locale
    • nullable: false
    minDays Number

    Return:

    WeekFields

    this for chaining

    public static ofFirstDayOfWeekMinDays(firstDayOfWeek: DayOfWeek, minimalDaysInFirstWeek: Number): WeekFields source

    Obtains an instance of {@code WeekFields} from the first day-of-week and minimal days.

    The first day-of-week defines the ISO {@code 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 day-of-week, 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 {@code firstDayOfWeek} and {@code minimalDaysInFirstWeek} the the same instance will be returned.

    Params:

    NameTypeAttributeDescription
    firstDayOfWeek DayOfWeek
    • nullable: false

    the first day of the week, not null

    minimalDaysInFirstWeek Number
    • nullable: false

    the minimal number of days in the first week, from 1 to 7

    Return:

    WeekFields

    the week-definition, not null

    Throw:

    *

    IllegalArgumentException if the minimal days value is less than one or greater than 7

    public static ofLocale(locale: Locale): * source

    Obtains an instance of {@code WeekFields} appropriate for a locale.

    This will look up appropriate values from the provider of localization data.

    Params:

    NameTypeAttributeDescription
    locale Locale
    • nullable: false

    the locale to use, not null

    Return:

    *

    the week-definition, not null

    Public Methods

    public dayOfWeek(): TemporalField source

    Returns a field to access the day of week based on this {@code WeekFields}.

    This is similar to ChronoField#DAY_OF_WEEK but uses values for the day-of-week based on this {@code WeekFields}. The days are numbered from 1 to 7 where the {@link #getFirstDayOfWeek() first day-of-week} is assigned the value 1.

    For example, if the first day-of-week 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 day-of-week will be converted to a standardized {@code ChronoField} day-of-week. The day-of-week must be in the valid range 1 to 7. Other fields in this class build dates using the standardized day-of-week.

    Return:

    TemporalField

    a field providing access to the day-of-week with localized numbering, not null

    public equals(other: *): * source

    Checks if this {@code WeekFields} is equal to the specified other.

    The comparison is based on the entire state of the rules, which is the first day-of-week and minimal days.

    Params:

    NameTypeAttributeDescription
    other *

    the other rules to compare to, null returns false

    Return:

    *

    true if this is equal to the specified rules

    public firstDayOfWeek(): DayOfWeek source

    Gets the first day-of-week.

    The first day-of-week varies by culture. For example, the US uses Sunday, while France and the ISO-8601 standard use Monday. This method returns the first day using the standard {@code DayOfWeek} enum.

    Return:

    DayOfWeek

    the first day-of-week, not null

    public hashCode(): * source

    A hash code for this {@code WeekFields}.

    Return:

    *

    a suitable hash code

    public minimalDaysInFirstWeek(): Number source

    Gets the minimal number of days in the first week.

    The number of days considered to define the first week of a month or year varies by culture. For example, the ISO-8601 requires 4 days (more than half a week) to be present before counting the first week.

    Return:

    Number

    the minimal number of days in the first week of a month or year, from 1 to 7

    public toString(): * source

    A string representation of this {@code WeekFields} instance.

    Return:

    *

    the string representation, not null

    public weekBasedYear(): TemporalField source

    Returns a field to access the year of a week-based-year based on this {@code WeekFields}.

    This represents the concept of the year where weeks start on a fixed day-of-week, such as Monday and each week belongs to exactly one year. This field is typically used with {@link WeekFields#dayOfWeek()} and {@link WeekFields#weekOfWeekBasedYear()}.

    Week one(1) is the week starting on the WeekFields#firstDayOfWeek where there are at least {@link WeekFields#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 week-based-year, week-of-year and day-of-week.

    In {@linkplain ResolverStyle#STRICT strict mode}, all three fields are validated against their range of valid values. The week-of-year field is validated to ensure that the resulting week-based-year is the week-based-year requested.

    In {@linkplain ResolverStyle#SMART smart mode}, all three fields are validated against their range of valid values. The week-of-week-based-year field is validated from 1 to 53, meaning that the resulting date can be in the following week-based-year to that specified.

    In {@linkplain ResolverStyle#LENIENT lenient mode}, the year and day-of-week 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 week-based-year. Then take the week-of-week-based-year, subtract one, and add the amount in weeks to the date. Finally, adjust to the correct day-of-week within the localized week.

    Return:

    TemporalField

    a field providing access to the week-based-year, not null

    public weekOfMonth(): TemporalField source

    Returns a field to access the week of month based on this {@code WeekFields}.

    This represents the concept of the count of weeks within the month where weeks start on a fixed day-of-week, such as Monday. This field is typically used with {@link WeekFields#dayOfWeek()}.

    Week one (1) is the week starting on the WeekFields#firstDayOfWeek where there are at least {@link WeekFields#getMinimalDaysInFirstWeek()} days in the month. Thus, week one may start up to {@code 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, week-of-month, month-of-year and day-of-week.

      In {@linkplain ResolverStyle#STRICT strict mode}, all four fields are validated against their range of valid values. The week-of-month field is validated to ensure that the resulting month is the month requested.

      In {@linkplain ResolverStyle#SMART smart mode}, all four fields are validated against their range of valid values. The week-of-month field is validated from 0 to 6, meaning that the resulting date can be in a different month to that specified.

      In {@linkplain ResolverStyle#LENIENT lenient mode}, the year and day-of-week 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 month-of-year, subtract one, and add the amount in months to the date. Then take the week-of-month, subtract one, and add the amount in weeks to the date. Finally, adjust to the correct day-of-week within the localized week.

    Return:

    TemporalField

    a field providing access to the week-of-month, not null

    public weekOfWeekBasedYear(): TemporalField source

    Returns a field to access the week of a week-based-year based on this {@code WeekFields}.

    This represents the concept of the count of weeks within the year where weeks start on a fixed day-of-week, such as Monday and each week belongs to exactly one year. This field is typically used with {@link WeekFields#dayOfWeek()} and {@link WeekFields#weekBasedYear()}.

    Week one(1) is the week starting on the WeekFields#firstDayOfWeek where there are at least {@link WeekFields#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 week-based-year, week-of-year and day-of-week.

      In {@linkplain ResolverStyle#STRICT strict mode}, all three fields are validated against their range of valid values. The week-of-year field is validated to ensure that the resulting week-based-year is the week-based-year requested.

      In {@linkplain ResolverStyle#SMART smart mode}, all three fields are validated against their range of valid values. The week-of-week-based-year field is validated from 1 to 53, meaning that the resulting date can be in the following week-based-year to that specified.

      In {@linkplain ResolverStyle#LENIENT lenient mode}, the year and day-of-week 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 week-based-year. Then take the week-of-week-based-year, subtract one, and add the amount in weeks to the date. Finally, adjust to the correct day-of-week within the localized week.

    Return:

    TemporalField

    a field providing access to the week-of-week-based-year, not null

    public weekOfYear(): TemporalField source

    Returns a field to access the week of year based on this {@code WeekFields}.

    This represents the concept of the count of weeks within the year where weeks start on a fixed day-of-week, such as Monday. This field is typically used with {@link WeekFields#dayOfWeek()}.

    Week one(1) is the week starting on the WeekFields#firstDayOfWeek where there are at least {@link WeekFields#getMinimalDaysInFirstWeek()} days in the year. Thus, week one may start up to {@code 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, week-of-year and day-of-week.

      In {@linkplain ResolverStyle#STRICT strict mode}, all three fields are validated against their range of valid values. The week-of-year field is validated to ensure that the resulting year is the year requested.

      In {@linkplain ResolverStyle#SMART smart mode}, all three fields are validated against their range of valid values. The week-of-year field is validated from 0 to 54, meaning that the resulting date can be in a different year to that specified.

      In {@linkplain ResolverStyle#LENIENT lenient mode}, the year and day-of-week 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 week-of-year, subtract one, and add the amount in weeks to the date. Finally, adjust to the correct day-of-week within the localized week.

    Return:

    TemporalField

    a field providing access to the week-of-year, not null