import {YearWeek} from '@js-joda/root/packages/extra/src/YearWeek.js'

public class | source

YearWeek

Extends:

@js-joda/core~Temporal → YearWeek

A year-week in the ISO week date system such as 2015-W13

YearWeek is an immutable date-time object that represents the combination of a week-based-year and week-of-week-based-year. Any field that can be derived from those two fields can be obtained.

This class does not store or represent a day, time or time-zone. For example, the value '13th week of 2007' can be stored in a YearWeek.

The ISO-8601 calendar system is the modern civil calendar system used today in most of the world. It is equivalent to the proleptic Gregorian calendar system, in which today's rules for leap years are applied for all time. For most applications written today, the ISO-8601 rules are entirely suitable. However, any application that makes use of historical dates, and requires them to be accurate will find the ISO-8601 approach unsuitable.

ISO-8601 defines the week as always starting with Monday. The first week is the week which contains the first Thursday of the calendar year. As such, the week-based-year used in this class does not align with the calendar year.

Static Method Summary

Static Public Methods
public static	from(temporal: Temporal): YearWeek Obtains an instance of YearWeek from a temporal object.
public static	now(zoneIdOrClock: ZoneId \| Clock): YearWeek Function overloading for YearWeek.now: if called with no arguments, YearWeek._now0 is executed; if called with an instance of ZoneId, then YearWeek._nowZoneId is executed; if called with an instance of Clock, then YearWeek._nowClock is executed; otherwise IllegalArgumentException is thrown.
public static	of(year: Year \| number, week: number): YearWeek Function overloading for YearWeek.of: if called with an instances of Year and `int`, then YearWeek._ofYearWeek is executed; if called with an instances of number and `int`, then YearWeek._ofWeekBasedYear is executed; otherwise IllegalArgumentException is thrown.
public static	parse(text: string, formatter: DateTimeFormatter): YearWeek Obtains an instance of YearWeek from a text string using a specific formatter.

Static Protected Methods
protected static	_now0(): YearWeek Obtains the current year-week from the system clock in the default time-zone.
protected static	_nowClock(clock: Clock): YearWeek Obtains the current year-week from the specified clock.
protected static	_nowZoneId(zone: ZoneId): YearWeek Obtains the current year-week from the system clock in the specified time-zone.
protected static	_ofWeekBasedYear(weekBasedYear: number, week: number): YearWeek Obtains an instance of YearWeek from a week-based-year and week.
protected static	_ofYearWeek(year: Year, week: number): YearWeek Obtains an instance of YearWeek from a year and week.

Method Summary

Public Methods
public	adjustInto(temporal: Temporal): Temporal Adjusts the specified temporal object to have this year-week.
public	atDay(dayOfWeek: DayOfWeek): LocalDate Combines this year-week with a day-of-week to create a LocalDate.
public	compareTo(other: YearWeek): number Compares this year-week to another
public	equals(obj: *): boolean Checks if this year-week is equal to another year-week.
public	format(formatter: DateTimeFormatter): string Formats this year-week using the specified formatter.
public	get(field: TemporalField): number Gets the value of the specified field from this year-week as an `int`.
public	getLong(field: TemporalField): number Gets the value of the specified field from this year-week as a `long`.
public	hashCode(): number A hash code for this year-week.
public	is53WeekYear(): boolean Checks if the week-based-year has 53 weeks.
public	isAfter(other: YearWeek): boolean Is this year-week after the specified year-week.
public	isBefore(other: YearWeek): boolean Is this year-week before the specified year-week.
public	isSupported(fieldOrUnit: TemporalField \| TemporalUnit): boolean function overloading for YearWeek.isSupported if called with an instance of TemporalField, then YearWeek._isSupportedField is executed, if called with an instance of TemporalUnit, then YearWeek._isSupportedUnit is executed, otherwise IllegalArgumentException is thrown.
public	lengthOfYear(): number Returns the length of the week-based-year.
public	minusWeeks(weeksToSubtract: number): YearWeek Returns a copy of this year-week with the specified number of weeks subtracted.
public	minusYears(yearsToSubtract: number): YearWeek Returns a copy of this year-week with the specified number of years subtracted.
public	plusWeeks(weeksToAdd: number): YearWeek Returns a copy of this year-week with the specified number of weeks added.
public	plusYears(yearsToAdd: number): YearWeek Returns a copy of this year-week with the specified number of years added.
public	query(query: TemporalQuery): * Queries this year-week using the specified query.
public	range(field: TemporalField): ValueRange Gets the range of valid values for the specified field.
public	toString(): string Outputs this year-week as a String, such as `2015-W13`.
public	until(endExclusive: Temporal, unit: TemporalUnit): number Calculates the amount of time until another year-week in terms of the specified unit.
public	week(): number Gets the week-of-week-based-year field.
public	withWeek(week: number): YearWeek Returns a copy of this YearWeek with the week altered.
public	withYear(weekBasedYear: number): YearWeek Returns a copy of this YearWeek with the week-based-year altered.
public	year(): number Gets the week-based-year field.

