src/share/classes/java/time/Year.java
Print this page
@@ -62,10 +62,14 @@
package java.time;
import static java.time.temporal.ChronoField.ERA;
import static java.time.temporal.ChronoField.YEAR;
import static java.time.temporal.ChronoField.YEAR_OF_ERA;
+import static java.time.temporal.ChronoUnit.CENTURIES;
+import static java.time.temporal.ChronoUnit.DECADES;
+import static java.time.temporal.ChronoUnit.ERAS;
+import static java.time.temporal.ChronoUnit.MILLENNIA;
import static java.time.temporal.ChronoUnit.YEARS;
import java.io.DataInput;
import java.io.DataOutput;
import java.io.IOException;
@@ -327,12 +331,13 @@
//-----------------------------------------------------------------------
/**
* Checks if the specified field is supported.
* <p>
* This checks if this year can be queried for the specified field.
- * If false, then calling the {@link #range(TemporalField) range} and
- * {@link #get(TemporalField) get} methods will throw an exception.
+ * If false, then calling the {@link #range(TemporalField) range},
+ * {@link #get(TemporalField) get} and {@link #with(TemporalField, long)}
+ * methods will throw an exception.
* <p>
* If the field is a {@link ChronoField} then the query is implemented here.
* The supported fields are:
* <ul>
* <li>{@code YEAR_OF_ERA}
@@ -356,10 +361,45 @@
}
return field != null && field.isSupportedBy(this);
}
/**
+ * Checks if the specified unit is supported.
+ * <p>
+ * This checks if the specified unit can be added to, or subtracted from, this date-time.
+ * If false, then calling the {@link #plus(long, TemporalUnit)} and
+ * {@link #minus(long, TemporalUnit) minus} methods will throw an exception.
+ * <p>
+ * If the unit is a {@link ChronoUnit} then the query is implemented here.
+ * The supported units are:
+ * <ul>
+ * <li>{@code YEARS}
+ * <li>{@code DECADES}
+ * <li>{@code CENTURIES}
+ * <li>{@code MILLENNIA}
+ * <li>{@code ERAS}
+ * </ul>
+ * All other {@code ChronoUnit} instances will return false.
+ * <p>
+ * If the unit is not a {@code ChronoUnit}, then the result of this method
+ * is obtained by invoking {@code TemporalUnit.isSupportedBy(Temporal)}
+ * passing {@code this} as the argument.
+ * Whether the unit is supported is determined by the unit.
+ *
+ * @param unit the unit to check, null returns false
+ * @return true if the unit can be added/subtracted, false if not
+ */
+ @Override
+ public boolean isSupported(TemporalUnit unit) {
+ if (unit instanceof ChronoUnit) {
+ return unit == YEARS || unit == DECADES || unit == CENTURIES || unit == MILLENNIA || unit == ERAS;
+ }
+ return unit != null && unit.isSupportedBy(this);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
* Gets the range of valid values for the specified field.
* <p>
* 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
@@ -448,11 +488,11 @@
switch ((ChronoField) field) {
case YEAR_OF_ERA: return (year < 1 ? 1 - year : year);
case YEAR: return year;
case ERA: return (year < 1 ? 0 : 1);
}
- throw new UnsupportedTemporalTypeException("Unsupported field: " + field.getName());
+ throw new UnsupportedTemporalTypeException("Unsupported field: " + field);
}
return field.getFrom(this);
}
//-----------------------------------------------------------------------
@@ -573,11 +613,11 @@
switch (f) {
case YEAR_OF_ERA: return Year.of((int) (year < 1 ? 1 - newValue : newValue));
case YEAR: return Year.of((int) newValue);
case ERA: return (getLong(ERA) == newValue ? this : Year.of(1 - year));
}
- throw new UnsupportedTemporalTypeException("Unsupported field: " + field.getName());
+ throw new UnsupportedTemporalTypeException("Unsupported field: " + field);
}
return field.adjustInto(this, newValue);
}
//-----------------------------------------------------------------------
@@ -662,11 +702,11 @@
case DECADES: return plusYears(Math.multiplyExact(amountToAdd, 10));
case CENTURIES: return plusYears(Math.multiplyExact(amountToAdd, 100));
case MILLENNIA: return plusYears(Math.multiplyExact(amountToAdd, 1000));
case ERAS: return with(ERA, Math.addExact(getLong(ERA), amountToAdd));
}
- throw new UnsupportedTemporalTypeException("Unsupported unit: " + unit.getName());
+ throw new UnsupportedTemporalTypeException("Unsupported unit: " + unit);
}
return unit.addTo(this, amountToAdd);
}
/**
@@ -819,11 +859,11 @@
* objects in terms of a single {@code TemporalUnit}.
* The start and end points are {@code this} and the specified year.
* The result will be negative if the end is before the start.
* The {@code Temporal} passed to this method must be a {@code Year}.
* For example, the period in decades between two year can be calculated
- * using {@code startYear.periodUntil(endYear, DECADES)}.
+ * using {@code startYear.until(endYear, DECADES)}.
* <p>
* The calculation returns a whole number, representing the number of
* complete units between the two years.
* For example, the period in decades between 2012 and 2031
* will only be one decade as it is one year short of two decades.
@@ -831,11 +871,11 @@
* There are two equivalent ways of using this method.
* The first is to invoke this method.
* The second is to use {@link TemporalUnit#between(Temporal, Temporal)}:
* <pre>
* // these two lines are equivalent
- * amount = start.periodUntil(end, YEARS);
+ * amount = start.until(end, YEARS);
* amount = YEARS.between(start, end);
* </pre>
* The choice should be made based on which makes the code more readable.
* <p>
* The calculation is implemented in this method for {@link ChronoUnit}.
@@ -856,11 +896,11 @@
* @throws DateTimeException if the amount cannot be calculated
* @throws UnsupportedTemporalTypeException if the unit is not supported
* @throws ArithmeticException if numeric overflow occurs
*/
@Override
- public long periodUntil(Temporal endYear, TemporalUnit unit) {
+ public long until(Temporal endYear, TemporalUnit unit) {
if (endYear instanceof Year == false) {
Objects.requireNonNull(endYear, "endYear");
throw new DateTimeException("Unable to calculate amount as objects are of two different types");
}
Year end = (Year) endYear;
@@ -871,11 +911,11 @@
case DECADES: return yearsUntil / 10;
case CENTURIES: return yearsUntil / 100;
case MILLENNIA: return yearsUntil / 1000;
case ERAS: return end.getLong(ERA) - getLong(ERA);
}
- throw new UnsupportedTemporalTypeException("Unsupported unit: " + unit.getName());
+ throw new UnsupportedTemporalTypeException("Unsupported unit: " + unit);
}
return unit.between(this, endYear);
}
/**