/** @file Data types and functions for working with dates in the Gregorian calendar. */
import type { Comparator } from "@softwareventures/ordered";
import { Comparison } from "@softwareventures/ordered";
import * as format from "@softwareventures/format-date";
/** A date in the Gregorian calendar, with no associated time zone. */
export interface Date {
    /** Type discriminator identifying the object as a `Date`. */
    readonly type: "Date";
    /** The day of the month. Should be an integer in the range `1`-`31`. */
    day: number;
    /** The month of the year. Should be an integer in the range `1`-`12`. */
    month: number;
    /**
     * The year.
     *
     * Should be an integer.
     *
     * Positive values represent years in the Common Era (CE/AD). For example
     * `2020` represents 2020 CE, the year this module was first published to
     * npm.
     *
     * Negative values or zero represent years before the Common Era (BCE/BC).
     * Zero represents 1 BCE, `-1` represents 2 BCE, `-2` represents 3 BCE,
     * etc.
     *
     * Note that there is no year zero in the Gregorian calendar. The year
     * 1 BCE was immediately followed by 1 CE.
     */
    year: number;
}
/**
 * Options required to construct a `Date`.
 *
 * An instance of {@link Date} may always be used in place of `DateOptions`.
 */
export interface DateOptions {
    /**
     * Type discriminator identifying the object as a `Date`.
     *
     * If specified, must be the string `"Date"`. This is to prevent errors
     * caused by a `DateTime` being accidentally passed to `Date` functions.
     */
    readonly type?: "Date";
    /** The day of the month. Should be in the range `1`-`31`. */
    readonly day: number;
    /** The month of the year. Should be in the range `1`-`12`. */
    readonly month: number;
    /**
     * The year.
     *
     * Positive values represent years in the Common Era (CE/AD). For example
     * `2020` represents 2020 CE, the year this module was first published to
     * npm.
     *
     * Negative values or zero represent years before the Common Era (BCE/BC).
     * Zero represents 1 BCE, `-1` represents 2 BCE, `-2` represents 3 BCE,
     * etc.
     *
     * Note that there is no year zero in the Gregorian calendar. The year
     * 1 BCE was immediately followed by 1 CE.
     */
    readonly year: number;
}
/** The numeric representation of the month of January. */
export declare const JANUARY = 1;
/** The numeric representation of the month of February. */
export declare const FEBRUARY = 2;
/** The numeric representation of the month of March. */
export declare const MARCH = 3;
/** The numeric representation of the month of April. */
export declare const APRIL = 4;
/** The numeric representation of the month of May. */
export declare const MAY = 5;
/** The numeric representation of the month of June. */
export declare const JUNE = 6;
/** The numeric representation of the month of July. */
export declare const JULY = 7;
/** The numeric representation of the month of August. */
export declare const AUGUST = 8;
/** The numeric representation of the month of September. */
export declare const SEPTEMBER = 9;
/** The numeric representation of the month of October. */
export declare const OCTOBER = 10;
/** The numeric representation of the month of November. */
export declare const NOVEMBER = 11;
/** The numeric representation of the month of December. */
export declare const DECEMBER = 12;
/**
 * Tests if the specified year is a leap year. Returns `true` if it is,
 * otherwise `false`.
 *
 * Positive values represent years in the Common Era (CE/AD). For example
 * `2020` represents 2020 CE, the year this module was first published to npm.
 *
 * Negative values or zero represent years before the Common Era (BCE/BC).
 * Zero represents 1 BCE, `-1` represents 2 BCE, `-2` represents 3 BCE,
 * etc.
 *
 * Note that there is no year zero in the Gregorian calendar. The year
 * 1 BCE was immediately followed by 1 CE.
 */
export declare function isLeapYear(year: number): boolean;
/**
 * Returns the number of days in the specified month in the specified year.
 *
 * @param month - An integer representing the month, in the range `1` (January)
 *   to `12` (December).
 *
 * @param year - An integer representing the year. Positive values represent
 *   years in the Common Era (CE/AD). For example `2020` represents 2020 CE,
 *   the year this module was first published to npm. Negative values or zero
 *   represent years before the Common Era (BCE/BC). Zero represents 1 BCE,
 *   `-1` represents 2 BCE, `-2` represents 3 BCE, etc. There is no year zero
 *   in the Gregorian calendar. The year 1 BCE was immediately followed by 1
 *   CE.
 */
export declare function daysInMonth(month: number, year: number): number;
/**
 * Returns `true` if the specified value has the shape of a {@link Date}
 * object.
 *
 * The `year`, `month` and `day` fields may be non-integers or outside the
 * valid range, meaning that the object may not represent a valid date.
 *
 * To test if the object represents a valid date, call {@link isValid} or
 * {@link isValidDate}.
 */
