/**
 * UTC Gregorian calendar helpers.
 */
import { type PlainDateTime } from './types.js';
export declare const MS_PER_SECOND = 1000;
export declare const MS_PER_DAY = 86400000;
export declare function isLeapYear(year: number): boolean;
export declare function daysInMonth(year: number, month: number): number;
export declare function assertValidDateTime(value: PlainDateTime, source: string): void;
export declare function toEpochMillis(value: PlainDateTime): number;
export declare function fromEpochMillis(ms: number): PlainDateTime;
export declare function toEpochDay(value: PlainDateTime): number;
export declare function fromEpochDay(day: number): PlainDateTime;
export declare function startOfDay(value: PlainDateTime): PlainDateTime;
export declare function subtractUtcYears(ms: number, years: number): number;
export declare function utcWeekday(value: PlainDateTime): number;
/**
 * A step is EITHER a fixed span or a calendar span, and never both.
 *
 * The distinction is not pedantry: `15m` is always 900 000 milliseconds, while
 * `1mo` is 28, 29, 30 or 31 days depending on where you start. They compose
 * within their own group — `1h30m`, `1y6mo` — and refuse to compose across it,
 * because "one month and fifteen days" depends on which you apply first, and a
 * config whose meaning turns on an invisible ordering is worse than one that
 * will not parse. Allowing the mix later is easy; changing what it already means
 * is not.
 */
export interface StepSpec {
    /** Milliseconds per step. Zero for a calendar step. */
    readonly ms: number;
    /** Months per step. Zero for a fixed step. */
    readonly months: number;
}
/** What a `step=` may say, for a diagnostic to quote. */
export declare const STEP_SYNTAX = "15m, 1h30m, 2d, 3mo, 1y \u2014 units s, m, h, d, w, mo, y";
/** Why a `step=` did not parse, or the step it means. */
export type StepResult = {
    readonly ok: true;
    readonly step: StepSpec;
} | {
    readonly ok: false;
    readonly reason: 'syntax' | 'mixed';
};
/** The default step of a walked axis: one day. */
export declare const DEFAULT_STEP: StepSpec;
/**
 * `step="15m"`, `step="1h30m"`, `step="3mo"`, `step="2"` — how far a row advances.
 *
 * A bare number means DAYS, the default unit, so `step="2"` is every other day.
 * A unit may appear once: `1h30m1h` is a typo, and summing it would hide the
 * typo rather than report it.
 */
export declare function parseStep(raw: string | undefined): StepResult;
/**
 * `start` advanced by `n` steps.
 *
 * A calendar month has no fixed length, so stepping by month or year keeps the
 * DAY OF MONTH and clamps it to the last day of a shorter one: 31 January plus
 * one month is 28 February, not 3 March. That is the same rule `subtractUtcYears`
 * above already applies to `person.b_day`, so the engine answers one way about
 * calendars rather than two.
 */
export declare function addStep(start: PlainDateTime, step: StepSpec, n: number): PlainDateTime;
/**
 * How many steps fit in `start..end`, counting both ends.
 *
 * Computed rather than counted, because a second-by-second span of a century is
 * a number no loop should walk. A fixed step divides; a calendar one is estimated
 * from the month difference and corrected by at most one, which is what the
 * clamping in `addStep` can cost.
 */
export declare function stepsBetween(start: PlainDateTime, end: PlainDateTime, step: StepSpec): number;
/**
 * True when every row of this step lands on the same weekday.
 *
 * A calendar step does, and so does any whole number of weeks — `14d` as much as
 * `2w`, which the old unit-name test would have missed. A weekday filter over
 * such a step matches every row or none, so it is refused rather than silently
 * producing a full column or an empty one.
 */
export declare function fixesWeekday(step: StepSpec): boolean;
/** What a `weekdays=` may say, for a diagnostic to quote. */
export declare const WEEKDAY_NAMES: readonly string[];
/**
 * `weekdays="mon..fri"` or `weekdays="sun,wed"` — which weekdays an axis keeps.
 *
 * `..` is the range operator everywhere else in the language, so it is the range
 * operator here. A SPAN wraps: `fri..mon` is Friday, Saturday, Sunday, Monday,
 * because a week is a circle and refusing to go round it would make half the
 * spans unwritable. Returns undefined on a name it does not know, so the caller
 * can say which.
 */
export declare function parseWeekdays(raw: string | undefined): ReadonlySet<number> | undefined;
/** The weekday of a date, 0 = Sunday, matching `parseWeekdays`. */
export declare function weekdayOf(value: PlainDateTime): number;
/** A drawn offset: `lo..hi` steps of one unit. `lo === hi` is a fixed offset. */
export interface OffsetSpec {
    readonly lo: number;
    readonly hi: number;
    /** One step, as `addStep` takes it — so the calendar clamping is shared. */
    readonly unit: StepSpec;
}
/** What a `plus=` may say, for a diagnostic to quote. */
export declare const OFFSET_SYNTAX = "7d, 3..10d, 1..3mo, -5..-1d, or a column holding the number: Dur m \u2014 units s, m, h, d, w, mo, y";
export type OffsetResult = {
    readonly ok: true;
    readonly offset: OffsetSpec;
} | {
    readonly ok: false;
    readonly reason: 'syntax' | 'order';
};
/**
 * `plus="3..10d"`, `plus="7d"`, `plus="-5..-1d"`, `plus="1..3mo"`.
 *
 * A bare number means DAYS, matching `step=`. The low bound may exceed neither
 * the high one nor the other way round — `10..3d` is a typo, and silently
 * swapping it would hide the typo rather than report it.
 */
export declare function parseOffset(raw: string | undefined): OffsetResult;
/** `plus="Dur m"`: the distance read from a column, row by row, in one unit. */
export interface ColumnOffset {
    readonly column: string;
    /** `-1` for `plus="-Lead d"`, which measures backwards. */
    readonly sign: 1 | -1;
    readonly unit: StepSpec;
}
/**
 * `plus="Dur m"`, `plus="-Lead d"`, `plus="Shift.hours h"` — how far, from another column.
 *
 * The end of an appointment is its start plus ITS OWN length, and a length that differs per
 * row could not be said: a literal is the same distance on every row, and a range is drawn,
 * not read. A name followed by a unit reads the distance from that column instead. A bare
 * name means days, as a bare number does. `undefined` when `raw` is not this shape — it may
 * still be a literal, which `parseOffset` reads first.
 */
export declare function parseColumnOffset(raw: string | undefined): ColumnOffset | undefined;
/** The source date moved by `n` steps of the offset's unit. */
export declare function applyOffset(start: PlainDateTime, offset: OffsetSpec, n: number): PlainDateTime;
//# sourceMappingURL=calendar.d.ts.map