108 * system, in which today's rules for leap years are applied for all time. |
108 * system, in which today's rules for leap years are applied for all time. |
109 * For most applications written today, the ISO-8601 rules are entirely suitable. |
109 * For most applications written today, the ISO-8601 rules are entirely suitable. |
110 * However, any application that makes use of historical dates, and requires them |
110 * However, any application that makes use of historical dates, and requires them |
111 * to be accurate will find the ISO-8601 approach unsuitable. |
111 * to be accurate will find the ISO-8601 approach unsuitable. |
112 * |
112 * |
113 * <h3>Specification for implementors</h3> |
113 * @implSpec |
114 * This class is immutable and thread-safe. |
114 * This class is immutable and thread-safe. |
115 * |
115 * |
116 * @since 1.8 |
116 * @since 1.8 |
117 */ |
117 */ |
118 public final class YearMonth |
118 public final class YearMonth |
942 } |
942 } |
943 return temporal.with(PROLEPTIC_MONTH, getProlepticMonth()); |
943 return temporal.with(PROLEPTIC_MONTH, getProlepticMonth()); |
944 } |
944 } |
945 |
945 |
946 /** |
946 /** |
947 * Calculates the period between this year-month and another year-month in |
947 * Calculates the amount of time until another year-month in terms of the specified unit. |
948 * terms of the specified unit. |
948 * <p> |
949 * <p> |
949 * This calculates the amount of time between two {@code YearMonth} |
950 * This calculates the period between two year-months in terms of a single unit. |
950 * objects in terms of a single {@code TemporalUnit}. |
951 * The start and end points are {@code this} and the specified year-month. |
951 * The start and end points are {@code this} and the specified year-month. |
952 * The result will be negative if the end is before the start. |
952 * The result will be negative if the end is before the start. |
953 * The {@code Temporal} passed to this method must be a {@code YearMonth}. |
953 * The {@code Temporal} passed to this method must be a {@code YearMonth}. |
954 * For example, the period in years between two year-months can be calculated |
954 * For example, the period in years between two year-months can be calculated |
955 * using {@code startYearMonth.periodUntil(endYearMonth, YEARS)}. |
955 * using {@code startYearMonth.periodUntil(endYearMonth, YEARS)}. |
980 * the second argument. |
980 * the second argument. |
981 * <p> |
981 * <p> |
982 * This instance is immutable and unaffected by this method call. |
982 * This instance is immutable and unaffected by this method call. |
983 * |
983 * |
984 * @param endYearMonth the end year-month, which must be a {@code YearMonth}, not null |
984 * @param endYearMonth the end year-month, which must be a {@code YearMonth}, not null |
985 * @param unit the unit to measure the period in, not null |
985 * @param unit the unit to measure the amount in, not null |
986 * @return the amount of the period between this year-month and the end year-month |
986 * @return the amount of time between this year-month and the end year-month |
987 * @throws DateTimeException if the period cannot be calculated |
987 * @throws DateTimeException if the amount cannot be calculated |
988 * @throws UnsupportedTemporalTypeException if the unit is not supported |
988 * @throws UnsupportedTemporalTypeException if the unit is not supported |
989 * @throws ArithmeticException if numeric overflow occurs |
989 * @throws ArithmeticException if numeric overflow occurs |
990 */ |
990 */ |
991 @Override |
991 @Override |
992 public long periodUntil(Temporal endYearMonth, TemporalUnit unit) { |
992 public long periodUntil(Temporal endYearMonth, TemporalUnit unit) { |
993 if (endYearMonth instanceof YearMonth == false) { |
993 if (endYearMonth instanceof YearMonth == false) { |
994 Objects.requireNonNull(endYearMonth, "endYearMonth"); |
994 Objects.requireNonNull(endYearMonth, "endYearMonth"); |
995 throw new DateTimeException("Unable to calculate period between objects of two different types"); |
995 throw new DateTimeException("Unable to calculate amount as objects are of two different types"); |
996 } |
996 } |
997 YearMonth end = (YearMonth) endYearMonth; |
997 YearMonth end = (YearMonth) endYearMonth; |
998 if (unit instanceof ChronoUnit) { |
998 if (unit instanceof ChronoUnit) { |
999 long monthsUntil = end.getProlepticMonth() - getProlepticMonth(); // no overflow |
999 long monthsUntil = end.getProlepticMonth() - getProlepticMonth(); // no overflow |
1000 switch ((ChronoUnit) unit) { |
1000 switch ((ChronoUnit) unit) { |