Enum DatePeriod

Source

pub enum DatePeriod {
    Year(u32),
    Quarter(u32, u32),
    Month(u32, u32),
    Daily(u32, u32),
}

Variants§

§

Year(u32)

Represents a yearly period with a specific year.

§

Quarter(u32, u32)

Represents a quarterly period with a specific year and quarter (1-4).

§

Month(u32, u32)

Represents a monthly period with a specific year and month (1-12).

§

Daily(u32, u32)

Represents a daily period with a specific year and day of the year (1-366).

Implementations§

Source §

impl DatePeriod

Source

pub fn year(year: u32) -> Self

Create a new yearly period

§Examples

use range_date::range_type::DatePeriod;

let year = DatePeriod::year(2024);
assert_eq!(year.to_string(), "2024Y");

Source

pub fn quarter(year: u32, quarter: u32) -> Result<Self>

Create a new quarterly period with validation Quarter must be between 1 and 4

§Errors

Returns an error if quarter is not in the range 1..=4.

§Examples

use range_date::range_type::DatePeriod;

let quarter = DatePeriod::quarter(2024, 2).unwrap();
assert_eq!(quarter.to_string(), "2024Q2");

Source

pub fn month(year: u32, month: u32) -> Result<Self>

Create a new monthly period with validation Month must be between 1 and 12

§Errors

Returns an error if month is not in the range 1..=12.

§Examples

use range_date::range_type::DatePeriod;

let month = DatePeriod::month(2024, 5).unwrap();
assert_eq!(month.to_string(), "2024M5");

Source

pub fn daily(year: u32, day: u32) -> Result<Self>

Create a new daily period with validation Day must be between 1 and 366 (accounting for leap years)

§Errors

Returns an error if day is 0 or exceeds the number of days in year (365 for common years, 366 for leap years).

§Examples

use range_date::range_type::DatePeriod;

let daily = DatePeriod::daily(2024, 136).unwrap();
assert_eq!(daily.to_string(), "2024D136");

Source

pub fn parse(s: &str) -> Result<Self>

