Struct DatesList

Source

pub struct DatesList { /* private fields */ }

Expand description

Represents a list of calendar dates generated between a start and end date at a specified frequency. Provides methods to retrieve the full list, count, or dates grouped by period.

Implementations§

Source §

impl DatesList

Represents a collection of calendar dates generated according to specific rules.

It can be defined either by a start and end date range or by a start date and a fixed number of periods. It provides methods to retrieve the dates as a flat list, count them, or group them by their natural period (e.g., month, quarter).

This struct handles all calendar dates, including weekends.

§Examples

1. Using DatesList::new (Start and End Date):

use chrono::NaiveDate;
use std::error::Error;
use rustframe::utils::{DatesList, DateFreq};

let start_date = "2023-11-01".to_string(); // Wednesday
let end_date = "2023-11-07".to_string();   // Tuesday
let freq = DateFreq::Daily;

let dates_list = DatesList::new(start_date, end_date, freq);

let expected_dates = vec![
    NaiveDate::from_ymd_opt(2023, 11, 1).unwrap(), // Wed
    NaiveDate::from_ymd_opt(2023, 11, 2).unwrap(), // Thu
    NaiveDate::from_ymd_opt(2023, 11, 3).unwrap(), // Fri
    NaiveDate::from_ymd_opt(2023, 11, 4).unwrap(), // Sat
    NaiveDate::from_ymd_opt(2023, 11, 5).unwrap(), // Sun
    NaiveDate::from_ymd_opt(2023, 11, 6).unwrap(), // Mon
    NaiveDate::from_ymd_opt(2023, 11, 7).unwrap(), // Tue
];

assert_eq!(dates_list.list()?, expected_dates);
assert_eq!(dates_list.count()?, 7);

2. Using DatesList::from_n_periods (Start Date and Count):

use chrono::NaiveDate;
use std::error::Error;
use rustframe::utils::{DatesList, DateFreq};

fn main() -> Result<(), Box<dyn Error>> {
let start_date = "2024-02-28".to_string(); // Wednesday
let freq = DateFreq::WeeklyFriday;
let n_periods = 3;

let dates_list = DatesList::from_n_periods(start_date, freq, n_periods)?;

// The first Friday on or after 2024-02-28 is Mar 1.
// The next two Fridays are Mar 8 and Mar 15.
let expected_dates = vec![
    NaiveDate::from_ymd_opt(2024, 3, 1).unwrap(),
    NaiveDate::from_ymd_opt(2024, 3, 8).unwrap(),
    NaiveDate::from_ymd_opt(2024, 3, 15).unwrap(),
];

assert_eq!(dates_list.list()?, expected_dates);
assert_eq!(dates_list.count()?, 3);
assert_eq!(dates_list.start_date_str(), "2024-02-28"); // Keeps original start string
assert_eq!(dates_list.end_date_str(), "2024-03-15");   // End date is the last generated date

3. Using groups():

use chrono::NaiveDate;
use std::error::Error;
use rustframe::utils::{DatesList, DateFreq};

fn main() -> Result<(), Box<dyn Error>> {
let start_date = "2023-11-20".to_string(); // Mon, Week 47
let end_date = "2023-12-08".to_string();   // Fri, Week 49
let freq = DateFreq::MonthEnd; // Find month-ends

let dates_list = DatesList::new(start_date, end_date, freq);

// Month ends >= Nov 20 and <= Dec 08: Nov 30
let groups = dates_list.groups()?;

assert_eq!(groups.len(), 1); // Only November's end date falls in the range
assert_eq!(groups[0], vec![NaiveDate::from_ymd_opt(2023, 11, 30).unwrap()]); // Nov 2023 group
Ok(())
}

Source

pub fn new(start_date_str: String, end_date_str: String, freq: DateFreq) -> Self

Creates a new DatesList instance defined by a start and end date.

§Arguments

start_date_str - The inclusive start date as a string (e.g., “YYYY-MM-DD”).
end_date_str - The inclusive end date as a string (e.g., “YYYY-MM-DD”).
freq - The frequency for generating dates.

Source

pub fn from_n_periods( start_date_str: String, freq: DateFreq, n_periods: usize, ) -> Result<Self, Box<dyn Error>>

Creates a new DatesList instance defined by a start date, frequency, and the number of periods (dates) to generate.

This calculates the required dates using a DatesGenerator and determines the effective end date based on the last generated date.

§Arguments

start_date_str - The start date as a string (e.g., “YYYY-MM-DD”). The first generated date will be on or after this date.
freq - The frequency for generating dates.
n_periods - The exact number of dates to generate according to the frequency.

§Errors

Returns an error if:

start_date_str cannot be parsed.
n_periods is 0 (as this would result in an empty list and no defined end date).

Source

pub fn list(&self) -> Result<Vec<NaiveDate>, Box<dyn Error>>

Returns the flat list of dates within the specified range and frequency.

The list is guaranteed to be sorted chronologically.

§Errors

Returns an error if the start or end date strings cannot be parsed.

Source

pub fn count(&self) -> Result<usize, Box<dyn Error>>

Returns the count of dates within the specified range and frequency.

§Errors

Returns an error if the start or end date strings cannot be parsed (as it calls list internally).

Source

pub fn groups(&self) -> Result<Vec<Vec<NaiveDate>>, Box<dyn Error>>

Returns a list of date lists, where each inner list contains dates belonging to the same period (determined by frequency).

The outer list (groups) is sorted by period chronologically, and the inner lists (dates within groups) are also sorted chronologically.

For Daily frequency, each date forms its own group. For Weekly frequencies, grouping is by ISO week number. For Monthly, Quarterly, and Yearly frequencies, grouping is by the respective period.