date_range_rs 0.2.0

A collection of date range types
Documentation

Date Range Utilities

A Rust crate for building and navigating inclusive date, time, and date-time ranges — yearly, semi-annual, quarterly, monthly, semi-monthly, bi-weekly, and weekly — built on top of joda_rs (LocalDate, LocalTime, LocalDateTime).

Highlights:

  • Inclusive ranges (start and end dates are both included)
  • Construct a period from either its start date or its end date
  • Navigate to the prior or next adjacent period with consistent, leap-year-aware logic
  • Query ranges: contains_date, contains_range, overlaps, range_containing_date, ranges_before/ranges_after/ranges_window, and more
  • TimeRange and DateTimeRange for time-of-day and timestamp spans, including overlap/duration calculations

Installation

Add the crate to your Cargo.toml:

[dependencies]
date_range_rs = "0.1"
joda_rs = "0.1"

If you're developing locally against an unpublished sibling crate, use a path dependency instead:

[dependencies]
date_range_rs = { path = "./path/to/date-range-rs" }
joda_rs = "0.1"

Quick start

use date_range_rs::AnnualDateRange;
use joda_rs::LocalDate;

fn main() {
    // Create a range for calendar year 2023 from its start date
    let dr = AnnualDateRange::with_start_date(LocalDate::of(2023, 1, 1));
    assert_eq!(dr.start_date(), LocalDate::of(2023, 1, 1));
    assert_eq!(dr.end_date(), LocalDate::of(2023, 12, 31));

    // Navigate to adjacent years
    let prior = dr.prior();
    let next = dr.next();
    assert_eq!(prior.start_date(), LocalDate::of(2022, 1, 1));
    assert_eq!(next.end_date(), LocalDate::of(2024, 12, 31));

    // Leap years are handled automatically: a range starting on Feb 29
    // ends on Feb 28 of the following (non-leap) year.
    let leap_span = AnnualDateRange::with_start_date(LocalDate::of(2020, 2, 29));
    assert_eq!(leap_span.end_date(), LocalDate::of(2021, 2, 28));
}

Date range types

Every period type builds a DateRange, so they all share the same query and navigation API.

Type Construct from
AnnualDateRange with_start_date / with_end_date
SemiAnnualDateRange with_start_date / with_end_date
QuarterlyDateRange with_start_date / with_end_date
MonthlyDateRange with_end_date_on_first / with_end_date_and_start_day
SemiMonthlyDateRange with_end_date
BiWeeklyDateRange with_start_date / with_end_date / with_target_date
WeeklyDateRange with_start_date / with_end_date / with_target_date

Each of these returns a DateRange, which exposes:

  • start_date(), end_date(), len() — the bounds and inclusive day count
  • iter(), dates(), date_at(index), dates_for_day(day) — iterate or collect the dates in the range
  • contains_date(date), contains_range(other), overlaps(other), overlaps_any(others) — membership and overlap checks
  • prior(), next(), prior_n(n), next_n(n) — move to adjacent ranges
  • range_containing_date(date) — find the range (walking prior/next) that contains a date
  • ranges_before(n), ranges_before_inclusive(n), ranges_after(n), ranges_after_inclusive(n), ranges_window(before, after), ranges_containing_span(from, to) — build lists of adjacent ranges

TimeRange and DateTimeRange

TimeRange (time-of-day spans) and DateTimeRange (timestamp spans) provide the same style of API for non-date-only ranges:

use date_range_rs::DateTimeRange;
use joda_rs::{LocalDateTime, LocalTime, LocalDate};

let workday = DateTimeRange::from_time_range_on_date(
    LocalTime::of(9, 0, 0),
    LocalTime::of(17, 0, 0),
    LocalDate::of(2023, 3, 10),
);
assert!(workday.contains(LocalDateTime::of(2023, 3, 10, 12, 0, 0)));

DateTimeRange also supports overlaps, overlaps_exclusive, overlaps_completely, overlap_range, overlap_duration, and duration(); TimeRange supports overlaps and duration(), including midnight-crossing spans.

Testing

cargo test

License

MIT — see Cargo.toml and the repository for details.