diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..ee77193 Binary files /dev/null and b/.DS_Store differ 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, +}