Protected Methods
protected	_isSupportedField(field: TemporalField): boolean Checks if the specified field is supported.
protected	_isSupportedUnit(unit: TemporalUnit): boolean Checks if the specified unit is supported.

Static Public Methods

public static from(temporal: Temporal): YearWeek source

Obtains an instance of YearWeek from a temporal object.

This obtains a year-week based on the specified temporal. A TemporalAccessor represents an arbitrary set of date and time information, which this factory converts to an instance of YearWeek.

The conversion extracts the IsoFields.WEEK_BASED_YEAR WEEK_BASED_YEAR and IsoFields.WEEK_OF_WEEK_BASED_YEAR WEEK_OF_WEEK_BASED_YEAR fields. The extraction is only permitted if the temporal object has an ISO chronology, or can be converted to a LocalDate.

This method matches the signature of the functional interface TemporalQuery allowing it to be used in queries via method reference, YearWeek.FROM.

Params:

Name	Type	Attribute	Description
temporal	Temporal		the temporal object to convert, not null

Return:

YearWeek

the year-week, not null

Throw:

DateTimeException

if unable to convert to a YearWeek

public static now(zoneIdOrClock: ZoneId | Clock): YearWeek source

Function overloading for YearWeek.now:

if called with no arguments, YearWeek._now0 is executed;
if called with an instance of ZoneId, then YearWeek._nowZoneId is executed;
if called with an instance of Clock, then YearWeek._nowClock is executed;
otherwise IllegalArgumentException is thrown.

Params:

Name	Type	Attribute	Description
zoneIdOrClock	ZoneId \| Clock	nullable: true

Return:

YearWeek

public static of(year: Year | number, week: number): YearWeek source

Function overloading for YearWeek.of:

if called with an instances of Year and int, then YearWeek._ofYearWeek is executed;
if called with an instances of number and int, then YearWeek._ofWeekBasedYear is executed;
otherwise IllegalArgumentException is thrown.

Params:

Name	Type	Attribute	Description
year	Year \| number		the year to represent, not null
week	number		the week-of-week-based-year to represent, from 1 to 53

Return:

YearWeek

the year-week, not null

public static parse(text: string, formatter: DateTimeFormatter): YearWeek source

Obtains an instance of YearWeek from a text string using a specific formatter.

The text is parsed using the formatter, returning a year-week.

Params:

Name	Type	Attribute	Description
text	string		the text to parse, not null
formatter	DateTimeFormatter	optional default: YearWeek.PARSER	the formatter to use, default is YearWeek.PARSER

Return:

YearWeek

the parsed year-week, not null

Throw:

DateTimeParseException

if the text cannot be parsed

Static Protected Methods

protected static _now0(): YearWeek source

Obtains the current year-week from the system clock in the default time-zone.

This will query the Clock.systemDefaultZone system clock in the default time-zone to obtain the current year-week. The zone and offset will be set based on the time-zone in the clock.

Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.

Return:

YearWeek

the current year-week using the system clock and default time-zone, not null

protected static _nowClock(clock: Clock): YearWeek source

Obtains the current year-week from the specified clock.

This will query the specified clock to obtain the current year-week. Using this method allows the use of an alternate clock for testing. The alternate clock may be introduced using Clock dependency injection.

Params:

Name	Type	Attribute	Description
clock	Clock		the clock to use, not null

Return:

YearWeek

the current year-week, not null

protected static _nowZoneId(zone: ZoneId): YearWeek source

Obtains the current year-week from the system clock in the specified time-zone.

This will query the Clock.system system clock to obtain the current year-week. Specifying the time-zone avoids dependence on the default time-zone.

Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.

Params:

Name	Type	Attribute	Description
zone	ZoneId		the zone ID to use, not null

Return:

YearWeek

the current year-week using the system clock, not null

protected static _ofWeekBasedYear(weekBasedYear: number, week: number): YearWeek source

Obtains an instance of YearWeek from a week-based-year and week.