export declare function isDate(value: unknown): value is Date;
/**
 * Tests if the specified value is a {@link Date} object representing a valid
 * date.
 *
 * Returns `true` if the value has the shape of a `Date` object and the `year`,
 * `month`, and `day` fields are all integers inside the valid range.
 *
 * Dates returned by functions in this library are always valid.
 */
export declare function isValidDate(value: unknown): value is Date;
/**
 * Tests if the specified {@link Date} object represents a valid date.
 *
 * Returns `true` if the `year`, `month` and `day` fields are all integers inside the
 * valid range.
 *
 * Dates returned by functions in this library are always valid.
 */
export declare function isValid(date: DateOptions): boolean;
/**
 * Tests if the specified {@link Date} object represents a valid date.
 *
 * Returns `true` if the `year`, `month` and `day` fields are all integers
 * inside the valid range.
 *
 * Dates returned by functions in this library are always valid.
 *
 * Alias of {@link isValid}, useful for disambiguation from similar functions
 * that operate on other types.
 */
export declare const isDateValid: typeof isValid;
/**
 * Tests if the specified {@link Date} object represents a valid date.
 *
 * Returns `true` if the `year`, `month` and `day` fields are all integers
 * inside the valid range.
 *
 * Dates returned by functions in this library are always valid.
 *
 * Alias of {@link isValid}, useful for disambiguation from similar functions
 * that operate on other types.
 *
 * @deprecated Use {@link isDateValid} instead.
 */
export declare const dateIsValid: typeof isValid;
/**
 * Asserts that the specified {@link Date} object represents a valid date.
 *
 * Dates returned by functions in this library are always valid.
 *
 * @throws {Error} if any of the `year`, `month` or `day` fields are
 *   non-integers or outside the valid range.
 */
export declare function validate(date: DateOptions): void;
/**
 * Asserts that the specified {@link Date} object represents a valid date.
 *
 * Dates returned by functions in this library are always valid.
 *
 * Alias of {@link validate}.
 *
 * @throws {Error} if any of the `year`, `month` or `day` fields are
 *   non-integers or outside the valid range.
 */
export declare const validateDate: typeof validate;
/**
 * Constructs a normalized {@link Date} object from the specified `year`,
 * `month` and `day`.
 *
 * If the `month` or `day` fields are outside the valid range, then they will
 * roll over into the next month or year.
 *
 * @throws {Error} if the `year`, `month` or `day` fields are not finite
 *   numbers
 */
export declare function date(date: DateOptions): Date;
/**
 * Normalizes the specified {@link Date} object so that it represents a valid
 * date.
 *
 * If the `month` or `day` fields are outside the valid range, then they will
 * roll over into the next month or year.
 *
 * Alias of {@link date}. Calling the function by this name instead might make
 * code clearer in cases where the purpose is to normalize an existing `Date`
 * object.
 *
 * @throws {Error} if the `year`, `month` or `day` fields are not finite
 *   numbers */
export declare const normalize: typeof date;
/**
 * Normalizes the specified {@link Date} object so that it represents a valid date.
 *
 * If the `month` or `day` fields are outside the valid range, then they will
 * roll over into the next month or year.
 *
 * Alias of {@link date}. Calling the function by this name instead might make
 * code clearer in cases where the purpose is to normalize an existing `Date`
 * object.
 *
 * @throws {Error} if the `year`, `month` or `day` fields are not finite
 *   numbers */
export declare const normalizeDate: typeof date;
/**
 * Converts the specified {@link Date} to a count of the number of days since the
 * reference date of 1st January, 1 CE.
 */
export declare function toReferenceDays(date: Partial<DateOptions>): number;
/**
 *  Creates a {@link Date} corresponding to the specified count of the number
 *  of days since the reference date of 1st January, 1 CE.
 *
 *  @throws {Error} if `referenceDays` is non-finite.
 */
export declare function fromReferenceDays(referenceDays: number): Date;
/**
 * Returns `true` if `a` and `b` refer to the same date.
 */
export declare function equal(a: DateOptions, b: DateOptions): boolean;
/**
 * Returns `true` if `a` and `b` refer to the same date.
 *
 * Alias of {@link equal}, for disambiguation from other equality functions.
 */
export declare const datesEqual: typeof equal;
/**
 * Returns `true` if `a` and `b` refer to the same date.
 *
 * Curried variant of {@link equal}.
 */
export declare function equalFn(b: DateOptions): (a: DateOptions) => boolean;
/**
 * Returns `true` if `a` and `b` refer to the same date.
 *
 * Curried variant of {@link datesEqual}.
 */
