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`](https://crates.io/crates/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`:

```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:

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

## Quick start

```rust
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:

```rust
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

```bash
cargo test
```

## License

MIT — see [`Cargo.toml`](Cargo.toml) and the repository for details.