If the week is 53 and the year does not have 53 weeks, week one of the following year is selected.

Params:

Name	Type	Attribute	Description
weekBasedYear	number		the week-based-year to represent, from MIN_YEAR to MAX_YEAR
week	number		the week-of-week-based-year to represent, from 1 to 53

Return:

YearWeek

the year-week, not null

Throw:

DateTimeException

if either field is invalid

protected static _ofYearWeek(year: Year, week: number): YearWeek source

Obtains an instance of YearWeek from a year and week.

If the week is 53 and the year does not have 53 weeks, week one of the following year is selected.

Note that this class is based on the week-based-year which aligns to Monday to Sunday weeks, whereas Year is intended to represent standard years aligned from January to December. This difference may be seen at the start and/or end of the year. This method treats the standard year as though it is the week-based-year. Thus, YearWeek.of(Year.of(2020), 1) creates an object where Monday and Tuesday of the week are actually the last two days of 2019.

Params:

Name	Type	Attribute	Description
year	Year		the year to represent, not null
week	number		the week-of-week-based-year to represent, from 1 to 53

Return:

YearWeek

the year-week, not null

Throw:

DateTimeException

if the week value is invalid

Public Methods

public adjustInto(temporal: Temporal): Temporal source

Adjusts the specified temporal object to have this year-week.

This returns a temporal object of the same observable type as the input with the week-based-year and week changed to be the same as this.

The adjustment is equivalent to using Temporal.with twice, passing IsoFields.WEEK_BASED_YEAR and IsoFields.WEEK_OF_WEEK_BASED_YEAR as the fields. If the specified temporal object does not use the ISO calendar system then a DateTimeException is thrown.

In most cases, it is clearer to reverse the calling pattern by using Temporal.with:

  // these two lines are equivalent, but the second approach is recommended
  temporal = thisYearWeek.adjustInto(temporal);
  temporal = temporal.with(thisYearWeek);

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
temporal	Temporal		the target object to be adjusted, not null

Return:

Temporal

the adjusted object, not null

Throw:

DateTimeException	if unable to make the adjustment
ArithmeticException	if numeric overflow occurs

public atDay(dayOfWeek: DayOfWeek): LocalDate source

Combines this year-week with a day-of-week to create a LocalDate.

This returns a LocalDate formed from this year-week and the specified day-of-Week.

This method can be used as part of a chain to produce a date:

 LocalDate date = yearWeek.atDay(MONDAY);

Params:

Name	Type	Attribute	Description
dayOfWeek	DayOfWeek		the day-of-week to use, not null

Return:

LocalDate

the date formed from this year-week and the specified day, not null

public compareTo(other: YearWeek): number source

Compares this year-week to another

The comparison is based first on the value of the year, then on the value of the week. It is "consistent with equals", as defined by Comparable.

Params:

Name	Type	Attribute	Description
other	YearWeek		the other year-week to compare to, not null

Return:

number

the comparator value, negative if less, positive if greater

public equals(obj: *): boolean source

Checks if this year-week is equal to another year-week.

Params:

Name	Type	Attribute	Description
obj	*		the object to check, null returns false

Return:

boolean

true if this is equal to the other year-week

public format(formatter: DateTimeFormatter): string source

Formats this year-week using the specified formatter.

This year-week will be passed to the formatter to produce a string.

Params:

Name	Type	Attribute	Description
formatter	DateTimeFormatter		the formatter to use, not null

Return:

string

the formatted year-week string, not null

Throw:

DateTimeException

if an error occurs during printing

public get(field: TemporalField): number source

Gets the value of the specified field from this year-week as an int.

This queries this year-week for the value for the specified field. The returned value will always be within the valid range of values for the field. If it is not possible to return the value, because the field is not supported or for some other reason, an exception is thrown.

The value for the IsoFields.WEEK_BASED_YEAR WEEK_BASED_YEAR and IsoFields.WEEK_OF_WEEK_BASED_YEAR WEEK_OF_WEEK_BASED_YEAR fields is returned. All ChronoField instances will throw an UnsupportedTemporalTypeException.

Params:

Name	Type	Attribute	Description
field	TemporalField		the field to get, not null

Return:

number

the value for the field

Throw:

DateTimeException	if a value for the field cannot be obtained or the value is outside the range of valid values for the field
UnsupportedTemporalTypeException	if the field is not supported or the range of values exceeds an `int`
ArithmeticException	if numeric overflow occurs

public getLong(field: TemporalField): number source

