Calendar Overlap and Common Gap Finder

Description

Compare bounded supplied busy calendars over an explicit half-open epoch-millisecond window, deduplicating same-calendar overlap and delegating interval cells to report common gaps, overlaps and per-calendar occupied duration.

A busy calendar is a collection of time intervals. A common free span has no busy calendar, while an overlap here means at least two distinct calendars are busy. Half-open intervals include their start and exclude their end, so touching events do not overlap.

When to use this tool

Use this tool when you need the stated calculation or classification with explicit inputs, intermediate evidence, and boundary conventions.

How to use the tool and how it works

Supply calendars, windowStartEpochMs, windowEndEpochMs in the field shapes below.
Run the calculation. Correct format, shape, range, or undefined-statistic errors before interpreting a result.
Read segments, commonFree, overlaps, calendarBusyDurationMs. Use the conventions below.

Clip supplied busy intervals to the comparison window, ignore zero-duration clipped intervals, and delegate coverage cells. Deduplicate active calendar IDs, merge adjacent equal-ID segments, and collect common-free spans, spans with at least two distinct busy calendars, and per-calendar union durations.^[1]

Delegated operations used for this result: interval coverage multiplicity. Their calculation or parsing conventions apply to the corresponding result fields.^[2]

Input field	Meaning and units	Accepted input
calendars	Opaque busy intervals [start,end); at most 16 calendars and 127 total supplied intervals. Duplicate events within one calendar do not count as different calendars.	Required. Array of Object; no unknown keys.; maximum items 16.
calendars[].id	Literal identifier used independently of display labels.	Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 64.
calendars[].intervals	Pairs of absolute epoch milliseconds [start,end), interpreted as busy.	Required. Array of Array of Safe integer.; minimum items 2; maximum items 2.; maximum items 127.
windowStartEpochMs	Absolute epoch milliseconds; timezone/recurrence normalization is caller-owned.	Required. Safe integer.
windowEndEpochMs	Absolute epoch milliseconds; timezone/recurrence normalization is caller-owned.	Required. Safe integer.

Output field	Interpretation	Returned shape
segments	Segments	Required. Array of Object; no unknown keys.; minimum items 1; maximum items 255.
segments[].startEpochMs	Absolute epoch milliseconds; timezone/recurrence normalization is caller-owned.	Required. Safe integer.
segments[].endEpochMs	Absolute epoch milliseconds; timezone/recurrence normalization is caller-owned.	Required. Safe integer.
segments[].durationMs	Occupied or segment duration in milliseconds, as identified by its parent record.	Required. Safe integer; minimum 1.
segments[].activeCalendarIds	Active Calendar Ids	Required. Array of Text; minimum UTF-16 length 1; maximum UTF-16 length 64.; maximum items 16.
commonFree	Maximal adjacent spans with no active calendar, in epoch milliseconds.	Required. Array of Array of Safe integer.; minimum items 2; maximum items 2.; maximum items 255.
overlaps	Maximal adjacent spans with two or more distinct active calendar IDs.	Required. Array of Array of Safe integer.; minimum items 2; maximum items 2.; maximum items 255.
calendarBusyDurationMs	Calendar Busy Duration Ms	Required. Array of Object; no unknown keys.; maximum items 16.
calendarBusyDurationMs[].id	Literal identifier used independently of display labels.	Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 64.
calendarBusyDurationMs[].durationMs	Occupied or segment duration in milliseconds, as identified by its parent record.	Required. Safe integer; minimum 0.

json

{
  "input": {
    "calendars": [
      {
        "id": "alice",
        "intervals": [
          [
            1792400400000,
            1792404000000
          ],
          [
            1792407600000,
            1792411200000
          ]
        ]
      },
      {
        "id": "bob",
        "intervals": [
          [
            1792402200000,
            1792407600000
          ]
        ]
      }
    ],
    "windowStartEpochMs": 1792400400000,
    "windowEndEpochMs": 1792414800000
  },
  "output": {
    "segments": [
      {
        "startEpochMs": 1792400400000,
        "endEpochMs": 1792402200000,
        "durationMs": 1800000,
        "activeCalendarIds": [
          "alice"
        ]
      },
      {
        "startEpochMs": 1792402200000,
        "endEpochMs": 1792404000000,
        "durationMs": 1800000,
        "activeCalendarIds": [
          "alice",
          "bob"
        ]
      },
      {
        "startEpochMs": 1792404000000,
        "endEpochMs": 1792407600000,
        "durationMs": 3600000,
        "activeCalendarIds": [
          "bob"
        ]
      },
      {
        "startEpochMs": 1792407600000,
        "endEpochMs": 1792411200000,
        "durationMs": 3600000,
        "activeCalendarIds": [
          "alice"
        ]
      },
      {
        "startEpochMs": 1792411200000,
        "endEpochMs": 1792414800000,
        "durationMs": 3600000,
        "activeCalendarIds": []
      }
    ],
    "commonFree": [
      [
        1792411200000,
        1792414800000
      ]
    ],
    "overlaps": [
      [
        1792402200000,
        1792404000000
      ]
    ],
    "calendarBusyDurationMs": [
      {
        "id": "alice",
        "durationMs": 7200000
      },
      {
        "id": "bob",
        "durationMs": 5400000
      }
    ]
  }
}

Limitations and assumptions

All times are absolute safe-integer epoch milliseconds and intervals are half-open. Duplicate events within one calendar do not create a cross-calendar overlap. The caller handles time zones and recurrence; no calendar account is accessed.
The field tables state structural bounds; cross-field constraints and bounded search or output budgets also apply. Unknown keys are rejected where the object contract disallows them. Input errors are distinct from null fields and deliberate invalid controls in a successful output.

Alternative or Complementary methods

Choose the statistic according to the question and data conventions. Inspect the supplied series or matrix and the stated assumptions before comparing outputs from implementations with different defaults.

References

Tool behavior and example: Calendar Overlap and Common Gap Finder — tool.io
Calculation or validation: interval/interval-coverage-multiplicity — tool.io

Similar or alternative tools

Random Calendar Event Set Generator
Generate exact-count date-only half-open events inside a supplied window, choosing feasible bounded durations sequentially and optionally distributing nonnegative gaps without overlaps; allowed-overlap mode uses the existing random date core, not a uniform draw over all event sets.
Random Booking Occupancy Dataset Generator
Construct synthetic half-open day reservations within resource capacity, with daily occupancy, overlap evidence, and optional labeled over-capacity controls.