C
- the chronology of the erapublic interface Era<C extends Chrono<C>> extends TemporalAccessor, TemporalAdjuster
Most calendar systems have a single epoch dividing the time-line into two eras.
However, some calendar systems, have multiple eras, such as one for the reign
of each leader.
In all cases, the era is conceptually the largest division of the time-line.
Each chronology defines the Era's that are known Eras and a
Chrono.eras
to get the valid eras.
For example, the Thai Buddhist calendar system divides time into two eras, before and after a single date. By contrast, the Japanese calendar system has one era for the reign of each Emperor.
Instances of Era
may be compared using the ==
operator.
Modifier and Type | Method and Description |
---|---|
default Temporal |
adjustInto(Temporal temporal)
Adjusts the specified temporal object to have the same era as this object.
|
default ChronoLocalDate<C> |
date(int yearOfEra,
int month,
int day)
Obtains a date in this era given the year-of-era, month, and day.
|
default ChronoLocalDate<C> |
dateYearDay(int yearOfEra,
int dayOfYear)
Obtains a date in this era given year-of-era and day-of-year fields.
|
default int |
get(TemporalField field)
Gets the value of the specified field from this era as an
int . |
C |
getChrono()
Gets the chronology of this era.
|
default long |
getLong(TemporalField field)
Gets the value of the specified field from this era as a
long . |
default java.lang.String |
getText(TextStyle style,
java.util.Locale locale)
Gets the textual representation of this era.
|
int |
getValue()
Gets the numeric value associated with the era as defined by the chronology.
|
default boolean |
isSupported(TemporalField field)
Checks if the specified field is supported.
|
default <R> R |
query(TemporalQuery<R> query)
Queries this era using the specified query.
|
default ValueRange |
range(TemporalField field)
Gets the range of valid values for the specified field.
|
int getValue()
All fields, including eras, have an associated numeric value. The meaning of the numeric value for era is determined by the chronology according to these principles:
C getChrono()
The Chrono
represents the calendar system in use.
This always returns the standard form of the chronology.
default ChronoLocalDate<C> date(int yearOfEra, int month, int day)
This era is combined with the given date fields to form a date.
The year specified must be the year-of-era.
Methods to create a date from the proleptic-year are on Chrono
.
This always uses the standard form of the chronology.
This default implementation invokes the factory method on Chrono
.
yearOfEra
- the calendar system year-of-eramonth
- the calendar system month-of-yearday
- the calendar system day-of-monthdefault ChronoLocalDate<C> dateYearDay(int yearOfEra, int dayOfYear)
This era is combined with the given date fields to form a date.
The year specified must be the year-of-era.
Methods to create a date from the proleptic-year are on Chrono
.
This always uses the standard form of the chronology.
This default implementation invokes the factory method on Chrono
.
yearOfEra
- the calendar system year-of-eradayOfYear
- the calendar system day-of-yeardefault boolean isSupported(TemporalField field)
This checks if this era can be queried for the specified field.
If false, then calling the range
and
get
methods will throw an exception.
If the field is a ChronoField
then the query is implemented here.
The ERA
field returns true.
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.doIsSupported(TemporalAccessor)
passing this
as the argument.
Whether the field is supported is determined by the field.
isSupported
in interface TemporalAccessor
field
- the field to check, null returns falsedefault ValueRange range(TemporalField field)
The range object expresses the minimum and maximum valid values for a field. This era 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 ERA
field returns the range.
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.doRange(TemporalAccessor)
passing this
as the argument.
Whether the range can be obtained is determined by the field.
range
in interface TemporalAccessor
field
- the field to query the range for, not nullDateTimeException
- if the range for the field cannot be obtaineddefault int get(TemporalField field)
int
.
This queries this era 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 ERA
field returns the value of the era.
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.doGet(TemporalAccessor)
passing this
as the argument. Whether the value can be obtained,
and what the value represents, is determined by the field.
get
in interface TemporalAccessor
field
- the field to get, not nullDateTimeException
- if a value for the field cannot be obtainedjava.lang.ArithmeticException
- if numeric overflow occursdefault long getLong(TemporalField field)
long
.
This queries this era 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 ERA
field returns the value of the era.
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.doGet(TemporalAccessor)
passing this
as the argument. Whether the value can be obtained,
and what the value represents, is determined by the field.
getLong
in interface TemporalAccessor
field
- the field to get, not nullDateTimeException
- if a value for the field cannot be obtainedjava.lang.ArithmeticException
- if numeric overflow occursdefault <R> R query(TemporalQuery<R> query)
This queries this era 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(TemporalAccessor)
method on the
specified query passing this
as the argument.
query
in interface TemporalAccessor
R
- the type of the resultquery
- the query to invoke, not nullDateTimeException
- if unable to query (defined by the query)java.lang.ArithmeticException
- if numeric overflow occurs (defined by the query)default Temporal adjustInto(Temporal temporal)
This returns a temporal object of the same observable type as the input with the era changed to be the same as this.
The adjustment is equivalent to using Temporal.with(TemporalField, long)
passing ChronoField.ERA
as the field.
In most cases, it is clearer to reverse the calling pattern by using
Temporal.with(TemporalAdjuster)
:
// these two lines are equivalent, but the second approach is recommended temporal = thisEra.adjustInto(temporal); temporal = temporal.with(thisEra);
This instance is immutable and unaffected by this method call.
adjustInto
in interface TemporalAdjuster
temporal
- the target object to be adjusted, not nullDateTimeException
- if unable to make the adjustmentjava.lang.ArithmeticException
- if numeric overflow occursdefault java.lang.String getText(TextStyle style, java.util.Locale locale)
This returns the textual name used to identify the era. The parameters control the style of the returned text and the locale.
If no textual mapping is found then the numeric value
is returned.
This default implementation is suitable for all implementations.
style
- the style of the text required, not nulllocale
- the locale to use, not null