Home Reference Source
import {Year} from 'js-joda/src/Year.js'
public class | source

Year

Extends:

TemporalAccessorTemporal → Year

A year in the ISO-8601 calendar system, such as 2007.

Year is an immutable date-time object that represents a year. Any field that can be derived from a year can be obtained.

Note that years in the ISO chronology only align with years in the Gregorian-Julian system for modern years. Parts of Russia did not switch to the modern Gregorian/ISO rules until 1920. As such, historical years must be treated with caution.

This class does not store or represent a month, day, time or time-zone. For example, the value "2007" can be stored in a Year.

Years represented by this class follow the ISO-8601 standard and use the proleptic numbering system. Year 1 is preceded by year 0, then by year -1.

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.

Static properties of Class LocalDate

Year.MIN_VALUE = -999.999;

The minimum supported year. Theoretically the minimum could be -28.542.4812 years in javascript. approx LocalDateTime.ofEpochSecond(Number.MIN_SAFE_INTEGER, 0, ZoneOffset.UTC).year()

Year.MAX_VALUE = 999.999;

The maximum supported year. Theoretically the maximum could be 285.428.751 years in javascript. approx LocalDateTime.ofEpochSecond(Number.MAX_SAFE_INTEGER, 0, ZoneOffset.UTC).year()

Static Method Summary

Static Public Methods
public static

from(temporal: TemporalAccessor): Year

Obtains an instance of Year from a temporal object.

public static

Checks if the year is a leap year, according to the ISO proleptic calendar system rules.

public static

now(zoneIdOrClock: ZoneId | Clock): Year

function overloading for Year.now

public static

now0(): Year

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

public static

nowClock(clock: Clock): Year

Obtains the current year from the specified clock.

public static

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

public static

of(isoYear: Number): Year

Obtains an instance of Year.

public static

parse(text: String, formatter: DateTimeFormatter): Year

function overloading for Year.parse

public static

Obtains an instance of Year from a text string such as 2007.

public static

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

Method Summary

Public Methods
public

Adjusts the specified temporal object to have this year.

public

atDay(dayOfYear: number): LocalDate

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

public

atMonth(monthOrNumber: Month | number): YearMonth

function overloading for Year.atMonth

public

Combines this year with a month-day to create a LocalDate.

public

Combines this year with a month to create a YearMonth.

public

Combines this year with a month to create a YearMonth.

public

compareTo(other: Year): number

Compares this year to another year.

public

equals(otherYear: *): boolean

Checks if this year is equal to the specified Year.

public

Outputs this year as a string using the formatter.

public

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

public

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

public

isAfter(other: Year): boolean

Is this year after the specified year.

public

isBefore(other: Year): boolean

Is this year before the specified year.

public

Checks if the year is a leap year, according to the ISO proleptic calendar system rules.

public

function overloading for YearMonth.isSupported

public

Checks if the specified field is supported.

public

isSupportedUnit(unit: *): *

public

Checks if the month-day is valid for this year.

public

Gets the length of this year in days.

public

minus(amountOrNumber: TemporalAmount | number, unit: TemporalUnit): Year

function overloading for Year.minus

public

Returns a copy of this year with the specified period subtracted.

public

minusAmountToSubtractUnit(amountToSubtract: number, unit: TemporalUnit): Year

public

minusYears(yearsToSubtract: number): Year

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

public

plus(amountOrNumber: TemporalAmount | number, unit: TemporalUnit): Year

function overloading for Year.plus

public

Returns a copy of this year with the specified period added.

public
public

plusYears(yearsToAdd: number): Year

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

public

query(query: TemporalQuery): *

Queries this year using the specified query.

public

Gets the range of valid values for the specified field.

public

toJSON() use by JSON.stringify delegates to toString()

public

Outputs this year as a string.

public
public

with(adjusterOrFieldOrNumber: TemporalAdjuster | TemporalField | Number, value: number): Year

function overloading for YearMonth.with

public

Returns an adjusted copy of this year.

public

withFieldValue(field: TemporalField, newValue: number): Year

