Home Reference Source
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

isLeap(year: number): boolean

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

parseText(text: String): Year

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

public static

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

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

atMonthNumber(month: number): YearMonth

Combines this year with a month to create a YearMonth.

public

compareTo(other: Year): number

Compares this year to another year.

public

equals(other: *): boolean

Checks if this year is equal to the specified Year.

public

format(formatter: DateTimeFormatter): String

Outputs this year as a string using the formatter.

public

get(field: TemporalField): number

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

public

getLong(field: TemporalField): number

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

isLeap(): boolean

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

public

isSupported(fieldOrUnit: TemporalField | ChronoUnit): boolean

function overloading for YearMonth.isSupported

public

isSupportedField(field: TemporalField): boolean

Checks if the specified field is supported.

public

isSupportedUnit(unit: *): *

public

isValidMonthDay(monthDay: MonthDay): boolean

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

public

length(): number

Gets the length of this year in days.

public

minusYears(yearsToSubtract: number): Year

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

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(): string

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

public

toString(): String

Outputs this year as a string.

public

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

Calculates the amount of time until another temporal in terms of the specified unit.

public

value(): number

Inherited Summary

From class TemporalAccessor
public

get(field: TemporalField): number

Gets the value of the specified field as an int.

public

getLong(field: *)

public

isSupported(field: *)

public

query(query: TemporalQuery): *

Queries this date-time.

public

Gets the range of valid values for the specified field.

From class Temporal
public

isSupported(fieldOrUnit: TemporalUnit): boolean

Checks if the specified unit is supported.

public

minus(amount: TemporalAmount | number, unit: TemporalUnit): Temporal

function overloading for Temporal.plus

public

plus(amount: TemporalAmount | number, unit: TemporalUnit): Temporal

function overloading for Temporal.plus

public

until(endTemporal: Temporal, unit: TemporalUnit): number

Calculates the period between this temporal and another temporal in terms of the specified unit.

public

with(adjusterOrField: TemporalAdjuster | TemporalField, newValue: number): Temporal

function overloading for Temporal.with

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(other: *): boolean source

Checks if this year is equal to the specified Year.

The comparison is based on the value

Params:

NameTypeAttributeDescription
other *

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.

Override:

TemporalAccessor#getLong

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

Override:

Temporal#isSupported

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 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 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 until(endExclusive: Temporal, unit: TemporalUnit): number source

Calculates the amount of time until another temporal in terms of the specified unit. This calculates the amount of time between two temporal objects in terms of a single TemporalUnit. The start and end points are this and the specified temporal. The end point is converted to be of the same type as the start point if different. The result will be negative if the end is before the start. For example, the amount in hours between two temporal objects can be calculated using startTime.until(endTime, HOURS).

The calculation returns a whole number, representing the number of complete units between the two temporals. For example, the amount in hours between the times 11:30 and 13:29 will only be one hour as it is one minute short of two hours.

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

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

The choice should be made based on which makes the code more readable. For example, this method allows the number of days between two dates to be calculated:

  daysBetween = start.until(end, DAYS);
  // or alternatively
  daysBetween = DAYS.between(start, end);

Implementation Requirements:

Implementations must begin by checking to ensure that the input temporal object is of the same observable type as the implementation. They must then perform the calculation for all instances of ChronoUnit. An UnsupportedTemporalTypeException must be thrown for ChronoUnit instances that are unsupported. If the unit is not a ChronoUnit, then the result of this method is obtained by invoking TemporalUnit.between(Temporal, Temporal) passing this as the first argument and the converted input temporal as the second argument.

In summary, implementations must behave in a manner equivalent to this pseudo-code:

  // convert the end temporal to the same type as this class
  if (unit instanceof ChronoUnit) {
    // if unit is supported, then calculate and return result
    // else throw UnsupportedTemporalTypeException for unsupported units
  }
  return unit.between(this, convertedEndTemporal);

Note that the unit's between method must only be invoked if the two temporal objects have exactly the same type evaluated by getClass().

Implementations must ensure that no observable state is altered when this read-only method is invoked.

Override:

Temporal#until

Params:

NameTypeAttributeDescription
endExclusive Temporal

the end temporal, exclusive, converted to be of the same type as this object, not null

unit TemporalUnit

the unit to measure the amount in, not null

Return:

number

the amount of time between this temporal object and the specified one in terms of the unit; positive if the specified object is later than this one, negative if it is earlier than this one

Throw:

*

DateTimeException - if the amount cannot be calculated, or the end temporal cannot be converted to the same type as this temporal

*

UnsupportedTemporalTypeException - if the unit is not supported

*

ArithmeticException - if numeric overflow occurs

public value(): number source

Return:

number

gets the value