|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.time.calendar.Year
public final class Year
A year in the ISO-8601 calendar system, such as 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.
Field Summary | |
---|---|
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. |
Method Summary | ||
---|---|---|
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(java.lang.Object other)
Is this year equal to the specified year. |
|
|
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<java.lang.Integer> |
rule()
Gets the rule that defines how the year field operates. |
|
java.lang.String |
toString()
Outputs the string form of the year. |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final int MIN_YEAR
public static final int MAX_YEAR
Method Detail |
---|
public static DateTimeFieldRule<java.lang.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 null
public 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_YEAR
IllegalCalendarFieldValueException
- 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 null
UnsupportedRuleException
- 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 null
public 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 null
Year
based on this year with the period added, never null
CalendricalException
- if the specified period cannot be converted to a Period
java.lang.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 add
Year
based on this year with the period added, never null
CalendricalException
- 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 null
Year
based on this year with the period subtracted, never null
CalendricalException
- if the specified period cannot be converted to a Period
java.lang.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 subtract
Year
based on this year with the period subtracted, never null
CalendricalException
- 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 null
public 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 null
public 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 null
IllegalCalendarFieldValueException
- 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 false
public 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 null
public 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 null
InvalidCalendarFieldException
- 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 null
InvalidCalendarFieldException
- if the day of year is 366 and this is not a leap yearpublic int compareTo(Year other)
compareTo
in interface java.lang.Comparable<Year>
other
- the other year to compare to, not null
java.lang.NullPointerException
- if other
is nullpublic boolean isAfter(Year other)
other
- the other year to compare to, not null
java.lang.NullPointerException
- if other
is nullpublic boolean isBefore(Year other)
other
- the other year to compare to, not null
java.lang.NullPointerException
- if other
is nullpublic boolean equals(java.lang.Object other)
equals
in class java.lang.Object
other
- the other year to compare to, null returns false
public int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |