Year
Extends:
A year in the ISO-8601 calendar system, such as {@code 2007}.
{@code Year} is an immutable date-time object that represents a year. Any field that can be derived from a year can be obtained.
<b>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.</b>
This class does not store or represent a month, day, time or time-zone. For example, the value "2007" can be stored in a {@code 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 {@code 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 {@code Year}. |
|
| public static |
parse(text: String, formatter: DateTimeFormatter): Year function overloading for Year.parse |
|
| public static |
Obtains an instance of {@code Year} from a text string such as {@code 2007}. |
|
| public static |
parseTextFormatter(text: String, formatter: DateTimeFormatter): Year Obtains an instance of {@code 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 {@code LocalDate}. |
|
| public |
atMonth(unit: TemporalUnit): YearMonth function overloading for Year.atMonth |
|
| public |
atMonthDay(monthDay: MonthDay): LocalDate Combines this year with a month-day to create a {@code LocalDate}. |
|
| public |
atMonthMonth(month: Month): YearMonth Combines this year with a month to create a {@code YearMonth}. |
|
| public |
atMonthNumber(month: number): YearMonth Combines this year with a month to create a {@code 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 {@code String} using the formatter. |
|
| public |
get(field: TemporalField): number Gets the value of the specified field from this year as an {@code int}. |
|
| public |
getLong(field: TemporalField): number Gets the value of the specified field from this year as a {@code long}. |
|
| 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 |
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(amount: 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(amount: 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 {@code String}. |
|
| public |
|
|
Inherited Summary
| From class TemporalAccessor | ||
| public |
get(field: TemporalField): number Gets the value of the specified field as an {@code int}. |
|
| 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 {@code Year} from a temporal object.
A {@code TemporalAccessor} represents some form of date and time information. This factory converts the arbitrary temporal object to an instance of {@code Year}.
The conversion extracts the {@link ChronoField#YEAR year} field. The extraction is only permitted if the temporal object has an ISO chronology, or can be converted to a {@code LocalDate}.
This method matches the signature of the functional interface TemporalQuery allowing it to be used in queries via method reference, {@code Year::from}.
Params:
| Name | Type | Attribute | Description |
| temporal | TemporalAccessor | the temporal object to convert, not null |
Throw:
* |
DateTimeException if unable to convert to a {@code 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(arg1: ZoneId | Clock | null): 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 {@link Clock#systemDefaultZone() system clock} 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 {@link Clock 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 {@link Clock#system(ZoneId) system clock} 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 {@code 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 {@code MIN_VALUE} to {@code 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 {@code Year} from a text string such as {@code 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 {@code 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 {@link Temporal#with(TemporalField, long)} passing ChronoField#YEAR as the field. If the specified temporal object does not use the ISO calendar system then a {@code DateTimeException} is thrown.
In most cases, it is clearer to reverse the calling pattern by using {@link Temporal#with(TemporalAdjuster)}:
// 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 {@code LocalDate}.
This returns a {@code 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(unit: TemporalUnit): 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:
| Name | Type | Attribute | Description |
| unit | TemporalUnit |
public atMonthDay(monthDay: MonthDay): LocalDate source
Combines this year with a month-day to create a {@code LocalDate}.
This returns a {@code 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 {@code YearMonth}.
This returns a {@code 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 {@code YearMonth}.
This returns a {@code 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 {@code String} using the formatter.
This year will be passed to the formatter {@link DateTimeFormatter#format(TemporalAccessor) print method}.
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 {@code 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 {@link #isSupported(TemporalField) supported fields} will return valid values based on this year. All other {@code ChronoField} instances will throw a {@code DateTimeException}.
If the field is not a {@code ChronoField}, then the result of this method is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)} passing {@code 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 {@code 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 {@link #isSupported(TemporalField) supported fields} will return valid values based on this year. All other {@code ChronoField} instances will throw a {@code DateTimeException}.
If the field is not a {@code ChronoField}, then the result of this method is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)} passing {@code 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 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(amount: 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 |
| amount | 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 {@link #minus(long, TemporalUnit)}.
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 {@inheritDoc} |
* |
ArithmeticException {@inheritDoc} |
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(amount: 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 |
| amount | TemporalAmount | number |
|
|
| unit | TemporalUnit |
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 {@link #plus(long, TemporalUnit)}.
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 {@code 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 {@link TemporalQuery#queryFrom(TemporalAccessor)} method on the specified query passing {@code 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 {@link #isSupported(TemporalField) supported fields} will return appropriate range instances. All other {@code ChronoField} instances will throw a {@code DateTimeException}.
If the field is not a {@code ChronoField}, then the result of this method is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessor)} passing {@code 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 |