Why TimestampRound::increment cannot use steps do not divide evenly into 86,400 seconds?

[tisonkun]

The following code snippet failed:

timestamp
  .round(
        TimestampRound::new()
            .smallest(Unit::Millisecond)
            .increment(833)
            .mode(RoundMode::Floor),
    )

called Result::unwrap() on an Err value: increment 833 for rounding timestamp to milliseconds must be 1) less than or equal to 86400000, 2) divide into it evenly and 3) greater than zero

I'm using this method to implement something like a time range query over metric series. And 833 is the step in counting. That said, I'd like to align the timestamp to every 833 ms from the start of the day, and I'm OK that the last time window can be smaller than others.

Is there some reason we forbid this use case? @BurntSushi

[tisonkun]

Seems I can understand some of them now that without evenly division it's hard to tell where the alignment it starts with.

If it starts with UNIX_EPOCH, it may not be aligned with the current hour, then it would be different from user's expectation.

If it starts with the current hour, it's too special also.

If it starts with the current day, one even needs a timezone to determinate the timestamp at the start of the day.

[BurntSushi]

I specifically took this restriction straight from Temporal: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/round#roundingincrement

I didn't really litigate this myself too much, and instead chose to start from a known-good point.

If someone wanted to work through all of the corner cases here for using something other than a divisor into 86,400 seconds and could justify that it has reasonable behavior in all cases, I'd be open to considering that.

But I'd say that if you need something bespoke, especially with a Timestamp, then it might make sense to just roll it yourself. Timestamp is probably the easiest thing to do it for since it's just a 96-bit integer.

[tisonkun]

Yes. I write a function for aligning with UNIX_EPOCH as a starting point:

fn round_timestamp(
    ts_nanos: i64,
    n: i64,
    unit_nanos: i64,
    mode: jiff::RoundMode,
) -> Result<i64, String> {
    if !n.is_positive() {
        return Err(format!("expected `n` to be positive, but got {n}"));
    }

    let quantity = ts_nanos;
    let Some(increment) = n.checked_mul(unit_nanos) else {
        return Err(format!("step overflow: {n} * {unit_nanos}"));
    };

    let mut quotient = quantity.wrapping_div(increment);
    let remainder = quantity.wrapping_rem(increment);

    if remainder == 0 {
        return Ok(ts_nanos);
    }

    let sign = if remainder < 0 { -1 } else { 1 };
    match mode {
        jiff::RoundMode::Floor => {
            if sign < 0 {
                quotient += sign;
            }
        }
        jiff::RoundMode::Ceil => {
            if sign > 0 {
                quotient += sign;
            }
        }
        _ => unreachable!("unexpected round mode: {mode:?}"),
    }

    // see also https://github.com/BurntSushi/jiff/blob/f21740ee/src/util/round/mode.rs#L172-L177
    let result = quotient.saturating_mul(increment);
    Ok(result)
}