export declare const datesEqualFn: typeof equalFn;
/**
 * Returns `true` if `a` and `b` refer to different dates.
 */
export declare function notEqual(a: DateOptions, b: DateOptions): boolean;
/**
 * Returns `true` if `a` and `b` refer to different dates.
 *
 * Alias of {@link notEqual}, for disambiguation from other inequality functions.
 */
export declare const datesNotEqual: typeof notEqual;
/**
 * Returns `true` if `a` and `b` refer to different dates.
 *
 * Curried variant of {@link notEqual}.
 */
export declare function notEqualFn(b: DateOptions): (a: DateOptions) => boolean;
/**
 * Returns `true` if `a` and `b` refer to different dates.
 *
 * Curried variant of {@link datesNotEqual}.
 */
export declare const datesNotEqualFn: typeof notEqualFn;
/**
 * Compares two dates and returns a {@link Comparison} specifying if `a` is
 * before, equal to, or after `b`.
 */
export declare const compare: Comparator<DateOptions>;
/**
 * Compares two dates and returns a {@link Comparison} specifying if `a` is
 * before, equal to, or after `b`.
 *
 * Alias of {@link compare}, useful for disambiguation from other comparison
 * functions.
 */
export declare const compareDates: Comparator<DateOptions>;
/**
 * Compares two dates and returns a {@link Comparison} specifying if `a` is
 * before, equal to, or after `b`.
 *
 * Curried variant of {@link compare}.
 */
export declare function compareFn(b: DateOptions): (a: DateOptions) => Comparison;
/**
 * Compares two dates and returns a {@link Comparison} specifying if `a` is before,
 * equal to, or after `b`.
 *
 * Curried variant of {@link compareDates}.
 */
export declare const compareDatesFn: typeof compareFn;
/**
 * Returns `true` if `a` refers to a date before `b`.
 */
export declare function before(a: DateOptions, b: DateOptions): boolean;
/**
 * Returns `true` if `a` refers to a date before `b`.
 *
 * Alias of {@link before}, useful for disambiguation from similar functions
 * that operate on other date/time types.
 */
export declare const dateBefore: typeof before;
/**
 * Returns `true` if `a` refers to a date before `b`.
 *
 * Curried variant of {@link before}.
 */
export declare function beforeFn(b: DateOptions): (a: DateOptions) => boolean;
/**
 * Returns `true` if `a` refers to a date before `b`.
 *
 * Curried variant of {@link dateBefore}.
 */
export declare const dateBeforeFn: typeof beforeFn;
/**
 * Returns `true` if `a` refers to a date before or the same as `b`.
 */
export declare function beforeOrEqual(a: DateOptions, b: DateOptions): boolean;
/**
 * Returns `true` if `a` refers to a date before or the same as `b`.
 *
 * Alias of {@link beforeOrEqual}, useful for disambiguation from similar
 * functions that operate on other date/time types.
 */
export declare const dateBeforeOrEqual: typeof beforeOrEqual;
/**
 * Returns `true` if `a` refers to a date before or the same as `b`.
 *
 * Curried variant of {@link beforeOrEqual}.
 */
export declare function beforeOrEqualFn(b: DateOptions): (a: DateOptions) => boolean;
/**
 * Returns `true` if `a` refers to a date before or the same as `b`.
 *
 * Curried variant of {@link dateBeforeOrEqual}.
 */
export declare const dateBeforeOrEqualFn: typeof beforeOrEqualFn;
/**
 * Returns `true` if `a` refers to a date after `b`.
 */
export declare function after(a: DateOptions, b: DateOptions): boolean;
/**
 * Returns `true` if `a` refers to a date after `b`.
 *
 * Alias of {@link after}, useful for disambiguation from similar functions
 * that operate on other date/time types.
 */
export declare const dateAfter: typeof after;
/**
 * Returns `true` if `a` refers to a date after `b`.
 *
 * Curried variant of {@link after}.
 */
export declare function afterFn(b: DateOptions): (a: DateOptions) => boolean;
/**
 * Returns `true` if `a` refers to a date after `b`.
 *
 * Curried variant of {@link dateAfter}.
 */
export declare const dateAfterFn: typeof afterFn;
/**
 * Returns `true` if `a` refers to a date after or the same as `b`.
 */
export declare function afterOrEqual(a: DateOptions, b: DateOptions): boolean;
/**
 * Returns `true` if `a` refers to a date after or the same as `b`.
 *
 * Alias of {@link afterOrEqual}, useful for disambiguation from similar
 * functions that operate on other date/time types.
 */
export declare const dateAfterOrEqual: typeof afterOrEqual;
/**
 * Returns `true` if `a` refers to a date after or the same as `b`.
 *
 * Curried variant of {@link afterOrEqual}.
 */
