Year
Extends:
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 |
function overloading for Year.now |
|
public static |
Obtains the current year from the system clock in the default time-zone. |
|
public static |
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 |
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 |
|
public static |
parseTextFormatter(text: String, formatter: DateTimeFormatter): Year Obtains an instance of Year from a text string using a specific formatter. |
Constructor Summary
Public Constructor | ||
public |
constructor(value: number) |
Method Summary
Public Methods | ||
public |
adjustInto(temporal: Temporal): Temporal Adjusts the specified temporal object to have this year. |
|
public |
Combines this year with a day-of-year to create a LocalDate. |
|
public |
function overloading for Year.atMonth |
|
public |
atMonthDay(monthDay: MonthDay): LocalDate Combines this year with a month-day to create a LocalDate. |
|
public |
atMonthMonth(month: Month): YearMonth 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 |
Compares this year to another year. |
|
public |
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 |
|
public |
getLong(field: TemporalField): number Gets the value of the specified field from this year as a |
|
public |
Is this year after the specified year. |
|
public |
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 |
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 |
Gets the length of this year in days. |
|
public |
minus(amountOrNumber: TemporalAmount | number, unit: TemporalUnit): Year function overloading for Year.minus |
|
public |
minusAmount(amount: TemporalAmount): Year 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 |
plusAmount(amount: TemporalAmount): Year Returns a copy of this year with the specified period added. |
|
public |
plusAmountToAddUnit(amountToAdd: number, unit: TemporalUnit): Year |
|
public |
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 |
range(field: TemporalField): ValueRange Gets the range of valid values for the specified field. |
|
public |
Outputs this year as a string. |
|
public |
|
|
public |
with(adjusterOrFieldOrNumber: TemporalAdjuster | TemporalField | Number, value: number): Year function overloading for YearMonth.with |
|
public |
withAdjuster(adjuster: TemporalAdjuster): Year 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 |
get(field: TemporalField): number Gets the value of the specified field as an |
|
public |
query(query: TemporalQuery): * Queries this date-time. |
|
public |
range(field: TemporalField): ValueRange 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:
Name | Type | Attribute | Description |
temporal | TemporalAccessor | the temporal object to convert, 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:
Name | Type | Attribute | Description |
year | number | the year to check |
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.
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.
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:
Name | Type | Attribute | Description |
clock | Clock | the clock to use, 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:
Name | Type | Attribute | Description |
zone | ZoneId | the zone ID to use, 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:
Name | Type | Attribute | Description |
isoYear | Number | the ISO proleptic year to represent, from MIN_VALUE to MAX_VALUE |
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:
Name | Type | Attribute | Description |
text | String |
|
|
formatter | DateTimeFormatter |
|
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:
Name | Type | Attribute | Description |
text | String | the text to parse such as "2007", 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:
Name | Type | Attribute | Description |
text | String | the text to parse, not null |
|
formatter | DateTimeFormatter | the formatter to use, not null |
Throw:
* |
DateTimeParseException if the text cannot be parsed |
Public Constructors
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:
Name | Type | Attribute | Description |
temporal | Temporal | the target object to be adjusted, 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:
Name | Type | Attribute | Description |
dayOfYear | number | the day-of-year to use, 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.
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:
Name | Type | Attribute | Description |
monthDay | MonthDay | the month-day to use, 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:
Name | Type | Attribute | Description |
month | Month | the month-of-year to use, 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:
Name | Type | Attribute | Description |
month | number | the month-of-year to use, from 1 (January) to 12 (December) |
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:
Name | Type | Attribute | Description |
other | Year | the other year to compare to, not null |
public equals(otherYear: *): boolean source
Checks if this year is equal to the specified Year.
The comparison is based on the value
Params:
Name | Type | Attribute | Description |
otherYear | * | the other year, null returns false |
public format(formatter: DateTimeFormatter): String source
Outputs this year as a string using the formatter.
Params:
Name | Type | Attribute | Description |
formatter | DateTimeFormatter | the formatter to use, 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#getParams:
Name | Type | Attribute | Description |
field | TemporalField | the field to get, not null |
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:
Name | Type | Attribute | Description |
field | TemporalField | the field to get, not null |
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:
Name | Type | Attribute | Description |
other | Year | the other year to compare to, not null |
public isBefore(other: Year): boolean source
Is this year before the specified year.
Params:
Name | Type | Attribute | Description |
other | Year | the other year to compare to, not null |
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.
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:
Name | Type | Attribute | Description |
fieldOrUnit | TemporalField | ChronoUnit |
|
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:
Name | Type | Attribute | Description |
field | TemporalField | the field to check, null returns false |
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:
Name | Type | Attribute | Description |
monthDay | MonthDay | the month-day to validate, null returns false |
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:
Name | Type | Attribute | Description |
amountOrNumber | TemporalAmount | number |
|
|
unit | TemporalUnit |
|
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:
Name | Type | Attribute | Description |
amount | TemporalAmount | the amount to subtract, not null |
Throw:
* |
DateTimeException if the subtraction cannot be made |
* |
ArithmeticException if numeric overflow occurs |
public minusAmountToSubtractUnit(amountToSubtract: number, unit: TemporalUnit): Year source
Params:
Name | Type | Attribute | Description |
amountToSubtract | number | the amount to subtract, not null |
|
unit | TemporalUnit |
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:
Name | Type | Attribute | Description |
yearsToSubtract | number | the years to subtract, may be negative |
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:
Name | Type | Attribute | Description |
amountOrNumber | TemporalAmount | number |
|
|
unit | TemporalUnit |
|
nullable only if first argument is an instance of TemporalAmount |
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:
Name | Type | Attribute | Description |
amount | TemporalAmount | the amount to add, not null |
Throw:
* |
DateTimeException if the addition cannot be made |
* |
ArithmeticException if numeric overflow occurs |
public plusAmountToAddUnit(amountToAdd: number, unit: TemporalUnit): Year source
Params:
Name | Type | Attribute | Description |
amountToAdd | number | ||
unit | TemporalUnit |
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:
Name | Type | Attribute | Description |
yearsToAdd | number | the years to add, may be negative |
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#queryParams:
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 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#rangeParams:
Name | Type | Attribute | Description |
field | TemporalField | the field to query the range for, not null |
Throw:
* |
DateTimeException if the range for the field cannot be obtained |
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:
Name | Type | Attribute | Description |
adjusterOrFieldOrNumber | TemporalAdjuster | TemporalField | Number |
|
|
value | number |
|
nullable only of first argument is an instance of TemporalAdjuster |
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:
Name | Type | Attribute | Description |
adjuster | TemporalAdjuster | the adjuster to use, 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:
Name | Type | Attribute | Description |
field | TemporalField | the field to set in the result, not null |
|
newValue | number | the new value of the field in the result |
Throw:
* |
DateTimeException if the field cannot be set |
* |
ArithmeticException if numeric overflow occurs |