public final class Year extends Object implements Calendrical, Comparable<Year>, Serializable, DateAdjuster, CalendricalMatcher
2007
.
Year
is an immutable calendrical 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.
Thus, 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 todays's rules for leap years are applied for all time.
For most applications written today, the ISO-8601 rules are entirely suitable.
Any application that uses historical dates should consider using HistoricDate
.
Year is immutable and thread-safe.
Modifier and Type | Field and Description |
---|---|
static int |
MAX_YEAR
Constant for the maximum year on the proleptic ISO calendar system, 999,999,999.
|
static int |
MIN_YEAR
Constant for the minimum year on the proleptic ISO calendar system, -999,999,999.
|
Modifier and Type | Method and Description |
---|---|
LocalDate |
adjustDate(LocalDate date)
Adjusts a date to have the value of this year, returning a new date.
|
LocalDate |
adjustDate(LocalDate date,
DateResolver resolver)
Adjusts a date to have the value of this year, using a resolver to
handle the case when the day-of-month becomes invalid.
|
LocalDate |
atDay(int dayOfYear)
Returns a date formed from this year at the specified day-of-year.
|
YearMonth |
atMonth(int monthOfYear)
Returns a year-month formed from this year at the specified month.
|
YearMonth |
atMonth(MonthOfYear monthOfYear)
Returns a year-month formed from this year at the specified month.
|
LocalDate |
atMonthDay(MonthDay monthDay)
Returns a date formed from this year at the specified month-day.
|
int |
compareTo(Year other)
Compares this year to another year.
|
boolean |
equals(Object other)
Is this year equal to the specified year.
|
<T> T |
get(CalendricalRule<T> rule)
Gets the value of the specified calendrical rule.
|
int |
getValue()
Gets the year value.
|
int |
hashCode()
A hash code for this year.
|
boolean |
isAfter(Year other)
Is this year after the specified year.
|
boolean |
isBefore(Year other)
Is this year before the specified year.
|
boolean |
isLeap()
Checks if the year is a leap year, according to the ISO proleptic
calendar system rules.
|
boolean |
isValidMonthDay(MonthDay monthDay)
Checks if the month-day is valid for this year.
|
int |
lengthInDays()
Gets the length of this year in days.
|
boolean |
matchesCalendrical(Calendrical calendrical)
Checks if the year extracted from the calendrical matches this.
|
Year |
minus(PeriodProvider periodProvider)
Returns a copy of this
Year with the specified period subtracted. |
Year |
minusYears(long years)
Returns a copy of this Year with the specified number of years subtracted.
|
Year |
next()
Returns the next year.
|
Year |
nextLeap()
Returns the next leap year after the current year.
|
static Year |
now()
Obtains the current year from the system clock in the default time-zone.
|
static Year |
now(Clock clock)
Obtains the current year from the specified clock.
|
static Year |
of(Calendrical calendrical)
Obtains an instance of
Year from a calendrical. |
static Year |
of(int isoYear)
Obtains an instance of
Year . |
Year |
plus(PeriodProvider periodProvider)
Returns a copy of this
Year with the specified period added. |
Year |
plusYears(long years)
Returns a copy of this Year with the specified number of years added.
|
Year |
previous()
Returns the previous year.
|
Year |
previousLeap()
Returns the previous leap year before the current year.
|
static DateTimeFieldRule<Integer> |
rule()
Gets the rule that defines how the year field operates.
|
String |
toString()
Outputs the string form of the year.
|
public static final int MIN_YEAR
public static final int MAX_YEAR
public static DateTimeFieldRule<Integer> rule()
The rule provides access to the minimum and maximum values, and a generic way to access values within a calendrical.
public static Year now()
This will query the 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 Year now(Clock 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
.
clock
- the clock to use, not nullpublic static Year of(int isoYear)
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.
isoYear
- the ISO proleptic year to represent, from MIN_YEAR to MAX_YEARIllegalCalendarFieldValueException
- if the field is invalidpublic static Year of(Calendrical calendrical)
Year
from a calendrical.
This can be used extract the year value directly from any implementation
of Calendrical
, including those in other calendar systems.
calendrical
- the calendrical to extract from, not nullUnsupportedRuleException
- if the year cannot be obtainedpublic int getValue()
public <T> T get(CalendricalRule<T> rule)
This method queries the value of the specified calendrical rule.
If the value cannot be returned for the rule from this instance then
null
will be returned.
get
in interface Calendrical
rule
- the rule to use, not nullpublic boolean isLeap()
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 ISO8601 standard.
public Year next()
CalendricalException
- if the maximum year is reachedpublic Year nextLeap()
isLeap()
.CalendricalException
- if the maximum year is reachedpublic Year previous()
CalendricalException
- if the maximum year is reachedpublic Year previousLeap()
isLeap()
.CalendricalException
- if the minimum year is reachedpublic Year plus(PeriodProvider periodProvider)
Year
with the specified period added.
This adds the specified period to this year, returning a new year.
Before addition, the period is converted to a Period
using
Period.of(PeriodProvider)
.
The calculation simply adds the amount of years from the specified period.
ISO fields other than years are ignored.
Note that no normalization is performed. Thus, adding 24 months has no effect. To take months into account, the period must be normalized by the caller.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to add, not nullYear
based on this year with the period added, never nullCalendricalException
- if the specified period cannot be converted to a Period
ArithmeticException
- if the result exceeds the supported year rangepublic Year plusYears(long years)
This instance is immutable and unaffected by this method call.
years
- the years to addYear
based on this year with the period added, never nullCalendricalException
- if the result exceeds the supported year rangepublic Year minus(PeriodProvider periodProvider)
Year
with the specified period subtracted.
This subtracts the specified period from this year, returning a new year.
Before subtraction, the period is converted to a Period
using
Period.of(PeriodProvider)
.
The calculation simply adds the amount of years from the specified period.
ISO fields other than years are ignored.
Note that no normalization is performed. Thus, subtracting 24 months has no effect. To take months into account, the period must be normalized by the caller.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to subtract, not nullYear
based on this year with the period subtracted, never nullCalendricalException
- if the specified period cannot be converted to a Period
ArithmeticException
- if the result exceeds the supported year rangepublic Year minusYears(long years)
This instance is immutable and unaffected by this method call.
years
- the years to subtractYear
based on this year with the period subtracted, never nullCalendricalException
- if the result exceeds the supported year rangepublic boolean matchesCalendrical(Calendrical calendrical)
This method implements the CalendricalMatcher
interface.
It is intended that applications use LocalDate.matches(javax.time.calendar.CalendricalMatcher)
rather than this method.
matchesCalendrical
in interface CalendricalMatcher
calendrical
- the calendrical to match, not nullpublic LocalDate adjustDate(LocalDate date)
This method implements the DateAdjuster
interface.
It is intended that, instead of calling this method directly, it is used from
an instance of LocalDate
:
date = date.with(year);
This implementation handles the case where the date represents February 29 and
this is not a leap year using the DateResolvers.previousValid()
resolver.
This instance is immutable and unaffected by this method call.
adjustDate
in interface DateAdjuster
date
- the date to be adjusted, not nullpublic LocalDate adjustDate(LocalDate date, DateResolver resolver)
This instance is immutable and unaffected by this method call.
date
- the date to be adjusted, not nullresolver
- the date resolver to use if the day-of-month becomes invalid, not nullIllegalCalendarFieldValueException
- if the date cannot be resolved using the resolverpublic int lengthInDays()
public boolean isValidMonthDay(MonthDay monthDay)
This method checks whether this year and the input month and day form a valid date.
monthDay
- the month-day to validate, null returns falsepublic YearMonth atMonth(MonthOfYear monthOfYear)
This method merges this
and the specified month to form an
instance of YearMonth
.
This method can be used as part of a chain to produce a date:
LocalDate date = year.atMonth(month).atDay(day);
This instance is immutable and unaffected by this method call.
monthOfYear
- the month-of-year to use, not nullpublic YearMonth atMonth(int monthOfYear)
This method merges this
and the specified month to form an
instance of YearMonth
.
This method can be used as part of a chain to produce a date:
LocalDate date = year.atMonth(month).atDay(day);
This instance is immutable and unaffected by this method call.
monthOfYear
- the month-of-year to use, from 1 (January) to 12 (December)public LocalDate atMonthDay(MonthDay monthDay)
This merges the two objects - this
and the specified day -
to form an instance of LocalDate
.
LocalDate date = year.atMonthDay(monthDay);
This instance is immutable and unaffected by this method call.
monthDay
- the month-day to use, not nullInvalidCalendarFieldException
- if the month-day is February 29th and this is not a leap yearpublic LocalDate atDay(int dayOfYear)
This merges the two objects - this
and the specified day -
to form an instance of LocalDate
.
LocalDate date = year.atDay(dayOfYear);
This instance is immutable and unaffected by this method call.
dayOfYear
- the day-of-year to use, not nullInvalidCalendarFieldException
- if the day of year is 366 and this is not a leap yearpublic int compareTo(Year other)
compareTo
in interface Comparable<Year>
other
- the other year to compare to, not nullNullPointerException
- if other
is nullpublic boolean isAfter(Year other)
other
- the other year to compare to, not nullNullPointerException
- if other
is nullpublic boolean isBefore(Year other)
other
- the other year to compare to, not nullNullPointerException
- if other
is nullpublic boolean equals(Object other)
public int hashCode()
Copyright © 2014. All rights reserved.