From 243f1a896366167f6608150094917da2d242e4c4 Mon Sep 17 00:00:00 2001 From: Hlars Date: Mon, 4 Aug 2025 21:20:28 +0200 Subject: [PATCH] minor changes and documentation --- .DS_Store | Bin 0 -> 6148 bytes .gitignore | 1 + .vscode/tasks.json | 16 +++++++++ src/countries/mod.rs | 14 ++++++++ src/holiday.rs | 6 ---- src/lib.rs | 76 ++++++++++++++++++++++++++++++++++++++++--- 6 files changed, 102 insertions(+), 11 deletions(-) create mode 100644 .DS_Store create mode 100644 .vscode/tasks.json diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..ee771938787a1bb39cadddab0eb4f7463f2ead2b GIT binary patch literal 6148 zcmeHKI|>3Z5S>vG!N$@uSMUZw^aOhW1;s`bM6I{-TprCgpGH?ZZR8D1UNV`NkXP*N zh=|TFo0-T&L`HB!x!KS)+c)o6FCz+si0p zwti-h{ zq5pp-aYY5Fz+Wk#gGIBL<4IXtJCCzkTi`3W<=o+Bm^%f7mt&xpV=Sy3PdzE}ip{ZK V6Wc(iBkpt{e+En!8Ws4p0uNe26{i3I literal 0 HcmV?d00001 diff --git a/.gitignore b/.gitignore index ea8c4bf..0b745e2 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ /target +.env \ No newline at end of file diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..bfe544f --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,16 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "type": "shell", + "label": "Package and Upload Documentation", + "command": "source ./.env && CRATE_NAME=$(cargo metadata --no-deps --format-version 1 | jq -r '.packages[0].name') && CRATE_VERSION=$(cargo metadata --no-deps --format-version 1 | jq -r '.packages[0].version') && cargo doc --no-deps && cd ./target && zip -r doc.zip ./doc && curl -v -H \"Authorization: ${KELLNR_TOKEN}\" https://crates.esteil.dedyn.io/api/v1/docs/$CRATE_NAME/$CRATE_VERSION --upload-file ./doc.zip", + "args": [], + "problemMatcher": [], + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} \ No newline at end of file diff --git a/src/countries/mod.rs b/src/countries/mod.rs index 2221e51..766cd12 100644 --- a/src/countries/mod.rs +++ b/src/countries/mod.rs @@ -17,10 +17,24 @@ where fn new() -> (String, Vec); } +/// Represents country codes for holiday calculations +/// +/// # Variants +/// * `DE` - Germany +/// * `US` - United States +/// * `FR` - France +/// +/// # Purpose +/// Provides a type-safe way to specify countries for holiday-related operations #[derive(Debug, Clone, Copy, Hash, PartialEq, Eq)] pub enum CountryCode { + /// Germany DE, + + /// The United States US, + + /// France FR, } diff --git a/src/holiday.rs b/src/holiday.rs index b39e268..9445f3e 100644 --- a/src/holiday.rs +++ b/src/holiday.rs @@ -75,12 +75,6 @@ impl Holiday { } } -#[derive(Debug, Clone)] -pub struct HolidayDate { - pub name: String, - pub date: Date, -} - #[cfg(test)] mod test { use crate::holiday::Activity; diff --git a/src/lib.rs b/src/lib.rs index b080279..41a0dc5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,21 +1,28 @@ use std::collections::HashMap; -use time::Date; +pub use time::Date; -use crate::{ - countries::CountryCode, - holiday::{HDate, Holiday, HolidayDate}, -}; +use crate::holiday::{HDate, Holiday}; mod countries; mod holiday; pub(crate) mod utils; +pub use countries::CountryCode; + +/// A struct to manage and check holidays for different countries pub struct HolidayChecker { countries: HashMap)>, } impl HolidayChecker { + /// Creates a new HolidayChecker with holidays for specified countries + /// + /// # Arguments + /// * `countries` - A vector of country codes to initialize holidays for + /// + /// # Returns + /// A new HolidayChecker instance with holidays for the specified countries pub fn new(countries: Vec) -> Self { let mut map = HashMap::new(); @@ -27,6 +34,15 @@ impl HolidayChecker { Self { countries: map } } + /// Retrieves a list of holidays for a specific country, state, and year + /// + /// # Arguments + /// * `country` - The country code + /// * `state` - The specific state within the country + /// * `year` - The year to retrieve holidays for + /// + /// # Returns + /// A vector of HolidayDate for the specified country, state, and year pub fn holiday_list(&self, country: CountryCode, state: &str, year: i32) -> Vec { Self::get_years_holidays( self.countries @@ -37,6 +53,15 @@ impl HolidayChecker { ) } + /// Counts the number of holidays for a specific country, state, and year + /// + /// # Arguments + /// * `country` - The country code + /// * `state` - The specific state within the country + /// * `year` - The year to count holidays for + /// + /// # Returns + /// The number of holidays for the specified country, state, and year pub fn number_of_holidays(&self, country: CountryCode, state: &str, year: i32) -> usize { Self::get_years_holidays( self.countries @@ -48,6 +73,16 @@ impl HolidayChecker { .len() } + /// Checks if a specific date is a holiday for a given country, state, and year + /// + /// # Arguments + /// * `country` - The country code + /// * `state` - The specific state within the country + /// * `year` - The year to check + /// * `date` - The specific date to check + /// + /// # Returns + /// An Option containing the HolidayDate if the date is a holiday, None otherwise pub fn is_holiday( &self, country: CountryCode, @@ -70,6 +105,15 @@ impl HolidayChecker { }) } + /// Internal method to retrieve holidays for a specific year and state + /// + /// # Arguments + /// * `holidays` - A tuple containing all states identifier and list of holidays + /// * `year` - The year to retrieve holidays for + /// * `state` - The specific state to filter holidays + /// + /// # Returns + /// A vector of HolidayDate for the specified year and state fn get_years_holidays( holidays: &(String, Vec), year: i32, @@ -103,3 +147,25 @@ impl HolidayChecker { .collect() } } + +/// Represents a specific holiday with its name and date +/// +/// # Fields +/// * `name` - The name of the holiday (e.g., "Christmas", "Independence Day") +/// * `date` - The specific date when the holiday occurs +/// +/// # Examples +/// ```rust +/// let christmas = HolidayDate { +/// name: String::from("Christmas"), +/// date: Date::from_calendar_date(2023, Month::December, 25).unwrap() +/// }; +/// ``` +#[derive(Debug, Clone)] +pub struct HolidayDate { + /// The name of the holiday + pub name: String, + + /// The date when the holiday is celebrated + pub date: Date, +}