Returns a copy of this year with the specified field set to a new value.

Inherited Summary

From class TemporalAccessor
public

Gets the value of the specified field as an int.

public

query(query: TemporalQuery): *

Queries this date-time.

public

Gets the range of valid values for the specified field.

Static Public Methods

public static from(temporal: TemporalAccessor): Year source

Obtains an instance of Year from a temporal object.

A TemporalAccessor represents some form of date and time information. This factory converts the arbitrary temporal object to an instance of Year.

The conversion extracts the ChronoField#YEAR field. 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, Year::from.

Params:

NameTypeAttributeDescription
temporal TemporalAccessor

the temporal object to convert, not null

Return:

Year

the year, not null

Throw:

*

DateTimeException if unable to convert to a Year

public static isLeap(year: number): boolean source

Checks if the year is a leap year, according to the ISO proleptic calendar system rules.

This method applies the current rules for leap years across the whole time-line. In general, a year is a leap year if it is divisible by four without remainder. However, years divisible by 100, are not leap years, with the exception of years divisible by 400 which are.

For example, 1904 is a leap year it is divisible by 4. 1900 was not a leap year as it is divisible by 100, however 2000 was a leap year as it is divisible by 400.

The calculation is proleptic - applying the same rules into the far future and far past. This is historically inaccurate, but is correct for the ISO-8601 standard.

Params:

NameTypeAttributeDescription
year number

the year to check

Return:

boolean

true if the year is leap, false otherwise

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

function overloading for Year.now

if called without arguments, then Year.now0 is executed.

if called with 1 arguments and first argument is an instance of ZoneId, then Year.nowZoneId is executed.

Otherwise Year.nowClock is executed.

Params:

NameTypeAttributeDescription
zoneIdOrClock ZoneId | Clock
  • nullable: false

Return:

Year

public static now0(): Year source

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

