chrono-intervals: Grouped time intervals for Rust

Create chrono time intervals as "per-day", "per-week" etc.

Usage

The most convenient way to get intervals is by creating an IntervalGenerator.

```rust use chrono::{DateTime, TimeZone, Utc}; use chrono_intervals::{IntervalGenerator};

let begin = DateTime::parsefromrfc3339("2022-06-25T08:23:45.000000Z").unwrap(); let end = DateTime::parsefromrfc3339("2022-06-27T09:31:12.000000Z").unwrap();

let dailyintervals = IntervalGenerator::new().getintervals(begin, end);

asserteq!( dailyintervals, vec![ ( Utc.ymd(2022, 6, 25).andhms(0, 0, 0), Utc.ymd(2022, 6, 25).andhmsmilli(23, 59, 59, 999), ), ( Utc.ymd(2022, 6, 26).andhms(0, 0, 0), Utc.ymd(2022, 6, 26).andhmsmilli(23, 59, 59, 999), ), ( Utc.ymd(2022, 6, 27).andhms(0, 0, 0), Utc.ymd(2022, 6, 27).andhms_milli(23, 59, 59, 999), ), ] ); ```

The IntervalGenerator can be configured in many ways. Let's look at an example of retrieving monthly intervals but in the Pacific Daylight Time (PDT) timezone:

```rust use chrono::{DateTime, TimeZone, Utc}; use chrono_intervals::{Grouping, IntervalGenerator};

// We want to obtain monthly intervals for month in PDT instead of in UTC. let begin = DateTime::parsefromrfc3339("2022-06-10T12:23:45.000000-07:00").unwrap(); let end = DateTime::parsefromrfc3339("2022-08-26T12:23:45.000000-07:00").unwrap();

// PDT is 7h behind of UTC (towards the west), thus the // offset_west_seconds are 7*3600 let pdtoffsetwest_seconds = 7 * 3600;

let monthlyintervals = IntervalGenerator::new() .withgrouping(Grouping::PerMonth) .withoffsetwestsecs(pdtoffsetwestseconds) .get_intervals(begin, end);

// In UTC, we expect the intervals to start 7h after the month boundary. asserteq!( monthlyintervals, vec![ ( Utc.ymd(2022, 6, 1).andhms(7, 0, 0), Utc.ymd(2022, 7, 1).andhmsmilli(6, 59, 59, 999), ), ( Utc.ymd(2022, 7, 1).andhms(7, 0, 0), Utc.ymd(2022, 8, 1).andhmsmilli(6, 59, 59, 999), ), ( Utc.ymd(2022, 8, 1).andhms(7, 0, 0), Utc.ymd(2022, 9, 1).andhms_milli(6, 59, 59, 999), ), ] ); ```

Configuration options and defaults

Here is an overview of configurable options and their defaults:

• The interval grouping: You can choose any grouping represented in, Grouping, the default is Grouping::PerDay.
• The time span between the end of one interval and the beginning of the next (precision): This defaults to 1ms but can be overwritten by passing an arbitrary chrono::Duration. We do not check that the precision is reasonable. You probably want to set it to the smallest duration that you still consider, e.g. milliseconds or microseconds.
• The offset in seconds towards the west of your local timezone: If you want time intervals for e.g. Pacific Daylight Time (PDT) which is at GMT-7, you have to pass 7*3600, so the time difference in seconds with a shift towards the west as positive values. Central European Time (CET) at GMT+1 for example would need -3600 offset seconds towards the west.
• Whether the first interval extends to before begin or not: By default, the first interval will start on the boundary before begin. You can switch this off if you want only full intervals that are strickly after begin.
• Whether the last interval extends to after end or not: By default, the last interval will end at the boundary after end. You can switch this off if you want only full intervals that are strickly before end.

Let's look at an example with all configuration options used:

```rust use chrono::{DateTime, Duration, TimeZone, Utc}; use chrono_intervals::{Grouping, IntervalGenerator};

let begin = DateTime::parsefromrfc3339("2022-10-02T08:23:45.000000Z").unwrap(); let end = DateTime::parsefromrfc3339("2022-10-18T08:23:45.000000Z").unwrap();

let intergen = IntervalGenerator::new() .withgrouping(Grouping::PerWeek) .withprecision(Duration::microseconds(1)) .withoffsetwestsecs(-3600) .withoutextendedbegin() .withoutextendedend();

let weeklyintervals = intergen.get_intervals(begin, end);

asserteq!( weeklyintervals, vec![ ( Utc.ymd(2022, 10, 2).andhms(23, 0, 0), Utc.ymd(2022, 10, 9).andhmsmicro(22, 59, 59, 999999), ), ( Utc.ymd(2022, 10, 9).andhms(23, 0, 0), Utc.ymd(2022, 10, 16).andhmsmicro(22, 59, 59, 999999), ), ] ); ```