export declare function afterOrEqualFn(b: DateOptions): (a: DateOptions) => boolean;
/**
 * Returns `true` if `a` refers to a date after or the same as `b`.
 *
 * Curried variant of {@link dateAfterOrEqual}.
 */
export declare const dateAfterOrEqualFn: typeof afterOrEqualFn;
/**
 * Compares two dates and returns the earlier of the two.
 *
 * @throws {Error} if both specified `Date`s contain numeric fields that
 *   are non-finite.
 */
export declare function earliest(a: DateOptions, b: DateOptions): Date;
/**
 * Compares two dates and returns the earlier of the two.
 *
 * Alias of {@link earliest}, useful for disambiguation from similar functions
 * that operate on other date/time types.
 *
 * @throws {Error} if both specified `Date`s contain numeric fields that
 *   are non-finite.
 */
export declare const earliestDate: typeof earliest;
/**
 * Compares two dates and returns the earlier of the two.
 *
 * Curried variant of {@link earliest}.
 *
 * @throws {Error} if both specified `Date`s contain numeric fields that
 *   are non-finite.
 */
export declare function earliestFn(b: DateOptions): (a: DateOptions) => Date;
/**
 * Compares two dates and returns the earlier of the two.
 *
 * Curried variant of {@link earliestDate}.
 *
 * @throws {Error} if both specified `Date`s contain numeric fields that
 *   are non-finite.
 */
export declare const earliestDateFn: typeof earliestFn;
/**
 * Compares two dates and returns the later of the two.
 *
 * @throws {Error} if both specified `Date`s contain numeric fields that
 *   are non-finite.
 */
export declare function latest(a: DateOptions, b: DateOptions): Date;
/**
 * Compares two dates and returns the later of the two.
 *
 * Alias of {@link latest}, useful for disambiguation from similar functions
 * that operate on other date/time types.
 *
 * @throws {Error} if both specified `Date`s contain numeric fields that
 *   are non-finite.
 */
export declare const latestDate: typeof latest;
/**
 * Compares two dates and returns the later of the two.
 *
 * Curried variant of {@link latest}.
 *
 * @throws {Error} if both specified `Date`s contain numeric fields that
 *   are non-finite.
 */
export declare function latestFn(b: DateOptions): (a: DateOptions) => Date;
/**
 * Compares two dates and returns the later of the two.
 *
 * Curried variant of {@link latestDate}.
 *
 * @throws {Error} if both specified `Date`s contain numeric fields that
 *   are non-finite.
 */
export declare const latestDateFn: typeof latestFn;
/**
 * Returns today's date according to UTC.
 */
export declare function todayUtc(): Date;
/**
 * Returns today's date, according to the device's local timezone.
 */
export declare function todayDeviceLocal(): Date;
/**
 * Returns today's date, according to the device's local timezone.
 *
 * Alias of {@link todayDeviceLocal}, retained for backwards compatibility.
 *
 * @deprecated Use {@link todayDeviceLocal} instead. This function has been
 *   renamed to make it clear that the timezone used is the local timezone as
 *   reported by the device.
 */
export declare const todayLocal: typeof todayDeviceLocal;
/**
 * Parses a {@link Date} from text in ISO 8601 format.
 *
 * The ISO 8601 text must not specify a time zone offset.
 *
 * If the specified text is not a valid ISO 8601 date then this function
 * returns `null`.
 *
 * Both extended `YYYY-MM-DD` and basic `YYYYMMDD` ISO 8601 formats are
 * accepted.
 */
export declare function parseIso8601(text: string): Date | null;
/**
 * Parses a {@link Date} from text in ISO 8601 format.
 *
 * The ISO 8601 text must not specify a time zone offset.
 *
 * If the specified text is not a valid ISO 8601 date then this function
 * returns `null`.
 *
 * Both extended `YYYY-MM-DD` and basic `YYYYMMDD` ISO 8601 formats are
 * accepted.
 *
 * Alias of {@link parseIso8601}, useful for disambiguation from similar
 * functions that operate on other date/time types.
 */
export declare const parseDateIso8601: typeof parseIso8601;
/**
 * Formats the specified Date as IS0 8601 extended, e.g. `2021-05-01`.
 *
 * For other formats, see `@softwareventures/format-date`.
 */
export declare const formatIso8601: format.DateFormatter;
/**
 * Formats the specified Date as IS0 8601 extended, e.g. `2021-05-01`.
 *
 * For other formats, see `@softwareventures/format-date`.
 *
 * Alias of {@link formatIso8601}, useful for disambiguation from similar
 * functions that operate on other date/time types.
 */
export declare const formatDateIso8601: format.DateFormatter;