This will query the system clock (see Clock#systemDefaultZone) in the default time-zone to obtain the current year.

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

Return:

Year

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

public static nowClock(clock: Clock): Year source

Obtains the current year from the specified clock.

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

Params:

NameTypeAttributeDescription
clock Clock

the clock to use, not null

Return:

Year

the current year, not null

public static nowZoneId(zone: ZoneId): Year source

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

This will query the system clock (see Clock#system) to obtain the current year. 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:

NameTypeAttributeDescription
zone ZoneId

the zone ID to use, not null

Return:

Year

the current year using the system clock, not null

public static of(isoYear: Number): Year source

Obtains an instance of Year.

This method accepts a year value from the proleptic ISO calendar system.

  • The year 2AD/CE is represented by 2.
  • The year 1AD/CE is represented by 1.
  • The year 1BC/BCE is represented by 0.
  • The year 2BC/BCE is represented by -1.

Params:

NameTypeAttributeDescription
isoYear Number

the ISO proleptic year to represent, from MIN_VALUE to MAX_VALUE

Return:

Year

the year, not null

Throw:

*

DateTimeException if the field is invalid

public static parse(text: String, formatter: DateTimeFormatter): Year source

function overloading for Year.parse

if called with 1 argument, then Year.parseText is executed.

Otherwise Year.parseTextFormatter is executed.

Params:

NameTypeAttributeDescription
text String
  • nullable: false
formatter DateTimeFormatter
  • nullable: true

Return:

Year

public static parseText(text: String): Year source

Obtains an instance of Year from a text string such as 2007.

The string must represent a valid year. Years outside the range 0000 to 9999 must be prefixed by the plus or minus symbol.

Params:

NameTypeAttributeDescription
text String

the text to parse such as "2007", not null

Return:

Year

the parsed year, not null

Throw:

*

DateTimeParseException if the text cannot be parsed

public static parseTextFormatter(text: String, formatter: DateTimeFormatter): Year source

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

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

Params:

NameTypeAttributeDescription
text String

the text to parse, not null

formatter DateTimeFormatter

the formatter to use, not null

Return:

Year

the parsed year, not null

Throw:

*

DateTimeParseException if the text cannot be parsed

Public Methods

public adjustInto(temporal: Temporal): Temporal source

Adjusts the specified temporal object to have this year.

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

The adjustment is equivalent to using Temporal#with passing ChronoField#YEAR as the field. 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 = thisYear.adjustInto(temporal);
  temporal = temporal.with(thisYear);

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
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(dayOfYear: number): LocalDate source

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

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

The day-of-year value 366 is only valid in a leap year.

Params:

NameTypeAttributeDescription
dayOfYear number

the day-of-year to use, not null

Return:

LocalDate

the local date formed from this year and the specified date of year, not null

Throw:

*

DateTimeException if the day of year is zero or less, 366 or greater or equal to 366 and this is not a leap year

public atMonth(monthOrNumber: Month | number): YearMonth source

function overloading for Year.atMonth

if called with 1 arguments and first argument is instance of Month, then Year.atMonthMonth is executed.

Otherwise Year.atMonthNumber is executed.

Params:

NameTypeAttributeDescription
monthOrNumber Month | number

Return:

YearMonth

public atMonthDay(monthDay: MonthDay): LocalDate source

Combines this year with a month-day to create a LocalDate.

This returns a LocalDate formed from this year and the specified month-day.

A month-day of February 29th will be adjusted to February 28th in the resulting date if the year is not a leap year.

Params:

NameTypeAttributeDescription
monthDay MonthDay

the month-day to use, not null

Return:

LocalDate

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

public atMonthMonth(month: Month): YearMonth source

Combines this year with a month to create a YearMonth.

This returns a YearMonth formed from this year and the specified month. All possible combinations of year and month are valid.

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

 LocalDate date = year.atMonth(month).atDay(day);

Params:

NameTypeAttributeDescription
month Month

the month-of-year to use, not null

Return:

YearMonth

the year-month formed from this year and the specified month, not null

public atMonthNumber(month: number): YearMonth source

Combines this year with a month to create a YearMonth.

This returns a YearMonth formed from this year and the specified month. All possible combinations of year and month are valid.

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

 LocalDate date = year.atMonth(month).atDay(day);

Params:

NameTypeAttributeDescription
month number

the month-of-year to use, from 1 (January) to 12 (December)

Return:

YearMonth

the year-month formed from this year and the specified month, not null

Throw:

*

DateTimeException if the month is invalid

public compareTo(other: Year): number source

Compares this year to another year.

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

Params:

NameTypeAttributeDescription
other Year

the other year to compare to, not null

Return:

number

the comparator value, negative if less, positive if greater

public equals(otherYear: *): boolean source

Checks if this year is equal to the specified Year.

The comparison is based on the value

Params:

NameTypeAttributeDescription
otherYear *

the other year, null returns false

Return:

boolean

true if the other duration is equal to this one

public format(formatter: DateTimeFormatter): String source

Outputs this year as a string using the formatter.

Params:

NameTypeAttributeDescription
formatter DateTimeFormatter

the formatter to use, not null

Return:

String

the formatted year 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 as an int.

This queries this year 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.

If the field is a ChronoField then the query is implemented here. The supported fields (see isSupported) will return valid values based on this year. All other ChronoField instances will throw a DateTimeException.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.getFrom passing this as the argument. Whether the value can be obtained, and what the value represents, is determined by the field.

Override:

TemporalAccessor#get

Params:

NameTypeAttributeDescription
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

*

ArithmeticException if numeric overflow occurs

public getLong(field: TemporalField): number source

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

This queries this year 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.

If the field is a ChronoField then the query is implemented here. The supported fields (see isSupported) will return valid values based on this year. All other ChronoField instances will throw a DateTimeException.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.getFrom passing this as the argument. Whether the value can be obtained, and what the value represents, is determined by the field.

Params:

NameTypeAttributeDescription
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

*

ArithmeticException if numeric overflow occurs

public isAfter(other: Year): boolean source

Is this year after the specified year.

Params:

NameTypeAttributeDescription
other Year

the other year to compare to, not null

Return:

boolean

true if this is after the specified year

public isBefore(other: Year): boolean source

Is this year before the specified year.

Params:

NameTypeAttributeDescription
other Year

the other year to compare to, not null

Return:

boolean

true if this point is before the specified year

public isLeap(): boolean source

Checks if the year is a leap year, according to the ISO proleptic calendar system rules.

This method applies the current rules for leap years across the whole time-line. In general, a year is a leap year if it is divisible by four without remainder. However, years divisible by 100, are not leap years, with the exception of years divisible by 400 which are.

For example, 1904 is a leap year it is divisible by 4. 1900 was not a leap year as it is divisible by 100, however 2000 was a leap year as it is divisible by 400.

The calculation is proleptic - applying the same rules into the far future and far past. This is historically inaccurate, but is correct for the ISO-8601 standard.

Return:

boolean

true if the year is leap, false otherwise

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

function overloading for YearMonth.isSupported

if called with 1 argument and first argument is an instance of TemporalField, then YearMonth.isSupportedField is executed,

otherwise YearMonth.isSupportedUnit is executed

Params:

NameTypeAttributeDescription
fieldOrUnit TemporalField | ChronoUnit
  • nullable: false

Return:

boolean

public isSupportedField(field: TemporalField): boolean source

Checks if the specified field is supported.

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

If the field is a ChronoField then the query is implemented here. The supported fields (see isSupported) will return valid values based on this date-time. The supported fields are:

  • YEAR_OF_ERA
  • YEAR
  • ERA

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:

NameTypeAttributeDescription
field TemporalField

the field to check, null returns false

Return:

boolean

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

public isSupportedUnit(unit: *): * source

Params:

NameTypeAttributeDescription
unit *

Return:

*

public isValidMonthDay(monthDay: MonthDay): boolean source

Checks if the month-day is valid for this year.

This method checks whether this year and the input month and day form a valid date.

Params:

NameTypeAttributeDescription
monthDay MonthDay

the month-day to validate, null returns false

Return:

boolean

true if the month and day are valid for this year

public length(): number source

Gets the length of this year in days.

Return:

number

the length of this year in days, 365 or 366

public minus(amountOrNumber: TemporalAmount | number, unit: TemporalUnit): Year source

function overloading for Year.minus

if called with 1 argument, then Year.minusAmount is executed.

Otherwise Year.minusAmountToSubtractUnit is executed.

Params:

NameTypeAttributeDescription
amountOrNumber TemporalAmount | number
  • nullable: false
unit TemporalUnit
  • nullable: true

Return:

Year

public minusAmount(amount: TemporalAmount): Year source

Returns a copy of this year with the specified period subtracted.

This method returns a new year based on this year with the specified period subtracted. The subtractor is typically Period but may be any other type implementing the TemporalAmount interface. The calculation is delegated to the specified adjuster, which typically calls back to minus.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
amount TemporalAmount

the amount to subtract, not null

Return:

Year

based on this year with the subtraction made, not null

Throw:

*

DateTimeException if the subtraction cannot be made

*

ArithmeticException if numeric overflow occurs

public minusAmountToSubtractUnit(amountToSubtract: number, unit: TemporalUnit): Year source

Params:

NameTypeAttributeDescription
amountToSubtract number

the amount to subtract, not null

unit TemporalUnit

Return:

Year

based on this year with the subtraction made, not null

Throw:

*

DateTimeException if the subtraction cannot be made

*

ArithmeticException if numeric overflow occurs

public minusYears(yearsToSubtract: number): Year source

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

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
yearsToSubtract number

the years to subtract, may be negative

Return:

Year

based on this year with the period subtracted, not null

Throw:

*

DateTimeException if the result exceeds the supported year range

public plus(amountOrNumber: TemporalAmount | number, unit: TemporalUnit): Year source

function overloading for Year.plus

if called with 1 arguments, then Year.plusAmount is executed.

Otherwise Year.plusAmountToAddUnit is executed.

Params:

NameTypeAttributeDescription
amountOrNumber TemporalAmount | number
  • nullable: false
unit TemporalUnit
  • nullable: true

nullable only if first argument is an instance of TemporalAmount

Return:

Year

public plusAmount(amount: TemporalAmount): Year source

Returns a copy of this year with the specified period added.

This method returns a new year based on this year with the specified period added. The adder is typically Period but may be any other type implementing the TemporalAmount interface. The calculation is delegated to the specified adjuster, which typically calls back to plus.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
amount TemporalAmount

the amount to add, not null

Return:

Year

based on this year with the addition made, not null

Throw:

*

DateTimeException if the addition cannot be made

*

ArithmeticException if numeric overflow occurs

public plusAmountToAddUnit(amountToAdd: number, unit: TemporalUnit): Year source

Params:

NameTypeAttributeDescription
amountToAdd number
unit TemporalUnit

Return:

Year

based on this year with the addition made, not null

Throw:

*

DateTimeException if the addition cannot be made

*

ArithmeticException if numeric overflow occurs

public plusYears(yearsToAdd: number): Year source

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

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
yearsToAdd number

the years to add, may be negative

Return:

Year

based on this year with the period added, not null

Throw:

*

DateTimeException if the result exceeds the supported year range

public query(query: TemporalQuery): * source

Queries this year using the specified query.

This queries this year 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.

Override:

TemporalAccessor#query

Params:

NameTypeAttributeDescription
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 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.

If the field is a ChronoField then the query is implemented here. The supported fields (see isSupported) will return appropriate range instances. All other ChronoField instances will throw a DateTimeException.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.rangeRefinedBy passing this as the argument. Whether the range can be obtained is determined by the field.

Override:

TemporalAccessor#range

Params:

NameTypeAttributeDescription
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

public toJSON(): string source

toJSON() use by JSON.stringify delegates to toString()

Return:

string

public toString(): String source

Outputs this year as a string.

Return:

String

a string representation of this year, not null

public value(): number source

Return:

number

gets the value

public with(adjusterOrFieldOrNumber: TemporalAdjuster | TemporalField | Number, value: number): Year source

function overloading for YearMonth.with

if called with 2 arguments and first argument is an instance of TemporalField, then Year.withFieldValue is executed,

otherwise Year.withAdjuster is executed,

Params:

NameTypeAttributeDescription
adjusterOrFieldOrNumber TemporalAdjuster | TemporalField | Number
  • nullable: false
value number
  • nullable: true

nullable only of first argument is an instance of TemporalAdjuster

Return:

Year

public withAdjuster(adjuster: TemporalAdjuster): Year source

Returns an adjusted copy of this year.

This returns a new Year, based on this one, with the year adjusted. The adjustment takes place using the specified adjuster strategy object. Read the documentation of the adjuster to understand what adjustment will be made.

The result of this method is obtained by invoking the TemporalAdjuster#adjustInto method on the specified adjuster passing this as the argument.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
adjuster TemporalAdjuster

the adjuster to use, not null

Return:

Year

based on this with the adjustment made, not null

Throw:

*

DateTimeException if the adjustment cannot be made

*

ArithmeticException if numeric overflow occurs

public withFieldValue(field: TemporalField, newValue: number): Year source

Returns a copy of this year with the specified field set to a new value.

This returns a new Year, based on this one, with the value for the specified field changed. If it is not possible to set the value, because the field is not supported or for some other reason, an exception is thrown.

If the field is a ChronoField then the adjustment is implemented here. The supported fields behave as follows:

  • YEAR_OF_ERA - Returns a Year with the specified year-of-era The era will be unchanged.
  • YEAR - Returns a Year with the specified year. This completely replaces the date and is equivalent to of.
  • ERA - Returns a Year with the specified era. The year-of-era will be unchanged.

In all cases, if the new value is outside the valid range of values for the field then a DateTimeException will be thrown.

All other ChronoField instances will throw a DateTimeException.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.adjustInto passing this as the argument. In this case, the field determines whether and how to adjust the instant.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
field TemporalField

the field to set in the result, not null

newValue number

the new value of the field in the result

Return:

Year

based on this with the specified field set, not null

Throw:

*

DateTimeException if the field cannot be set

*

ArithmeticException if numeric overflow occurs