Using functions instead of the generator

The generator is the most convenient way. However you can also use two different functions to obtain intervals:

• get_extended_utc_intervals returns grouped intervals which enclose the begin and end and have a precision of 1ms. This is pretty close to the default IntervalGenerator behavior, just that you have to specify a Grouping.
• get_utc_intervals_opts returns grouped intervals and allows to specify all options that the generator also accepts.

Examples

Get daily intervals between two times with default options:

```rust use chrono::{DateTime, TimeZone, Utc}; use chronointervals::{Grouping, getextendedutcintervals};

let begin = DateTime::parsefromrfc3339("2022-06-25T08:23:45.000000Z").unwrap(); let end = DateTime::parsefromrfc3339("2022-06-27T09:31:12.000000Z").unwrap();

let dailyintervals = getextendedutcintervals(begin, end, &Grouping::PerDay, 0);

asserteq!( dailyintervals, vec![ ( Utc.ymd(2022, 6, 25).andhms(0, 0, 0), Utc.ymd(2022, 6, 25).andhmsmilli(23, 59, 59, 999), ), ( Utc.ymd(2022, 6, 26).andhms(0, 0, 0), Utc.ymd(2022, 6, 26).andhmsmilli(23, 59, 59, 999), ), ( Utc.ymd(2022, 6, 27).andhms(0, 0, 0), Utc.ymd(2022, 6, 27).andhms_milli(23, 59, 59, 999), ), ] ); ```

Get monthly intervals with default options in the Pacific Daylight Time (PDT) timezone:

```rust use chrono::{DateTime, TimeZone, Utc}; use chronointervals::{Grouping, getextendedutcintervals};

// We want to obtain monthly intervals for months in PDT instead of in UTC. let begin = DateTime::parsefromrfc3339("2022-06-10T12:23:45.000000-07:00").unwrap(); let end = DateTime::parsefromrfc3339("2022-08-26T12:23:45.000000-07:00").unwrap();

// PDT is 7h behind of UTC (towards the west), thus the // offset_west_seconds are 7*3600 let pdtoffsetwest_seconds = 7 * 3600;

let monthlyintervals = getextendedutcintervals(begin, end, &Grouping::PerMonth, pdtoffsetwest_seconds);

// In UTC, we expect the intervals to start 7h after the day boundary. asserteq!( monthlyintervals, vec![ ( Utc.ymd(2022, 6, 1).andhms(7, 0, 0), Utc.ymd(2022, 7, 1).andhmsmilli(6, 59, 59, 999), ), ( Utc.ymd(2022, 7, 1).andhms(7, 0, 0), Utc.ymd(2022, 8, 1).andhmsmilli(6, 59, 59, 999), ), ( Utc.ymd(2022, 8, 1).andhms(7, 0, 0), Utc.ymd(2022, 9, 1).andhms_milli(6, 59, 59, 999), ), ] ); ```

Specify options for get_utc_intervals_opts:

```rust use chrono::{DateTime, Duration, TimeZone, Utc}; use chronointervals::{Grouping, getutcintervalsopts};

let begin = DateTime::parsefromrfc3339("2022-06-15T08:23:45.000000Z").unwrap(); let end = DateTime::parsefromrfc3339("2022-06-30T09:31:12.000000Z").unwrap();

let weeklyintervals = getutcintervalsopts( begin, end, &Grouping::PerWeek, 0, Duration::microseconds(1), // interval end is 1µs before the next false, // start on the boundary after start true, // end at the boundary after end );

asserteq!( weeklyintervals, vec![ ( // First interval begins after begin Utc.ymd(2022, 6, 20).andhms(0, 0, 0), Utc.ymd(2022, 6, 26).andhmsmicro(23, 59, 59, 999999), ), ( Utc.ymd(2022, 6, 27).andhms(0, 0, 0), // Last interval ends after end Utc.ymd(2022, 7, 3).andhmsmicro(23, 59, 59, 999999), ), ] ); ```