import type { Period } from "../modules/SelectedAttributeTypes/Period.ta.mjs";
/**
 * @function boundariesOfPeriodOccurrence
 * @summary Returns the bounds of the occurrence in a period in which a point in time occurs.
 * @description
 *
 * This function returns the upper and lower bounds of an occurrence (one of a
 * recurring series of time intervals) in a `Period`, where the specific
 * occurrence is selected by the `point` argument. If the `point` in time does
 * not fall within the bounds of any occurrence of the `Period`, this function
 * returns `null`.
 *
 * ### Architecture
 *
 * This function used to be split into two functions: `startOfPeriod()` and
 * `endOfPeriod()`, but it was merged into one, because there is a somewhat
 * large overhead before the function actually begins traversing the timespan,
 * and because you usually want the end of the period whenever you want the
 * start of the period, anyway.
 *
 * This function returns bounds that may be inaccurate by one second.
 *
 * This function uses local time exclusively.
 *
 * ### Assumptions
 *
 * - Not all possible values for a given unit of precision in a `Period` are specified.
 * - `DayTimeBand`s do not overlap.
 * - `DayTimeBand`s are not adjacent (other than at minima and maxima)
 *
 * ### Algorithm
 *
 * For simplicity, the following will describe only the algorithm for
 * determining the lower bound of an occurrence of a period, since finding the
 * upper bound will be essentially the same, except we increment instead of
 * decrement.
 *
 * 1. Validation.
 * 2. Decode the `Period`'s properties into `Set`s of `number`s.
 * 3. Determine if the point in time falls within any occurrence of the period
 *    at all.
 * 4. Set the point in time to the current minimum; this number will serve as
 *    the currently identified lowest we can go while still staying within the
 *    bounds of an occurrence of the period.
 * 5. We _assume_ that all values for a given unit (e.g. values 1 through 12 for
 *    `months`) are not present (why even specify it if so?). Given this
 *    assumption, it would not be possible to advance more than 1 unit of the
 *    next most coarse denomination of time, which means that the most precise
 *    denomination of time will define the lower bound of the occurrence.
 * 6. With the most precise denomination identified, iterate downwards through
 *    its possible values, updating the current lower bound until the next value
 *    is not permitted.
 * 7. If this countdown results in us reaching 1 for the most precise
 *    denomination of time, we have to keep going, because the span may still be
 *    contiguous into a lower value of a coarser denomination. For instance, if
 *    months 1, 2 and 12 are permitted for all years, and `point` has a month of
 *    2, the occurrence of the period really begins on month 12 of the previous
 *    year. To perform this "rolling back," we check if this "rolled-back" value
 *    still satisfies all of the constraints of the `Period`. If it does, we
 *    continue counting down through the previous day / week / month / year.
 *
 * @param period {Period} The `Period` data structure that defines the period itself.
 * @param point {Date} The point in time used to select an occurence of the `Period`
 * @returns {Date | null} A `Date` whose value is the lower bound of the
 *  period's occurrence if the point in time falls within the bounds of an
 *  occurrence or `null` if it does not fall within the bounds of any occurrence.
 */
export declare function boundariesOfPeriodOccurrence(period: Period, point: Date): [Date, Date] | null;
export default boundariesOfPeriodOccurrence;
//# sourceMappingURL=boundariesOfPeriodOccurrence.d.mts.map