Gets the value of the specified field from this year-week as a long.

This queries this year-week for the value for the specified field. If it is not possible to return the value, because the field is not supported or for some other reason, an exception is thrown.

Params:

Name	Type	Attribute	Description
field	TemporalField		the field to get, not null

Return:

number

the value for the field

Throw:

DateTimeException	if a value for the field cannot be obtained
UnsupportedTemporalTypeException	if the field is not supported
ArithmeticException	if numeric overflow occurs

public hashCode(): number source

A hash code for this year-week.

Return:

number

a suitable hash code

public is53WeekYear(): boolean source

Checks if the week-based-year has 53 weeks.

This determines if the year has 53 weeks, returning true. If false, the year has 52 weeks.

Return:

boolean

true if the year has 53 weeks, false otherwise

public isAfter(other: YearWeek): boolean source

Is this year-week after the specified year-week.

Params:

Name	Type	Attribute	Description
other	YearWeek		the other year-week to compare to, not null

Return:

boolean

true if this is after the specified year-week

public isBefore(other: YearWeek): boolean source

Is this year-week before the specified year-week.

Params:

Name	Type	Attribute	Description
other	YearWeek		the other year-week to compare to, not null

Return:

boolean

true if this point is before the specified year-week

public isSupported(fieldOrUnit: TemporalField | TemporalUnit): boolean source

function overloading for YearWeek.isSupported

if called with an instance of TemporalField, then YearWeek._isSupportedField is executed,
if called with an instance of TemporalUnit, then YearWeek._isSupportedUnit is executed,
otherwise IllegalArgumentException is thrown.

Params:

Name	Type	Attribute	Description
fieldOrUnit	TemporalField \| TemporalUnit

Return:

boolean

public lengthOfYear(): number source

Returns the length of the week-based-year.

This returns the length of the year in days, either 364 or 371.

Return:

number

364 if the year has 52 weeks, 371 if it has 53 weeks

public minusWeeks(weeksToSubtract: number): YearWeek source

Returns a copy of this year-week with the specified number of weeks subtracted.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
weeksToSubtract	number		the weeks to subtract, may be negative

Return:

YearWeek

the year-week with the weeks subtracted, not null

public minusYears(yearsToSubtract: number): YearWeek source

Returns a copy of this year-week with the specified number of years subtracted.

If the week of this instance is 53 and the new year does not have 53 weeks, the week will be adjusted to be 52.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
yearsToSubtract	number		the years to subtract, may be negative

Return:

YearWeek

the year-week with the years subtracted, not null

public plusWeeks(weeksToAdd: number): YearWeek source

Returns a copy of this year-week with the specified number of weeks added.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
weeksToAdd	number		the weeks to add, may be negative

Return:

YearWeek

the year-week with the weeks added, not null

public plusYears(yearsToAdd: number): YearWeek source

Returns a copy of this year-week with the specified number of years added.

If the week of this instance is 53 and the new year does not have 53 weeks, the week will be adjusted to be 52.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
yearsToAdd	number		the years to add, may be negative

Return:

YearWeek

the year-week with the years added, not null

public query(query: TemporalQuery): * source

Queries this year-week using the specified query.

This queries this year-week using the specified query strategy object. The TemporalQuery object defines the logic to be used to obtain the result. Read the documentation of the query to understand what the result of this method will be.

The result of this method is obtained by invoking the TemporalQuery.queryFrom method on the specified query passing this as the argument.

Params:

Name	Type	Attribute	Description
query	TemporalQuery		the query to invoke, not null

Return:

*	the query result, null may be returned (defined by the query)

Throw:

DateTimeException	if unable to query (defined by the query)
ArithmeticException	if numeric overflow occurs (defined by the query)

public range(field: TemporalField): ValueRange source

Gets the range of valid values for the specified field.

The range object expresses the minimum and maximum valid values for a field. This year-week is used to enhance the accuracy of the returned range. If it is not possible to return the range, because the field is not supported or for some other reason, an exception is thrown.

The range for the IsoFields.WEEK_BASED_YEAR WEEK_BASED_YEAR and IsoFields.WEEK_OF_WEEK_BASED_YEAR WEEK_OF_WEEK_BASED_YEAR fields is returned. All ChronoField instances will throw an UnsupportedTemporalTypeException.

Params:

Name	Type	Attribute	Description
field	TemporalField		the field to query the range for, not null

Return:

ValueRange

the range of valid values for the field, not null

Throw:

DateTimeException	if the range for the field cannot be obtained
UnsupportedTemporalTypeException	if the field is not supported

