packages/core/src/temporal/TemporalField.js
import { abstractMethodFail } from '../assert';
/**
* @copyright (c) 2016, Philipp Thürwächter & Pattrick Hüper
* @copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos
* @license BSD-3-Clause (see LICENSE in the root directory of this source tree)
*/
/**
* A field of date-time, such as month-of-year or hour-of-minute.
*
* Date and time is expressed using fields which partition the time-line into something
* meaningful for humans. Implementations of this interface represent those fields.
*
* The most commonly used units are defined in {@link ChronoField}.
* Further fields are supplied in {@link IsoFields}, {@link WeekFields} and {@link JulianFields}.
* Fields can also be written by application code by implementing this interface.
*
* The field works using double dispatch. Client code calls methods on a date-time like
* {@link LocalDateTime} which check if the field is a {@link ChronoField}.
* If it is, then the date-time must handle it.
* Otherwise, the method call is re-dispatched to the matching method in this interface.
*
* @interface
*/
export class TemporalField {
/**
* Checks if this field represents a component of a date.
*
* @return {boolean} `true` if it is a component of a date, `false` otherwise.
*/
isDateBased() {
abstractMethodFail('isDateBased');
}
/**
* Checks if this field represents a component of a time.
*
* @return {boolean} `true` if it is a component of a time, `false` otherwise.
*/
isTimeBased() {
abstractMethodFail('isTimeBased');
}
/**
* Gets the unit that the field is measured in.
*
* The unit of the field is the period that varies within the range.
* For example, in the field 'MonthOfYear', the unit is 'Months'.
* See also {@link rangeUnit}.
*
* @return {TemporalUnit} the period unit defining the base unit of the field.
*/
baseUnit() {
abstractMethodFail('baseUnit');
}
/**
* Gets the range that the field is bound by.
*
* The range of the field is the period that the field varies within.
* For example, in the field 'MonthOfYear', the range is 'Years'.
* See also {@link baseUnit}.
*
* The range is never null. For example, the 'Year' field is shorthand for
* 'YearOfForever'. It therefore has a unit of 'Years' and a range of 'Forever'.
*
* @return {TemporalUnit} the period unit defining the range of the field.
*/
rangeUnit() {
abstractMethodFail('rangeUnit');
}
/**
* Gets the range of valid values for the field.
*
* All fields can be expressed as an integer.
* This method returns an object that describes the valid range for that value.
* This method is generally only applicable to the ISO-8601 calendar system.
*
* Note that the result only describes the minimum and maximum valid values
* and it is important not to read too much into them. For example, there
* could be values within the range that are invalid for the field.
*
* @return {ValueRange} the range of valid values for the field.
*/
range() {
abstractMethodFail('range');
}
/**
* Get the range of valid values for this field using the temporal object to
* refine the result.
*
* This uses the temporal object to find the range of valid values for the field.
* This is similar to {@link range}, however this method refines the result
* using the temporal. For example, if the field is {@link DAY_OF_MONTH} the
* {@link range} method is not accurate as there are four possible month lengths,
* 28, 29, 30 and 31 days. Using this method with a date allows the range to be
* accurate, returning just one of those four options.
*
* There are two equivalent ways of using this method.
* The first is to invoke this method directly.
* The second is to use {@link TemporalAccessor#range}:
* <pre>
* // these two lines are equivalent, but the second approach is recommended
* temporal = thisField.rangeRefinedBy(temporal);
* temporal = temporal.range(thisField);
* </pre>
* It is recommended to use the second approach, {@link range},
* as it is a lot clearer to read in code.
*
* Implementations should perform any queries or calculations using the fields
* available in {@link ChronoField}.
* If the field is not supported a {@link DateTimeException} must be thrown.
*
* @param {!TemporalAccessor} temporal the temporal object used to refine the result.
* @return {ValueRange} the range of valid values for this field.
* @throws {DateTimeException} if the range for the field cannot be obtained.
*
*/
// eslint-disable-next-line no-unused-vars
rangeRefinedBy(temporal) {
abstractMethodFail('rangeRefinedBy');
}
/**
* Gets the value of this field from the specified temporal object.
*
* This queries the temporal object for the value of this field.
*
* There are two equivalent ways of using this method.
* The first is to invoke this method directly.
* The second is to use {@link TemporalAccessor#get}:
* <pre>
* // these two lines are equivalent, but the second approach is recommended
* temporal = thisField.getFrom(temporal);
* temporal = temporal.get(thisField);
* </pre>
* It is recommended to use the second approach, as it is a lot clearer to read in code.
*
* Implementations should perform any queries or calculations using the fields
* available in {@link ChronoField}.
* If the field is not supported a {@link DateTimeException} must be thrown.
*
* @param {!TemporalAccesor} temporal the temporal object to query.
* @return {number} the value of this field.
* @throws {DateTimeException} if a value for the field cannot be obtained.
*/
// eslint-disable-next-line no-unused-vars
getFrom(temporal) {
abstractMethodFail('getFrom');
}
/**
* Returns a copy of the specified temporal object with the value of this field set.
*
* This returns a new temporal object based on the specified one with the value for
* this field changed. For example, on a {@link LocalDate}, this could be used to
* set the year, month or day-of-month.
* The returned object has the same observable type as the specified object.
*
* In some cases, changing a field is not fully defined. For example, if the target object is
* a date representing the 31st January, then changing the month to February would be unclear.
* In cases like this, the implementation is responsible for resolving the result.
* Typically it will choose the previous valid date, which would be the last valid
* day of February in this example.
*
* There are two equivalent ways of using this method.
* The first is to invoke this method directly.
* The second is to use {@link Temporal#with}:
* <pre>
* // these two lines are equivalent, but the second approach is recommended
* temporal = thisField.adjustInto(temporal);
* temporal = temporal.with(thisField);
* </pre>
* It is recommended to use the second approach, `with(temporal)`,
* as it is a lot clearer to read in code.
*
* Implementations should perform any queries or calculations using the fields
* available in {@link ChronoField}.
* If the field is not supported a {@link DateTimeException} must be thrown.
*
* Implementations must not alter the specified temporal object.
* Instead, an adjusted copy of the original must be returned.
* This provides equivalent, safe behavior for immutable and mutable implementations.
*
* @param {!Temporal} temporal the temporal object to adjust.
* @param {!number} newValue the new value of the field.
* @return {Temporal} the adjusted temporal object.
* @throws {DateTimeException} if the field cannot be set.
*/
// eslint-disable-next-line no-unused-vars
adjustInto(temporal, newValue) {
abstractMethodFail('adjustInto');
}
/**
* Checks if this field is supported by the temporal object.
*
* This determines whether the temporal accessor supports this field.
* If this returns false, the the temporal cannot be queried for this field.
*
* There are two equivalent ways of using this method.
* The first is to invoke this method directly.
* The second is to use {@link TemporalAccessor#isSupported}:
* <pre>
* // these two lines are equivalent, but the second approach is recommended
* temporal = thisField.isSupportedBy(temporal);
* temporal = temporal.isSupported(thisField);
* </pre>
* It is recommended to use the second approach, `isSupported(temporal)`,
* as it is a lot clearer to read in code.
*
* Implementations should determine whether they are supported using the fields
* available in {@link ChronoField}.
*
* @param {!TemporalAccesor} temporal the temporal object to query.
* @return {boolean} `true` if the date-time can be queried for this field, `false` if not.
*/
// eslint-disable-next-line no-unused-vars
isSupportedBy(temporal) {
abstractMethodFail('isSupportedBy');
}
/**
* @return {string}
*/
displayName(/* TODO: locale */) {
abstractMethodFail('displayName');
}
/**
* @param {*} other
* @returns {boolean}
*/
// eslint-disable-next-line no-unused-vars
equals(other) {
abstractMethodFail('equals');
}
/**
* @returns {string}
*/
name() {
abstractMethodFail('name');
}
}
