sleep_stages_utils library

Utilities for preprocessing sleep segments before rendering.

This file contains pure functions that:

• clip segments to a day window
• merge overlapping segments
• merge adjacent segments of the same stage
• compute per-stage durations and total sleep time

These utilities are UI-agnostic and have no platform dependencies.

Functions

clipSegmentsToDay(List<SleepSegment> segments, DateTime dayStart, {Duration length = const Duration(days: 1)}) → List<SleepSegment>

Returns a new list with segments clipped to [dayStart, dayStart + length].

durationsByStage(List<SleepSegment> segments) → Map<SleepStage, int>

Returns total milliseconds per stage (including Awake).

mergeAdjacentSameStage(List<SleepSegment> segments, {Duration tolerance = Duration.zero}) → List<SleepSegment>

Merges adjacent segments of the same stage when the gap is within tolerance. Useful if your data source produces tiny gaps between same-stage slices.

mergeOverlaps(List<SleepSegment> segments) → List<SleepSegment>

Merges overlaps using a line sweep approach:

totalSleepMsExcludingAwake(List<SleepSegment> segments) → int

Returns total sleep milliseconds excluding Awake.