public toString(): string source

Outputs this year-week as a String, such as 2015-W13.

The output will be in the format YYYY-'W'ww:

Return:

string

a string representation of this year-week, not null

public until(endExclusive: Temporal, unit: TemporalUnit): number source

Calculates the amount of time until another year-week in terms of the specified unit.

This calculates the amount of time between two YearWeek objects in terms of a single TemporalUnit. The start and end points are this and the specified year-week. The result will be negative if the end is before the start. The Temporal passed to this method is converted to a YearWeek using YearWeek.from. For example, the period in years between two year-weeks can be calculated using startYearWeek.until(endYearWeek, YEARS).

The calculation returns a whole number, representing the number of complete units between the two year-weeks. For example, the period in years between 2012-W23 and 2032-W22 will only be 9 years as it is one week short of 10 years.

There are two equivalent ways of using this method. The first is to invoke this method. The second is to use TemporalUnit.between:

  // these two lines are equivalent
  amount = start.until(end, WEEKS);
  amount = WEEKS.between(start, end);

The choice should be made based on which makes the code more readable.

The calculation is implemented in this method for units WEEKS and WEEK_BASED_YEARS. Other ChronoUnit values will throw an exception.

If the unit is not a ChronoUnit, then the result of this method is obtained by invoking TemporalUnit.between passing this as the first argument and the converted input temporal as the second argument.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
endExclusive	Temporal		the end date, exclusive, which is converted to a YearWeek, not null
unit	TemporalUnit		the unit to measure the amount in, not null

Return:

number

the amount of time between this year-week and the end year-week

Throw:

DateTimeException	if the amount cannot be calculated, or the end temporal cannot be converted to a YearWeek
UnsupportedTemporalTypeException	if the unit is not supported
ArithmeticException	if numeric overflow occurs

public week(): number source

Gets the week-of-week-based-year field.

This method returns the primitive int value for the week of the week-based-year.

Return:

number

the week-of-week-based-year

public withWeek(week: number): YearWeek source

Returns a copy of this YearWeek with the week altered.

This returns a year-week with the specified week-of-week-based-year. If the new week is 53 and the year does not have 53 weeks, week one of the following year is selected.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
week	number		the week-of-week-based-year to set in the returned year-week

Return:

YearWeek

a year-week based on this year-week with the requested week, not null

Throw:

DateTimeException

if the week-of-week-based-year value is invalid

public withYear(weekBasedYear: number): YearWeek source

Returns a copy of this YearWeek with the week-based-year altered.

This returns a year-week with the specified week-based-year. If the week of this instance is 53 and the new year does not have 53 weeks, the week will be adjusted to be 52.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
weekBasedYear	number		the week-based-year to set in the returned year-week

Return:

YearWeek

a year-week based on this year-week with the requested year, not null

Throw:

DateTimeException

if the week-based-year value is invalid

public year(): number source

Gets the week-based-year field.

This method returns the primitive int value for the week-based-year.

Note that the ISO week-based-year does not align with the standard Gregorian/ISO calendar year.

Return:

number

the week-based-year

Protected Methods

protected _isSupportedField(field: TemporalField): boolean source

Checks if the specified field is supported.

This checks if this year-week can be queried for the specified field. If false, then calling the YearWeek.range range and YearWeek.get get methods will throw an exception.

The supported fields are:

IsoFields.WEEK_OF_WEEK_BASED_YEAR

IsoFields.WEEK_BASED_YEAR All other ChronoField instances will return false.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.isSupportedBy passing this as the argument. Whether the field is supported is determined by the field.

Params:

Name	Type	Attribute	Description
field	TemporalField		the field to check, null returns false

Return:

boolean

true if the field is supported on this year-week, false if not

protected _isSupportedUnit(unit: TemporalUnit): boolean source

Checks if the specified unit is supported.

This checks if the specified unit can be added to, or subtracted from, this date-time. If false, then calling the YearWeek.plus and YearWeek.minus minus methods will throw an exception.

The supported units are:

ChronoUnit.WEEKS
IsoFields.WEEK_BASED_YEARS

All other ChronoUnit instances will return false.

If the unit is not a ChronoUnit, then the result of this method is obtained by invoking TemporalUnit.isSupportedBy passing this as the argument. Whether the unit is supported is determined by the unit.

Params:

Name	Type	Attribute	Description
unit	TemporalUnit		the unit to check, null returns false

Return:

boolean

true if the unit can be added/subtracted, false if not