time

def times(
    resolution: timedelta = timedelta(minutes=5),
    span: timedelta = timedelta(hours=24),
    start: datetime | None = None,
) -> cg.Array[datetime]:
    """Generate candidate timestamps over a time span.

    Args:
        resolution: Time between candidate slots. Defaults to 5 minutes.
        span: Total time span to cover. Defaults to 24 hours.
        start: Starting time. Defaults to now.

    Returns:
        List of datetime objects at the given resolution.
    """
    if start is None:
        start = datetime.now()

    times = []
    end = start + span
    current = start

    while current < end:
        times.append(current)
        current += resolution

    return cg.Array(times)

def times_of_day(
    hours: list[int],
    start: datetime | None = None,
) -> cg.Array[datetime]:
    """Generate candidate time slots at specific hours of the day.

    Creates slots for today (the date of `start`) at the specified hours,
    returning only those strictly after `start`. Slots already in the past
    are dropped, so late in the day the result may be empty.

    Args:
        hours: List of hours (0-23) to generate slots for.
        start: Starting time. Defaults to now.

    Returns:
        List of datetime objects, sorted chronologically.

    Example:
        ```python
        times = cgsh.forecast.times_of_day(hours=[10, 12, 14, 16, 18, 20, 22])
        chosen = reservations.reserve(user_id, among=times)
        ```
    """
    if start is None:
        start = datetime.now()

    slots = []
    today = start.date()

    for hour in hours:
        slot_time = datetime.combine(today, datetime.min.time()).replace(hour=hour)

        if slot_time > start:
            slots.append(slot_time)

    # Sort by date
    slots.sort(key=lambda s: s)
    return cg.Array(slots)