@thi.ng/date/relative.d.ts

Datetime types, relative dates, math, iterators, composable formatters, locales

import { type MaybeDate, type Period } from "./api.js";
import { type DateTime } from "./datetime.js";
/**
 * Takes a relative time `offset` string in plain english and an optional `base`
 * date (default: now). Parses `offset` and returns new date with relative
 * offset applied. Returns `undefined` if parsing failed.
 *
 * @remarks
 * This function only handles the parsing and input normalization aspect for
 * {@link relative}. The latter function applies the actual offset.
 *
 * The following input formats are supported:
 *
 * - `"tomorrow"` / `"yesterday"` - ±1 day
 * - any weekday names in {@link EN_SHORT} and {@link EN_LONG} (always in future)
 * - `<"-"|"+">?<num><period><" ago">?"` - ±num periods (if prefixed with "-" or
 *   if the `" ago"` suffix is given, the offset will be applied towards the
 *   past)
 *
 * (Note: If both negative offset and "ago" is given, the suffix will, like a
 * double-negative, flip the direction back towards the future).
 *
 * If using the latter form:
 *
 * - `<num>` can be a positve integer or strings: `"next "`, `"a "` or `"an "`
 * - `<period>` can be:
 *   - `ms` / `millis` / `millisecond` / `milliseconds`
 *   - `s` / `sec` / `secs` / `second` / `seconds`
 *   - `min` / `mins` / `minute` / `minutes`
 *   - `h` / `hour` / `hours`
 *   - `d` / `day` / `days`
 *   - `w` / `week` / `weeks`
 *   - `mo` / `month` / `months`
 *   - `q` / `quarter` / `quarters`
 *   - `y` / `year` / `years`
 *
 * @param offset -
 * @param base -
 */
export declare const parseRelative: (offset: string, base?: MaybeDate) => DateTime | undefined;
/**
 * Applies the given relative offset (defined by `num` and `period`) to the
 * optionally given `base` date (default: now). If `num < 0` the result date
 * will be in the past (relative to `base`).
 *
 * @param num -
 * @param period -
 * @param base -
 */
export declare const relative: (num: number, period: Period, base?: MaybeDate) => DateTime;
/**
 * Returns the signed difference in milliseconds between given two dates `a` and
 * `b` (as `diff = a - b`).
 *
 * @remarks
 * Also see {@link absDifference}.
 *
 * @param a -
 * @param b -
 */
export declare const difference: (a: MaybeDate, b: MaybeDate) => number;
/**
 * Returns the unsigned difference in milliseconds between given dates.
 *
 * @remarks
 * Also see {@link difference} for signed difference.
 *
 * @param a
 * @param b
 */
export declare const absDifference: (a: MaybeDate, b: MaybeDate) => number;
/**
 * Computes and decomposes difference between given dates. Returns tuple of:
 * `[sign, years, months, days, hours, mins, secs, millis]`. The `sign` is used
 * to indicate the relative order of `a` compared to `b`, i.e. same contract as
 * [`ICompare`](https://docs.thi.ng/umbrella/api/interfaces/ICompare.html).
 *
 * @param a -
 * @param b -
 */
export declare const decomposeDifference: (a: MaybeDate, b?: MaybeDate) => number[];
//# sourceMappingURL=relative.d.ts.map