Parse a DatePeriod from a string representation like "2024Q2" Format: YYYYT[#] where T is period type (Y/Q/M/D) and # is the index (optional for Y)

§Errors

Returns an error if the input is shorter than five characters, the year or index cannot be parsed, the period type is unknown, or the resulting period fails validation (e.g. invalid quarter/month/day).

§Examples

use range_date::range_type::DatePeriod;

let period = DatePeriod::parse("2024Q2").unwrap();
assert_eq!(period.to_string(), "2024Q2");

Source

pub fn from_date_as_year(date: NaiveDate) -> Self

Convert a NaiveDate to a yearly DatePeriod

§Examples

use range_date::range_type::DatePeriod;
use chrono::NaiveDate;

let date = NaiveDate::from_ymd_opt(2024, 5, 15).unwrap();
let year = DatePeriod::from_date_as_year(date);
assert_eq!(year.to_string(), "2024Y");

Source

pub fn from_date_as_quarter(date: NaiveDate) -> Self

Convert a NaiveDate to a quarterly DatePeriod

§Examples

use range_date::range_type::DatePeriod;
use chrono::NaiveDate;

let date = NaiveDate::from_ymd_opt(2024, 5, 15).unwrap();
let quarter = DatePeriod::from_date_as_quarter(date);
assert_eq!(quarter.to_string(), "2024Q2");

Source

pub fn from_date_as_month(date: NaiveDate) -> Self

Convert a NaiveDate to a monthly DatePeriod

§Examples

use range_date::range_type::DatePeriod;
use chrono::NaiveDate;

let date = NaiveDate::from_ymd_opt(2024, 5, 15).unwrap();
let month = DatePeriod::from_date_as_month(date);
assert_eq!(month.to_string(), "2024M5");

Source

pub fn from_date_as_daily(date: NaiveDate) -> Self

Convert a NaiveDate to a daily DatePeriod

§Examples

use range_date::range_type::DatePeriod;
use chrono::NaiveDate;

let date = NaiveDate::from_ymd_opt(2024, 5, 15).unwrap();
let daily = DatePeriod::from_date_as_daily(date);
assert_eq!(daily.to_string(), "2024D136");

Source

pub fn between_date_as_year( start: NaiveDate, end: NaiveDate, ) -> Result<Vec<DatePeriod>>

Generate all yearly periods between two dates (inclusive) Returns an empty vector if start > end

§Errors

This function currently returns Ok in all cases; the Result return type is retained for API symmetry with the other between_date_as_* helpers which may propagate errors from period arithmetic.

§Examples

use range_date::range_type::DatePeriod;
use chrono::NaiveDate;

let start = NaiveDate::from_ymd_opt(2023, 6, 15).unwrap();
let end = NaiveDate::from_ymd_opt(2025, 3, 10).unwrap();
let years = DatePeriod::between_date_as_year(start, end).unwrap();
assert_eq!(years.len(), 3);
assert_eq!(years[0].to_string(), "2023Y");

Source

pub fn between_date_as_quarter( start: NaiveDate, end: NaiveDate, ) -> Result<Vec<DatePeriod>>

Generate all quarterly periods between two dates (inclusive) Returns an empty vector if start > end

§Errors

Returns an error if advancing the quarterly period via DatePeriod::succ fails while iterating from start to end.

§Examples

use range_date::range_type::DatePeriod;
use chrono::NaiveDate;

let start = NaiveDate::from_ymd_opt(2024, 4, 1).unwrap();
let end = NaiveDate::from_ymd_opt(2024, 9, 30).unwrap();
let quarters = DatePeriod::between_date_as_quarter(start, end).unwrap();
assert_eq!(quarters.len(), 2);
assert_eq!(quarters[0].to_string(), "2024Q2");

Source

pub fn between_date_as_month( start: NaiveDate, end: NaiveDate, ) -> Result<Vec<DatePeriod>>

Generate all monthly periods between two dates (inclusive) Returns an empty vector if start > end

§Errors

Returns an error if advancing the monthly period via DatePeriod::succ fails while iterating from start to end.

§Examples

use range_date::range_type::DatePeriod;
use chrono::NaiveDate;

let start = NaiveDate::from_ymd_opt(2024, 2, 1).unwrap();
let end = NaiveDate::from_ymd_opt(2024, 4, 30).unwrap();
let months = DatePeriod::between_date_as_month(start, end).unwrap();
assert_eq!(months.len(), 3);
assert_eq!(months[0].to_string(), "2024M2");

Source

pub fn between_date_as_daily( start: NaiveDate, end: NaiveDate, ) -> Result<Vec<DatePeriod>>

Generate all daily periods between two dates (inclusive) Returns an empty vector if start > end

§Errors

Returns an error if advancing the daily period via DatePeriod::succ fails while iterating from start to end.

§Examples

use range_date::range_type::DatePeriod;
use chrono::NaiveDate;

let start = NaiveDate::from_ymd_opt(2024, 2, 1).unwrap();
let end = NaiveDate::from_ymd_opt(2024, 2, 3).unwrap();
let days = DatePeriod::between_date_as_daily(start, end).unwrap();
assert_eq!(days.len(), 3);
assert_eq!(days[0].to_string(), "2024D32");

Source

pub fn get_first_day(&self) -> Result<NaiveDate>

Get the first day of this period

Returns the first date of the period. Since DatePeriod instances should only be created through validated constructors, this should always succeed.

§Errors

Returns an error if the underlying year/month/day combination cannot be represented as a NaiveDate (for example, a year that overflows i32).

§Examples

use range_date::range_type::DatePeriod;
use chrono::NaiveDate;

let period = DatePeriod::month(2024, 2).unwrap();
let first_day = period.get_first_day().unwrap();
assert_eq!(first_day, NaiveDate::from_ymd_opt(2024, 2, 1).unwrap());

Source

pub fn get_last_day(&self) -> Result<NaiveDate>

Get the last day of this period

Returns the last date of the period.

§Errors

Returns an error if the period’s boundary date cannot be constructed (e.g. month arithmetic overflow for quarter/month periods).

§Examples

use range_date::range_type::DatePeriod;
use chrono::NaiveDate;

let period = DatePeriod::month(2024, 2).unwrap();
let last_day = period.get_last_day().unwrap();
assert_eq!(last_day, NaiveDate::from_ymd_opt(2024, 2, 29).unwrap()); // 2024 is leap year

Source

pub fn contains_date(&self, date: NaiveDate) -> bool

Check if this period contains the given date

Returns false if there’s an error calculating the date boundaries.

§Examples

use range_date::range_type::DatePeriod;
use chrono::NaiveDate;

let period = DatePeriod::month(2024, 2).unwrap();
let date_in_period = NaiveDate::from_ymd_opt(2024, 2, 15).unwrap();
let date_outside_period = NaiveDate::from_ymd_opt(2024, 3, 1).unwrap();
assert!(period.contains_date(date_in_period));
assert!(!period.contains_date(date_outside_period));

Source

pub fn get_year(&self) -> u32

Get the year component

§Examples

use range_date::range_type::DatePeriod;

let period = DatePeriod::month(2024, 2).unwrap();
assert_eq!(period.get_year(), 2024);

Source

pub fn value(&self) -> u32

Get the period value (quarter number, month number, or day number)

§Examples

use range_date::range_type::DatePeriod;

let year_period = DatePeriod::year(2024);
assert_eq!(year_period.value(), 2024);

let month_period = DatePeriod::month(2024, 2).unwrap();
assert_eq!(month_period.value(), 2);

Source

pub fn short_name(&self) -> &'static str

Get the short name of the period type

§Examples

use range_date::range_type::DatePeriod;

let year_period = DatePeriod::year(2024);
assert_eq!(year_period.short_name(), "Y");

let month_period = DatePeriod::month(2024, 2).unwrap();
assert_eq!(month_period.short_name(), "M");

Source

pub fn period_name(&self) -> &'static str

Get the full name of the period type

§Examples

use range_date::range_type::DatePeriod;

let year_period = DatePeriod::year(2024);
assert_eq!(year_period.period_name(), "YEAR");

let month_period = DatePeriod::month(2024, 2).unwrap();
assert_eq!(month_period.period_name(), "MONTH");

Source

pub fn succ(&self) -> Result<DatePeriod>

Get the successor (next) period

§Errors

This function currently never fails in practice; the Result return type is kept for API symmetry with DatePeriod::pred.

§Examples

use range_date::range_type::DatePeriod;

let period = DatePeriod::month(2024, 2).unwrap();
let next_period = period.succ().unwrap();
assert_eq!(next_period.to_string(), "2024M3");

Source

pub fn pred(&self) -> Result<DatePeriod>

Get the predecessor (previous) period

§Errors

Returns an error if the period is already at the beginning of the supported range (year 0) and has no predecessor.

§Examples

use range_date::range_type::DatePeriod;

let period = DatePeriod::month(2024, 2).unwrap();
let prev_period = period.pred().unwrap();
assert_eq!(prev_period.to_string(), "2024M1");

Source

pub fn decompose(&self) -> Vec<DatePeriod>

Decompose this period into its direct sub-periods

§Examples

use range_date::range_type::DatePeriod;

let quarter = DatePeriod::quarter(2024, 1).unwrap();
let months = quarter.decompose();
assert_eq!(months.len(), 3);
assert_eq!(months[0].to_string(), "2024M1");
assert_eq!(months[2].to_string(), "2024M3");

Source

pub fn aggregate(&self) -> DatePeriod

Aggregate this period to its direct parent period

§Examples

use range_date::range_type::DatePeriod;

let daily = DatePeriod::daily(2024, 32).unwrap();
let month = daily.aggregate();
assert_eq!(month, DatePeriod::month(2024, 2).unwrap());

let quarter = DatePeriod::quarter(2024, 2).unwrap();
let year = quarter.aggregate();
assert_eq!(year, DatePeriod::year(2024));

let year_period = DatePeriod::year(2024);
let parent = year_period.aggregate();
assert_eq!(parent, year_period); // Year has no parent, remains the same

Source

pub fn succ_n(&self, n: u32) -> Result<DatePeriod>

Get the successor n periods ahead

Returns the period that is n steps ahead of the current period. If n is 0, returns the current period.

§Errors

This function currently never fails in practice; the Result return type is kept for API symmetry with DatePeriod::pred_n.

§Examples

use range_date::range_type::DatePeriod;

let period = DatePeriod::month(2024, 2).unwrap();
let next_period = period.succ_n(3).unwrap();
assert_eq!(next_period.to_string(), "2024M5");

Source

pub fn pred_n(&self, n: u32) -> Result<DatePeriod>

Get the predecessor n periods back

Returns the period that is n steps back from the current period. If n is 0, returns the current period. Returns an error if going back would result in an invalid year (less than 0).

§Errors

Returns an error if stepping n periods back would underflow past year 0 (i.e. there is no representable period that far in the past).

§Examples

use range_date::range_type::DatePeriod;

let period = DatePeriod::month(2024, 5).unwrap();
let prev_period = period.pred_n(3).unwrap();
assert_eq!(prev_period.to_string(), "2024M2");

Source

pub fn offset_n(&self, n: i32) -> Result<DatePeriod>

Offset this period by n steps

Positive n advances forward, negative n goes backward. If n is 0, returns the current period.

§Errors

Returns an error from the underlying DatePeriod::succ_n / DatePeriod::pred_n call — most notably when a negative offset would underflow past year 0.

§Examples

use range_date::range_type::DatePeriod;

let period = DatePeriod::month(2024, 5).unwrap();
let next_period = period.offset_n(3).unwrap();
assert_eq!(next_period.to_string(), "2024M8");

let prev_period = period.offset_n(-3).unwrap();
assert_eq!(prev_period.to_string(), "2024M2");