* 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 {@link TemporalField} instances. *
* WeekFields provides three fields, * {@link #dayOfWeek()}, {@link #weekOfMonth()}, and {@link #weekOfYear()} * that provide access to the values from any {@linkplain Temporal temporal object}. *
* The computations for day-of-week, week-of-month, and week-of-year are based * on the {@linkplain ChronoField#YEAR proleptic-year}, * {@linkplain ChronoField#MONTH_OF_YEAR month-of-year}, * {@linkplain ChronoField#DAY_OF_MONTH day-of-month}, and * {@linkplain ChronoField#DAY_OF_WEEK ISO day-of-week} which are based on the * {@linkplain ChronoField#EPOCH_DAY epoch-day} and the chronology. * The values may not be aligned with the {@linkplain ChronoField#YEAR_OF_ERA year-of-Era} * depending on the Chronology. *
A week is defined by: *
* Together these two values allow a year or month to be divided into weeks. *
*
*
| Date | Day-of-week | *First day: Monday Minimal days: 4 | First day: Monday Minimal days: 5 |
|---|---|---|---|
| 2008-12-31 | Wednesday | *Week 5 of December 2008 | Week 5 of December 2008 |
| 2009-01-01 | Thursday | *Week 1 of January 2009 | Week 0 of January 2009 |
| 2009-01-04 | Sunday | *Week 1 of January 2009 | Week 0 of January 2009 |
| 2009-01-05 | Monday | *Week 2 of January 2009 | Week 1 of January 2009 |
*
* This class is immutable and thread-safe.
*
* @since 1.8
*/
public final class WeekFields implements Serializable {
// implementation notes
// querying week-of-month or week-of-year should return the week value bound within the month/year
// however, setting the week value should be lenient (use plus/minus weeks)
// allow week-of-month outer range [0 to 5]
// allow week-of-year outer range [0 to 53]
// this is because callers shouldn't be expected to know the details of validity
/**
* The cache of rules by firstDayOfWeek plus minimalDays.
* Initialized first to be available for definition of ISO, etc.
*/
private static final ConcurrentMap
* The ISO-8601 standard defines a calendar system based on weeks.
* It uses the week-based-year and week-of-week-based-year 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
* week-based-year corresponding to the previous calendar year.
*/
public static final WeekFields ISO = new WeekFields(DayOfWeek.MONDAY, 4);
/**
* The common definition of a week that starts on Sunday.
*
* 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 WeekFields SUNDAY_START = WeekFields.of(DayOfWeek.SUNDAY, 1);
/**
* Serialization version.
*/
private static final long serialVersionUID = -1177360819670808121L;
/**
* The first day-of-week.
*/
private final DayOfWeek firstDayOfWeek;
/**
* The minimal number of days in the first week.
*/
private final int minimalDays;
/**
* The field used to access the computed DayOfWeek.
*/
private transient final TemporalField dayOfWeek = ComputedDayOfField.ofDayOfWeekField(this);
/**
* The field used to access the computed WeekOfMonth.
*/
private transient final TemporalField weekOfMonth = ComputedDayOfField.ofWeekOfMonthField(this);
/**
* The field used to access the computed WeekOfYear.
*/
private transient final TemporalField weekOfYear = ComputedDayOfField.ofWeekOfYearField(this);
/**
* Obtains an instance of {@code WeekFields} appropriate for a locale.
*
* This will look up appropriate values from the provider of localization data.
*
* @param locale the locale to use, not null
* @return the week-definition, not null
*/
public static WeekFields of(Locale locale) {
Objects.requireNonNull(locale, "locale");
locale = new Locale(locale.getLanguage(), locale.getCountry()); // elminate variants
// obtain these from GregorianCalendar for now
// TODO: consider getting them directly from the spi
GregorianCalendar gcal = new GregorianCalendar(locale);
int calDow = gcal.getFirstDayOfWeek();
DayOfWeek dow = DayOfWeek.SUNDAY.plus(calDow - 1);
int minDays = gcal.getMinimalDaysInFirstWeek();
return WeekFields.of(dow, minDays);
}
/**
* 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.
*
* @param firstDayOfWeek the first day of the week, not null
* @param minimalDaysInFirstWeek the minimal number of days in the first week, from 1 to 7
* @return the week-definition, not null
* @throws IllegalArgumentException if the minimal days value is less than one
* or greater than 7
*/
public static WeekFields of(DayOfWeek firstDayOfWeek, int minimalDaysInFirstWeek) {
String key = firstDayOfWeek.toString() + minimalDaysInFirstWeek;
WeekFields rules = CACHE.get(key);
if (rules == null) {
rules = new WeekFields(firstDayOfWeek, minimalDaysInFirstWeek);
CACHE.putIfAbsent(key, rules);
rules = CACHE.get(key);
}
return rules;
}
//-----------------------------------------------------------------------
/**
* Creates an instance of the definition.
*
* @param firstDayOfWeek the first day of the week, not null
* @param minimalDaysInFirstWeek the minimal number of days in the first week, from 1 to 7
* @throws IllegalArgumentException if the minimal days value is invalid
*/
private WeekFields(DayOfWeek firstDayOfWeek, int minimalDaysInFirstWeek) {
Objects.requireNonNull(firstDayOfWeek, "firstDayOfWeek");
if (minimalDaysInFirstWeek < 1 || minimalDaysInFirstWeek > 7) {
throw new IllegalArgumentException("Minimal number of days is invalid");
}
this.firstDayOfWeek = firstDayOfWeek;
this.minimalDays = minimalDaysInFirstWeek;
}
//-----------------------------------------------------------------------
/**
* Return the singleton WeekFields associated with the
* {@code firstDayOfWeek} and {@code minimalDays}.
* @return the singleton WeekFields for the firstDayOfWeek and minimalDays.
* @throws InvalidObjectException if the serialized object has invalid
* values for firstDayOfWeek or minimalDays.
*/
private Object readResolve() throws InvalidObjectException {
try {
return WeekFields.of(firstDayOfWeek, minimalDays);
} catch (IllegalArgumentException iae) {
throw new InvalidObjectException("Invalid serialized WeekFields: "
+ iae.getMessage());
}
}
//-----------------------------------------------------------------------
/**
* 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 the first day-of-week, not null
*/
public DayOfWeek getFirstDayOfWeek() {
return firstDayOfWeek;
}
/**
* 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 the minimal number of days in the first week of a month or year, from 1 to 7
*/
public int getMinimalDaysInFirstWeek() {
return minimalDays;
}
//-----------------------------------------------------------------------
/**
* Returns a field to access the day of week,
* computed based on this WeekFields.
*
* The days of week are numbered from 1 to 7.
* Day number 1 is the {@link #getFirstDayOfWeek() first day-of-week}.
*
* @return the field for day-of-week using this week definition, not null
*/
public TemporalField dayOfWeek() {
return dayOfWeek;
}
/**
* Returns a field to access the week of month,
* computed based on this WeekFields.
*
* This represents 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 {@link WeekFields#getFirstDayOfWeek}
* 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:
* This field can be used with any calendar system.
* @return a TemporalField to access the WeekOfMonth, not null
*/
public TemporalField weekOfMonth() {
return weekOfMonth;
}
/**
* Returns a field to access the week of year,
* computed based on this WeekFields.
*
* This represents 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 {@link WeekFields#getFirstDayOfWeek}
* 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 year.
* If the first week starts after the start of the year then the period before is week zero (0).
*
* For example:
* This field can be used with any calendar system.
* @return a TemporalField to access the WeekOfYear, not null
*/
public TemporalField weekOfYear() {
return weekOfYear;
}
/**
* Checks if these rules are equal to the specified rules.
*
* The comparison is based on the entire state of the rules, which is
* the first day-of-week and minimal days.
*
* @param object the other rules to compare to, null returns false
* @return true if this is equal to the specified rules
*/
@Override
public boolean equals(Object object) {
if (this == object) {
return true;
}
if (object instanceof WeekFields) {
return hashCode() == object.hashCode();
}
return false;
}
/**
* A hash code for these rules.
*
* @return a suitable hash code
*/
@Override
public int hashCode() {
return firstDayOfWeek.ordinal() * 7 + minimalDays;
}
//-----------------------------------------------------------------------
/**
* A string representation of this definition.
*
* @return the string representation, not null
*/
@Override
public String toString() {
return "WeekFields[" + firstDayOfWeek + ',' + minimalDays + ']';
}
//-----------------------------------------------------------------------
/**
* Field type that computes DayOfWeek, WeekOfMonth, and WeekOfYear
* based on a WeekFields.
* A separate Field instance is required for each different WeekFields;
* combination of start of week and minimum number of days.
* Constructors are provided to create fields for DayOfWeek, WeekOfMonth,
* and WeekOfYear.
*/
static class ComputedDayOfField implements TemporalField {
/**
* Returns a field to access the day of week,
* computed based on a WeekFields.
*
* The WeekDefintion of the first day of the week is used with
* the ISO DAY_OF_WEEK field to compute week boundaries.
*/
static ComputedDayOfField ofDayOfWeekField(WeekFields weekDef) {
return new ComputedDayOfField("DayOfWeek", weekDef,
ChronoUnit.DAYS, ChronoUnit.WEEKS, DAY_OF_WEEK_RANGE);
}
/**
* Returns a field to access the week of month,
* computed based on a WeekFields.
* @see WeekFields#weekOfMonth()
*/
static ComputedDayOfField ofWeekOfMonthField(WeekFields weekDef) {
return new ComputedDayOfField("WeekOfMonth", weekDef,
ChronoUnit.WEEKS, ChronoUnit.MONTHS, WEEK_OF_MONTH_RANGE);
}
/**
* Returns a field to access the week of year,
* computed based on a WeekFields.
* @see WeekFields#weekOfYear()
*/
static ComputedDayOfField ofWeekOfYearField(WeekFields weekDef) {
return new ComputedDayOfField("WeekOfYear", weekDef,
ChronoUnit.WEEKS, ChronoUnit.YEARS, WEEK_OF_YEAR_RANGE);
}
private final String name;
private final WeekFields weekDef;
private final TemporalUnit baseUnit;
private final TemporalUnit rangeUnit;
private final ValueRange range;
private ComputedDayOfField(String name, WeekFields weekDef, TemporalUnit baseUnit, TemporalUnit rangeUnit, ValueRange range) {
this.name = name;
this.weekDef = weekDef;
this.baseUnit = baseUnit;
this.rangeUnit = rangeUnit;
this.range = range;
}
private static final ValueRange DAY_OF_WEEK_RANGE = ValueRange.of(1, 7);
private static final ValueRange WEEK_OF_MONTH_RANGE = ValueRange.of(0, 1, 4, 5);
private static final ValueRange WEEK_OF_YEAR_RANGE = ValueRange.of(0, 1, 52, 53);
@Override
public long doGet(TemporalAccessor temporal) {
// Offset the ISO DOW by the start of this week
int sow = weekDef.getFirstDayOfWeek().getValue();
int isoDow = temporal.get(ChronoField.DAY_OF_WEEK);
int dow = Math.floorMod(isoDow - sow, 7) + 1;
if (rangeUnit == ChronoUnit.WEEKS) {
return dow;
} else if (rangeUnit == ChronoUnit.MONTHS) {
int dom = temporal.get(ChronoField.DAY_OF_MONTH);
int offset = startOfWeekOffset(dom, dow);
return computeWeek(offset, dom);
} else if (rangeUnit == ChronoUnit.YEARS) {
int doy = temporal.get(ChronoField.DAY_OF_YEAR);
int offset = startOfWeekOffset(doy, dow);
return computeWeek(offset, doy);
} else {
throw new IllegalStateException("unreachable");
}
}
/**
* Returns an offset to align week start with a day of month or day of year.
*
* @param day the day; 1 through infinity
* @param dow the day of the week of that day; 1 through 7
* @return an offset in days to align a day with the start of the first 'full' week
*/
private int startOfWeekOffset(int day, int dow) {
// offset of first day corresponding to the day of week in first 7 days (zero origin)
int weekStart = Math.floorMod(day - dow, 7);
int offset = -weekStart;
if (weekStart + 1 > weekDef.getMinimalDaysInFirstWeek()) {
// The previous week has the minimum days in the current month to be a 'week'
offset = 7 - weekStart;
}
return offset;
}
/**
* Returns the week number computed from the reference day and reference dayOfWeek.
*
* @param offset the offset to align a date with the start of week
* from {@link #startOfWeekOffset}.
* @param day the day for which to compute the week number
* @return the week number where zero is used for a partial week and 1 for the first full week
*/
private int computeWeek(int offset, int day) {
return ((7 + offset + (day - 1)) / 7);
}
@Override
public
* - 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
*
* - 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
*