@js-joda/extra 0.9.1 → 0.10.0

package/src/Quarter.js

@@ -0,0 +1,587 @@
+/**
+ * @copyright (c) 2016, Philipp Thürwächter & Pattrick Hüper & Michał Sobkiewicz
+ * @copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos
+ * @license BSD-3-Clause (see LICENSE in the root directory of this source tree)
+ */
+
+// TODO: hm... is this a good idea?? copied from joda currently, could we add a js-joda-utils module??
+import { requireNonNull, requireInstance } from './assert';
+import { ChronoField, DateTimeException, IllegalArgumentException, IllegalStateException, IsoChronology, IsoFields, Month, TemporalAccessor, TemporalField, TemporalQueries, TemporalQuery, UnsupportedTemporalTypeException, _ as jodaInternal } from '@js-joda/core';
+
+const MathUtil = jodaInternal.MathUtil;
+
+/**
+ * A quarter-of-year, such as 'Q2'.
+ * 
+ * `Quarter` is an enum representing the 4 quarters of the year -
+ * Q1, Q2, Q3 and Q4. These are defined as January to March, April to June,
+ * July to September and October to December.
+ * 
+ * The `int` value follows the quarter, from 1 (Q1) to 4 (Q4).
+ * It is recommended that applications use the enum rather than the `int` value
+ * to ensure code clarity.
+ * 
+ * **Do not use `ordinal()` to obtain the numeric representation of `Quarter`.
+ * Use `getValue()` instead.**
+ * 
+ * This enum represents a common concept that is found in many calendar systems.
+ * As such, this enum may be used by any calendar system that has the quarter-of-year
+ * concept defined exactly equivalent to the ISO calendar system.
+ *
+ */
+export class Quarter extends TemporalAccessor {
+    /**
+     * replacement for enum `valueOf(name)`
+     * 
+     * @param {string} name
+     * @return {Quarter}
+     */
+    static valueOf(name) {
+        requireNonNull(name, 'name');
+        switch (name) {
+            case 'Q1':
+                return Quarter.Q1;
+            case 'Q2':
+                return Quarter.Q2;
+            case 'Q3':
+                return Quarter.Q3;
+            case 'Q4':
+                return Quarter.Q4;
+        }
+        throw new IllegalArgumentException(`No enum constant Quarter.${name}`);
+    }
+
+    /**
+     * replacement for enum `values()`
+     * @return {Quarter[]}
+     */
+    static values() {
+        return QUARTERS.slice();
+    }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Obtains an instance of `Quarter` from an `int` value.
+     * 
+     * `Quarter` is an enum representing the 4 quarters of the year.
+     * This factory allows the enum to be obtained from the `int` value.
+     * The `int` value follows the quarter, from 1 (Q1) to 4 (Q4).
+     *
+     * @param {number} quarterOfYear - the quarter-of-year to represent, from 1 (Q1) to 4 (Q4)
+     * @return {Quarter} the quarter-of-year, not null
+     * @throws {DateTimeException} if the quarter-of-year is invalid
+     */
+    static of(quarterOfYear) {
+        requireNonNull(quarterOfYear, 'quarterOfYear');
+        switch (quarterOfYear) {
+            case 1:
+                return Quarter.Q1;
+            case 2:
+                return Quarter.Q2;
+            case 3:
+                return Quarter.Q3;
+            case 4:
+                return Quarter.Q4;
+            default:
+                throw new DateTimeException(`Invalid value for Quarter: ${quarterOfYear}`);
+        }
+    }
+
+    /**
+     * Obtains an instance of `Quarter` from a month-of-year.
+     * 
+     * `Quarter` is an enum representing the 4 quarters of the year.
+     * This factory allows the enum to be obtained from the `Month` value.
+     * 
+     * January to March are Q1, April to June are Q2, July to September are Q3
+     * and October to December are Q4.
+     *
+     * @param {number} monthOfYear - the month-of-year to convert from, from 1 to 12
+     * @return {Quarter} the quarter-of-year, not null
+     * @throws {DateTimeException} if the month-of-year is invalid
+     */
+    static ofMonth(monthOfYear) {
+        requireNonNull(monthOfYear, 'monthOfYear');
+        ChronoField.MONTH_OF_YEAR.range().checkValidValue(monthOfYear, ChronoField.MONTH_OF_YEAR);
+        return Quarter.of(MathUtil.intDiv(monthOfYear - 1, 3) + 1);
+    }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Obtains an instance of `Quarter` from a temporal object.
+     * 
+     * This obtains a quarter based on the specified temporal.
+     * A `TemporalAccessor` represents an arbitrary set of date and time information,
+     * which this factory converts to an instance of `Quarter`.
+     * 
+     * The conversion extracts the {@link IsoFields.QUARTER_OF_YEAR} field.
+     * The extraction is only permitted if the temporal object has an ISO
+     * chronology, or can be converted to a `LocalDate`.
+     * 
+     * This method matches the signature of the functional interface {@link TemporalQuery}
+     * allowing it to be used in queries via method reference, `Quarter.from`.
+     *
+     * @param {Temporal} temporal - the temporal-time object to convert, not null
+     * @return {Quarter} the quarter-of-year, not null
+     * @throws {DateTimeException} if unable to convert to a `Quarter`
+     */
+    static from(temporal) {
+        if (temporal instanceof Quarter) {
+            return temporal;
+        } else if (temporal instanceof Month) {
+            const month = temporal;
+            return Quarter.of(MathUtil.intDiv(month.ordinal(), 3) + 1);
+        }
+        try {
+            /* TODO: only IsoChronology for now
+            if (IsoChronology.INSTANCE.equals(Chronology.from(temporal)) == false) {
+                temporal = LocalDate.from(temporal);
+            }
+            */
+            const qoy = MathUtil.safeToInt(temporal.getLong(IsoFields.QUARTER_OF_YEAR));
+            return Quarter.of(qoy);
+        } catch (ex) {
+            throw new DateTimeException(`Unable to obtain Quarter from TemporalAccessor: ${temporal} of type ${temporal.constructor.name}`, ex);
+        }
+    }
+
+    /**
+     * 
+     * @param {number} value
+     * @param {string} name
+     * @private
+     */
+    constructor(value, name) {
+        super();
+        this._value = MathUtil.safeToInt(value);
+        this._name = name;
+    }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Gets the quarter-of-year `int` value.
+     * 
+     * The values are numbered following the ISO-8601 standard,
+     * from 1 (Q1) to 4 (Q4).
+     *
+     * @return {number} the quarter-of-year, from 1 (Q1) to 4 (Q4)
+     */
+    value() {
+        return this._value;
+    }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Gets the textual representation, such as 'Q1' or '4th quarter'.
+     * 
+     * This returns the textual name used to identify the quarter-of-year,
+     * suitable for presentation to the user.
+     * The parameters control the style of the returned text and the locale.
+     * 
+     * If no textual mapping is found then the {@link #getValue() numeric value} is returned.
+     *
+     * @param {TextStyle} style - the length of the text required, not null
+     * @param {Locale} locale - the locale to use, not null
+     * @return {string} the text value of the day-of-week, not null
+     */
+    // eslint-disable-next-line no-unused-vars
+    displayName(style, locale) {
+        throw new IllegalArgumentException('Pattern using (localized) text not implemented yet!');
+    }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Checks if the specified field is supported.
+     * 
+     * This checks if this quarter-of-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 the field is {@link IsoFields#QUARTER_OF_YEAR QUARTER_OF_YEAR} then
+     * this method returns true.
+     * All `ChronoField` instances will return false.
+     * 
+     * If the field is not a `ChronoField`, then the result of this method
+     * is obtained by invoking `TemporalField.isSupportedBy(TemporalAccessor)`
+     * passing `this` as the argument.
+     * Whether the field is supported is determined by the field.
+     *
+     * @param {TemporalField} field - the field to check, null returns false
+     * @return {boolean} true if the field is supported on this quarter-of-year, false if not
+     */
+    isSupported(field) {
+        if (field === IsoFields.QUARTER_OF_YEAR) {
+            return true;
+        } else if (field instanceof ChronoField) {
+            return false;
+        }
+        return field != null && field.isSupportedBy(this);
+    }
+
+    /**
+     * Gets the range of valid values for the specified field.
+     * 
+     * The range object expresses the minimum and maximum valid values for a field.
+     * This quarter 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 {@link IsoFields#QUARTER_OF_YEAR QUARTER_OF_YEAR} then the
+     * range of the quarter-of-year, from 1 to 4, will be returned.
+     * All `ChronoField` instances will throw an `UnsupportedTemporalTypeException`.
+     * 
+     * If the field is not a `ChronoField`, then the result of this method
+     * is obtained by invoking `TemporalField.rangeRefinedBy(TemporalAccessor)`
+     * passing `this` as the argument.
+     * Whether the range can be obtained is determined by the field.
+     *
+     * @param {TemporalField} field - the field to query the range for, not null
+     * @return {ValueRange} the range of valid values for the field, not null
+     * @throws {DateTimeException} if the range for the field cannot be obtained
+     * @throws {UnsupportedTemporalTypeException} if the field is not supported
+     */
+    range(field) {
+        requireNonNull(field, 'field');
+        if (field === IsoFields.QUARTER_OF_YEAR) {
+            return field.range();
+        } else if (field instanceof ChronoField) {
+            throw new UnsupportedTemporalTypeException(`Unsupported field: ${field}`);
+        }
+        return super.range(field);
+    }
+
+    /**
+     * Gets the value of the specified field from this quarter-of-year as an `int`.
+     * 
+     * This queries this quarter 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 {@link IsoFields.QUARTER_OF_YEAR} then the
+     * value of the quarter-of-year, from 1 to 4, will be returned.
+     * All `ChronoField` instances will throw an `UnsupportedTemporalTypeException`.
+     * 
+     * If the field is not a `ChronoField`, then the result of this method
+     * is obtained by invoking `TemporalField.getFrom(TemporalAccessor)`
+     * passing `this` as the argument. Whether the value can be obtained,
+     * and what the value represents, is determined by the field.
+     *
+     * @param {TemporalField} field - the field to get, not null
+     * @return {number} the value for the field, within the valid range of values
+     * @throws {DateTimeException} if a value for the field cannot be obtained or
+     *         the value is outside the range of valid values for the field
+     * @throws {UnsupportedTemporalTypeException} if the field is not supported or
+     *         the range of values exceeds an `int`
+     * @throws {ArithmeticException} if numeric overflow occurs
+     */
+    get(field) {
+        requireNonNull(field, 'field');
+        requireInstance(field, TemporalField, 'field');
+        return this.range(field).checkValidIntValue(this.getLong(field), field);
+    }
+
+    /**
+     * Gets the value of the specified field from this quarter-of-year as a `long`.
+     * 
+     * This queries this quarter 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 {@link IsoFields#QUARTER_OF_YEAR QUARTER_OF_YEAR} then the
+     * value of the quarter-of-year, from 1 to 4, will be returned.
+     * All other `ChronoField` instances will throw an `UnsupportedTemporalTypeException`.
+     * 
+     * If the field is not a `ChronoField`, then the result of this method
+     * is obtained by invoking `TemporalField.getFrom(TemporalAccessor)`
+     * passing `this` as the argument. Whether the value can be obtained,
+     * and what the value represents, is determined by the field.
+     *
+     * @param {TemporalField} field - the field to get, not null
+     * @return {number} the value for the field
+     * @throws {DateTimeException} if a value for the field cannot be obtained
+     * @throws {UnsupportedTemporalTypeException} if the field is not supported
+     * @throws {ArithmeticException} if numeric overflow occurs
+     */
+    getLong(field) {
+        requireNonNull(field, 'field');
+        if (field === IsoFields.QUARTER_OF_YEAR) {
+            return this.value();
+        } else if (field instanceof ChronoField) {
+            throw new UnsupportedTemporalTypeException(`Unsupported field: ${field}`);
+        }
+        return field.getFrom(this);
+    }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Returns the quarter that is the specified number of quarters after this one.
+     * 
+     * The calculation rolls around the end of the year from Q4 to Q1.
+     * The specified period may be negative.
+     * 
+     * This instance is immutable and unaffected by this method call.
+     *
+     * @param {number} quarters - the quarters to add, positive or negative
+     * @return {Quarter} the resulting quarter, not null
+     */
+    plus(quarters) {
+        const amount = MathUtil.intMod(quarters, 4);
+        return QUARTERS[(this.ordinal() + amount + 4) % 4];
+    }
+
+    /**
+     * Returns the quarter that is the specified number of quarters before this one.
+     * 
+     * The calculation rolls around the start of the year from Q1 to Q4.
+     * The specified period may be negative.
+     * 
+     * This instance is immutable and unaffected by this method call.
+     *
+     * @param {number} quarters - the quarters to subtract, positive or negative
+     * @return {Quarter} the resulting quarter, not null
+     */
+    minus(quarters) {
+        return this.plus(-(MathUtil.intMod(quarters, 4)));
+    }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Gets the length of this quarter in days.
+     * 
+     * This takes a flag to determine whether to return the length for a leap year or not.
+     * 
+     * Q1 has 90 in a standard year and 91 days in a leap year.
+     * Q2 has 91 days.
+     * Q3 and Q4 have 92 days.
+     *
+     * @param {boolean} leapYear - true if the length is required for a leap year
+     * @return {number} the length of this month in days, from 90 to 92
+     */
+    length(leapYear) {
+        switch (this) {
+            case Quarter.Q1:
+                return (leapYear ? 91 : 90);
+            case Quarter.Q2:
+                return 91;
+            default:
+                return 92;
+        }
+    }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Gets the first of the three months that this quarter refers to.
+     * 
+     * Q1 will return January.
+     * Q2 will return April.
+     * Q3 will return July.
+     * Q4 will return October.
+     * 
+     * To obtain the other two months of the quarter, simply use {@link Month#plus(long)}
+     * on the returned month.
+     *
+     * @return {Month} the first month in the quarter, not null
+     */
+    firstMonth() {
+        switch (this) {
+            case Quarter.Q1:
+                return Month.JANUARY;
+            case Quarter.Q2:
+                return Month.APRIL;
+            case Quarter.Q3:
+                return Month.JULY;
+            case Quarter.Q4:
+                return Month.OCTOBER;
+            default:
+                throw new IllegalStateException('Unreachable');
+        }
+    }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Queries this quarter-of-year using the specified query.
+     * 
+     * This queries this quarter-of-year 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
+     * {@link TemporalQuery.queryFrom(TemporalAccessor)} method on the
+     * specified query passing `this` as the argument.
+     *
+     * @param {TemporalQuery} query - the query to invoke, not null
+     * @return {*} the query result, null may be returned (defined by the query)
+     * @throws {DateTimeException} if unable to query (defined by the query)
+     * @throws {ArithmeticException} if numeric overflow occurs (defined by the query)
+     */
+    query(query) {
+        requireNonNull(query, 'query');
+        requireInstance(query, TemporalQuery, 'query');
+        if (query === TemporalQueries.chronology()) {
+            return IsoChronology.INSTANCE;
+        } else if (query === TemporalQueries.precision()) {
+            return IsoFields.QUARTER_YEARS;
+        }
+        return super.query(query);
+    }
+
+    /**
+     * Adjusts the specified temporal object to have this quarter-of-year.
+     * 
+     * This returns a temporal object of the same observable type as the input
+     * with the quarter-of-year changed to be the same as this.
+     * 
+     * The adjustment is equivalent to using {@link Temporal.with}
+     * passing {@link IsoFields.QUARTER_OF_YEAR} as the field.
+     * If the specified temporal object does not use the ISO calendar system then
+     * a `DateTimeException` is thrown.
+     * 
+     * In most cases, it is clearer to reverse the calling pattern by using
+     * {@link Temporal.with}:
+     * ```
+     *   // these two lines are equivalent, but the second approach is recommended
+     *   temporal = thisQuarter.adjustInto(temporal);
+     *   temporal = temporal.with(thisQuarter);
+     * ```
+     * 
+     * For example, given a date in May, the following are output:
+     * ```
+     *   dateInMay.with(Q1);    // three months earlier
+     *   dateInMay.with(Q2);    // no change
+     *   dateInMay.with(Q3);    // three months later
+     *   dateInMay.with(Q4);    // six months later
+     * ```
+     * 
+     * This instance is immutable and unaffected by this method call.
+     *
+     * @param {Temporal} temporal - the target object to be adjusted, not null
+     * @return {Temporal} the adjusted object, not null
+     * @throws {DateTimeException} if unable to make the adjustment
+     * @throws {ArithmeticException} if numeric overflow occurs
+     */
+    adjustInto(temporal) {
+        requireNonNull(temporal, 'temporal');
+        /* TODO: only IsoChronology for now
+        if (Chronology.from(temporal).equals(IsoChronology.INSTANCE) == false) {
+            throw new DateTimeException('Adjustment only supported on ISO date-time');
+        }
+        */
+        return temporal.with(IsoFields.QUARTER_OF_YEAR, this.value());
+    }
+
+    //-----------------------------------------------------------------------
+    // Enum
+    //-----------------------------------------------------------------------
+
+    /**
+     *
+     * @return {number}
+     */
+    ordinal() {
+        return this._value - 1;
+    }
+
+    /**
+     *
+     * @return {string}
+     */
+    name() {
+        return this._name;
+    }
+
+    //-----------------------------------------------------------------------
+    // Comparable
+    //-----------------------------------------------------------------------
+
+    /**
+     * Compares this Quarter to another Quarter.
+     *
+     * The comparison is based on the value of the Quarter.
+     * It is "consistent with equals", as defined by {@link Comparable}.
+     *
+     * @param {Quarter} other - the other quarter to compare to, not null
+     * @return {number} the comparator value, negative if less, positive if greater
+     */
+    compareTo(other) {
+        requireNonNull(other, 'other');
+        requireInstance(other, Quarter, 'other');
+        return this._value - other._value;
+    }
+
+    //-----------------------------------------------------------------------
+    // Object
+    //-----------------------------------------------------------------------
+
+    /**
+     * Outputs this quarter as a String, such as Q1
+     *
+     * @return {string} a string representation of this quarter, not null
+     */
+    toString() {
+        return this.name();
+    }
+
+    /**
+     *
+     * @return {boolean}
+     */
+    equals(other){
+        return this === other;
+    }
+
+    /**
+     * A hash code for this quarter.
+     *
+     * @return {number} a suitable hash code
+     */
+    hashCode() {
+        return this._value;
+    }
+}
+
+let QUARTERS;
+
+export function _init() {
+    /**
+     * The singleton instance for the first quarter-of-year, from January to March.
+     * This has the numeric value of `1`.
+     */
+    Quarter.Q1 = new Quarter(1, 'Q1');
+    /**
+      * The singleton instance for the second quarter-of-year, from April to June.
+      * This has the numeric value of `2`.
+      */
+    Quarter.Q2 = new Quarter(2, 'Q2');
+    /**
+      * The singleton instance for the third quarter-of-year, from July to September.
+      * This has the numeric value of `3`.
+      */
+    Quarter.Q3 = new Quarter(3, 'Q3');
+    /**
+      * The singleton instance for the fourth quarter-of-year, from October to December.
+      * This has the numeric value of `4`.
+      */
+    Quarter.Q4 = new Quarter(4, 'Q4');
+
+    Quarter.FROM = createTemporalQuery('Quarter.FROM', (temporal) => {
+        return Quarter.from(temporal);
+    });
+
+    QUARTERS = [
+        Quarter.Q1,
+        Quarter.Q2,
+        Quarter.Q3,
+        Quarter.Q4
+    ];
+}
+
+// copied from packages/core/src/temporal/TemporalQuery.js
+function createTemporalQuery(name, queryFromFunction) {
+    class ExtendedTemporalQuery extends TemporalQuery {
+    }
+
+    ExtendedTemporalQuery.prototype.queryFrom = queryFromFunction;
+    return new ExtendedTemporalQuery(name);
+}