recurring_event 0.1.3

//! # Overview
//!
//! This crate provides a set of components that describe the properties and behaviors of recurring events.
//!
//! The typical usage of this crate is to create a recurring event, define its recurrences rules
//! (e.g. happens on every tuesday, happens on the 15th of the month) and then get from the event the next date(s) that match the rules.
//!
//! Four periodicities are currently supported (daily, weekly, monthly and yearly) through four types :
//! [`DailyEvent`], [`WeeklyEvent`], [`MonthlyEvent`] and [`YearlyEvent`].
//!
//! ## Example of using a yearly event
//!
//! ```
//! use recurring_event::{MonthlyWeekdayOrdinal, Ordinal, Recurrent, YearlyEvent,
//!     time::{Month, OffsetDateTime, Weekday, macros::datetime}};
//!
//! // This yearly event starts recurring on the 14th of November 2018.
//! let mut event = YearlyEvent::new(datetime!(2018-11-14 00:00 UTC));
//!
//! // It's an event that recurs every four years.
//! event.update_frequency(4);
//!
//! // On a year, the event happens on every Monday and Thursday of February.
//! event.insert_weekday(Weekday::Monday, Month::February);
//! event.insert_weekday(Weekday::Thursday, Month::February);
//!
//! // And also on the 7th and 15th of February.
//! event.insert_monthly_day_ordinal(7, Month::February);
//! event.insert_monthly_day_ordinal(25, Month::February);
//!
//! // And also on the second Tuesday and the last Sunday of February.
//! event.insert_monthly_weekday_ordinal(
//!     MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Tuesday),
//!     Month::February);
//! event.insert_monthly_weekday_ordinal(
//!     MonthlyWeekdayOrdinal::new(Ordinal::Last, Weekday::Sunday),
//!     Month::February);
//!
//! // The event also happens on August, every Tuesday and Saturday.
//! event.insert_weekday(Weekday::Tuesday, Month::August);
//! event.insert_weekday(Weekday::Saturday, Month::August);
//!
//! // And on the 13th and 29th of August.
//! event.insert_monthly_day_ordinal(13, Month::August);
//! event.insert_monthly_day_ordinal(29, Month::August);
//!
//! // And on the first Wednesday and third Friday of August.
//! event.insert_monthly_weekday_ordinal(
//!     MonthlyWeekdayOrdinal::new(Ordinal::First, Weekday::Wednesday),
//!     Month::August);
//! event.insert_monthly_weekday_ordinal(
//!     MonthlyWeekdayOrdinal::new(Ordinal::Third, Weekday::Friday),
//!     Month::August);
//!
//! // One possibility for getting the next occurrence dates is to take advantage of the fact
//! // that a YearlyEvent implement the Iterator trait.
//! // Let's get the next fourty occurrence dates !
//! let next_occurrences_dates: Vec<OffsetDateTime> = event.take(40).collect();
//!
//! let expected_dates = vec![datetime!(2022-02-03 00:00 UTC),
//!     datetime!(2022-02-07 00:00 UTC),
//!     datetime!(2022-02-08 00:00 UTC),
//!     datetime!(2022-02-10 00:00 UTC),
//!     datetime!(2022-02-14 00:00 UTC),
//!     datetime!(2022-02-17 00:00 UTC),
//!     datetime!(2022-02-21 00:00 UTC),
//!     datetime!(2022-02-24 00:00 UTC),
//!     datetime!(2022-02-25 00:00 UTC),
//!     datetime!(2022-02-27 00:00 UTC),
//!     datetime!(2022-02-28 00:00 UTC),
//!     datetime!(2022-08-02 00:00 UTC),
//!     datetime!(2022-08-03 00:00 UTC),
//!     datetime!(2022-08-06 00:00 UTC),
//!     datetime!(2022-08-09 00:00 UTC),
//!     datetime!(2022-08-13 00:00 UTC),
//!     datetime!(2022-08-16 00:00 UTC),
//!     datetime!(2022-08-19 00:00 UTC),
//!     datetime!(2022-08-20 00:00 UTC),
//!     datetime!(2022-08-23 00:00 UTC),
//!     datetime!(2022-08-27 00:00 UTC),
//!     datetime!(2022-08-29 00:00 UTC),
//!     datetime!(2022-08-30 00:00 UTC),
//!     datetime!(2026-02-02 00:00 UTC),
//!     datetime!(2026-02-05 00:00 UTC),
//!     datetime!(2026-02-07 00:00 UTC),
//!     datetime!(2026-02-09 00:00 UTC),
//!     datetime!(2026-02-10 00:00 UTC),
//!     datetime!(2026-02-12 00:00 UTC),
//!     datetime!(2026-02-16 00:00 UTC),
//!     datetime!(2026-02-19 00:00 UTC),
//!     datetime!(2026-02-22 00:00 UTC),
//!     datetime!(2026-02-23 00:00 UTC),
//!     datetime!(2026-02-25 00:00 UTC),
//!     datetime!(2026-02-26 00:00 UTC),
//!     datetime!(2026-08-01 00:00 UTC),
//!     datetime!(2026-08-04 00:00 UTC),
//!     datetime!(2026-08-05 00:00 UTC),
//!     datetime!(2026-08-08 00:00 UTC),
//!     datetime!(2026-08-11 00:00 UTC)];
//!
//! assert_eq!(expected_dates, next_occurrences_dates)
//! ```
//!
//! # `time` crate
//!
//! This crate uses the [`time`] crate, in particular the [`OffsetDateTime`], [`Month`], and [`Weekday`] types.
//!
//! An [`OffsetDateTime`] stores time and offset (i.e. timezone) information. Currently, this crate doesn't make any use of them.
//! It is available for your code, should you need to manage specific time and offset in your event (by using the [`update_current_date`] method).
//!
//! # `serde` and `typetag` crates
//!
//! (De)serialization of event types is available thanks to [`serde`], and (de)serialization of `Box<dyn Recurrent>` trait object thanks to [`typetag`].
//!
//! [`datetime!`]: time::macros
//! [`Month`]: time::Month
//! [`OffsetDateTime`]: time::OffsetDateTime
//! [`update_current_date`]: Recurrent::update_current_date
//! [`Weekday`]: time::Weekday


mod calendar;
pub mod error;
mod matcher;
mod utility;
mod recurrences;

pub extern crate time;

use core::any::Any;
use std::collections::{HashMap, hash_map::Keys, hash_set::Iter};
use std::fmt::{self, Display};

use serde::{Serialize, Deserialize};
use time::{Duration, Month, Weekday, OffsetDateTime};

use crate::error::Error;
use crate::matcher::EventRecurrences;
use crate::recurrences::Recurrences;

/// Provides the core methods for [`DailyEvent`], [`WeeklyEvent`], [`MonthlyEvent`] and [`YearlyEvent`].
///
/// # Scope
///
/// This trait _must be in scope_ for the events to be able to call the trait methods.
///
/// ## Example
///
/// ```
/// use recurring_event::{DailyEvent, Recurrent};
/// # assert!(true);
/// ```
///
/// # Trait Object
///
/// The trait can be used as a trait object to store the different types in the same container.
///
/// ## Example
///
/// ```
/// # use recurring_event::{DailyEvent, MonthlyEvent, MonthlyWeekdayOrdinal, Ordinal, Recurrent, WeeklyEvent, YearlyEvent,
///     time::{Month, OffsetDateTime, Weekday, macros::datetime}};
/// // Constructs a Vec of 'Recurrent'
/// let mut events: Vec<Box<dyn Recurrent>> = Vec::new();
///
/// let mut event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
/// events.push(Box::new(event));
///
/// let mut event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
/// event.insert_weekday(Weekday::Thursday);
/// events.push(Box::new(event));
///
/// let mut event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
/// event.insert_monthly_day_ordinal(7);
/// events.push(Box::new(event));
///
/// let mut event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
/// event.insert_monthly_weekday_ordinal(
///     MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Tuesday),
///     Month::February);
/// events.push(Box::new(event));
///
/// let mut dates = Vec::new();
///
/// for event in events.iter_mut() {
///     // Each event calls the `next_date` method.
///     dates.push(event.next_date().unwrap());
/// };
///
/// assert_eq!(dates, vec![datetime!(2022-12-26 00:00 UTC),
///                        datetime!(2022-12-29 00:00 UTC),
///                        datetime!(2023-1-07 00:00 UTC),
///                        datetime!(2023-02-14 00:00 UTC)]);
/// ```
///
/// ## Downcasting
///
/// When using the trait object, it's possible to get back to the concrete type of a recurring event by using the [`as_any`] method of the trait.
///
/// ### Example
/// ```
/// # use recurring_event::{DailyEvent, MonthlyEvent, Ordinal, Recurrent, Periodicity, WeeklyEvent, YearlyEvent,
///     time::{Month, OffsetDateTime, Weekday, macros::datetime}};
/// let mut events: Vec<Box<dyn Recurrent>> = Vec::new();
///
/// let mut event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
/// event.insert_weekday(Weekday::Thursday);
/// events.push(Box::new(event));
///
/// let mut event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
/// event.insert_monthly_day_ordinal(7);
/// events.push(Box::new(event));
///
/// for event in events.iter_mut() {
///     if *event.periodicity() == Periodicity::Weekly {
///         let weekly_event = event.as_any().downcast_ref::<WeeklyEvent>().unwrap();
///         assert_eq!(1, weekly_event.weekdays().count());
///     };
/// };
/// ```
/// [`as_any`]: Recurrent::as_any
#[typetag::serde(tag = "type")]
pub trait Recurrent: std::fmt::Debug {
    /// Returns a reference to the periodicity.
    fn periodicity(&self) -> &Periodicity;
    /// Returns a reference to the frequency.
    fn frequency(&self) -> u16;
    /// Update the frequency with the given value. Returns the previous value.
    fn update_frequency(&mut self, frequency: u16) -> u16;
    /// Returns a reference to the current occurrence date.
    fn current_date(&self) -> &OffsetDateTime;
    /// Update the current occurence date with the given value. Returns the previous value.
    fn update_current_date(&mut self, new_date: OffsetDateTime) -> OffsetDateTime;
    /// Try to determine the next occurrence date, starting from a day after the current date.
    /// May return an error.
    fn next_date(&mut self) -> Result<OffsetDateTime, Error>;
    /// Try to determine the next occurrence date, starting from the date given (inclusive).
    /// May return an error.
    fn next_date_from(&mut self, from_date: &OffsetDateTime) -> Result<OffsetDateTime, Error>;
    /// Returns a mutable reference to a component whose type is determined using dynamic dispatch.
    ///
    /// Useful when this trait is used as a trait object and a downcast to the concrete type of a component is required.
    ///
    /// See the [Downcasting](#downcasting) section.
    fn as_any(&mut self) -> &mut dyn Any;
}

/// An event whose recurrence rules are defined over a daily period
///
/// # Core methods
///
/// See [`implementation of the Recurrent trait`](struct.DailyEvent.html#impl-Recurrent) and
/// the [`implementation of the Iterator trait`](struct.DailyEvent.html#impl-Iterator)
/// for the core methods of `DailyEvent`.
///
/// # Recurrence Rules Supported
///
/// For `DailyEvent`, the frequency _is_ the recurrence rule. No additional recurrence rules are supported.
/// If you need an event that recurs on certain days of the week, see [`WeeklyEvent`].
///
/// # Example
///
/// ```
/// use recurring_event::{DailyEvent, Recurrent, time::macros::datetime};
///
/// // An event that happens every four days.
/// let mut event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
/// event.update_frequency(4);
///
/// let next_date = event.next_date().unwrap();
///
/// assert_eq!(datetime!(2022-12-29 00:00 UTC), next_date);
///
/// let next_date = event.next_date().unwrap();
///
/// assert_eq!(datetime!(2023-01-02 00:00 UTC), next_date);
/// ```
#[derive (Debug, Deserialize, Serialize)]
pub struct DailyEvent {
    current_date: OffsetDateTime,
    periodicity: Periodicity,
    frequency: u16,
}

#[typetag::serde]
impl Recurrent for DailyEvent {
    /// Returns a reference to the current occurrence date.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, time::macros::datetime};
    /// let event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let current_date = event.current_date();
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *current_date);
    /// ```
    fn current_date(&self) -> &OffsetDateTime {
        &self.current_date
    }

    /// Returns the frequency. For `DailyEvent`, the frequency is expressed in days.
    ///
    /// For a newly created `DailyEvent`, the frequency defaults to 1, which means the event recurs every day.
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, time::macros::datetime};
    /// let event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let frequency = event.frequency();
    ///
    /// assert_eq!(1, frequency);
    /// ```
    fn frequency(&self) -> u16 {
        self.frequency
    }

    /// Try to determine the next occurrence date, starting from a day after the current date.
    ///
    /// When successful, updates the current date with the next date and returns the next date.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, time::macros::datetime};
    /// let mut event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.update_frequency(4);
    /// let next_date = event.next_date().unwrap();
    ///
    /// // 4 days after 25th December.
    /// assert_eq!(datetime!(2022-12-29 00:00 UTC), next_date);
    /// assert_eq!(datetime!(2022-12-29 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// Call `next_date` several times to get consecutive values (or call the [`next`] method
    /// if you want to get many values at once, and don't need to use potentially returned errors).
    ///
    /// [`next`]: DailyEvent::next
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, time::macros::datetime};
    /// let mut event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    ///
    /// let mut next_date = event.next_date().unwrap();
    /// next_date = event.next_date().unwrap();
    /// next_date = event.next_date().unwrap();
    ///
    /// assert_eq!(datetime!(2022-12-28 00:00 UTC), next_date);
    /// ```
    ///
    /// # Errors
    ///
    /// See [`Error`] for errors that can be returned.
    ///
    fn next_date(&mut self) -> Result<OffsetDateTime, Error> {
        self.current_date = self.current_date.checked_add(Duration::days(i64::from(self.frequency))).ok_or(Error::DateOverflow)?;
        Ok(self.current_date)
    }

    /// Try to determine the next occurrence date, starting from the given date _included_.
    ///
    /// If the given date is equal to the current date (year, month and day values), act like [`next_date`]. Else
    /// updates the current date with the given date, and returns the given date.
    ///
    /// [`next_date`]: DailyEvent::next_date
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, time::macros::datetime};
    /// let date = datetime!(2022-12-25 00:00 UTC);
    /// let mut event = DailyEvent::new(date);
    /// // The current occurrence date is set to the 25th of December 2022.
    ///
    /// // given date is not equal to current date.
    /// let actual = event.next_date_from(&datetime!(2022-12-31 00:00 UTC)).unwrap();
    ///
    /// assert_eq!(datetime!(2022-12-31 00:00 UTC), actual);
    /// assert_eq!(datetime!(2022-12-31 00:00 UTC), *event.current_date());
    ///
    /// // given date is equal to current date (even if time is different) : act like next_date().
    /// let actual = event.next_date_from(&datetime!(2022-12-31 12:00 UTC)).unwrap();
    ///
    /// assert_eq!(datetime!(2023-01-01 00:00 UTC), actual);
    /// assert_eq!(datetime!(2023-01-01 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// # Errors
    ///
    /// See [`Error`] for errors that can be returned.
    ///
    fn next_date_from(&mut self, from_date: &OffsetDateTime) -> Result<OffsetDateTime, Error> {
        if self.current_date.date() == from_date.date() {
            self.next_date()
        } else {
            self.current_date = from_date.replace_time(self.current_date.time()); // Keep the time of current_date.
            Ok(self.current_date)
        }
    }

    /// Returns a reference to the periodicity of the event. For `DailyEvent`, it's always [`Periodicity::Daily`].
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Periodicity, Recurrent, time::macros::datetime};
    /// let event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let periodicity = event.periodicity();
    ///
    /// assert_eq!(Periodicity::Daily, *periodicity);
    /// ```
    ///
    /// This method is useful when [`Recurrent`] has been used as a trait object to type the event, and a downcast to the concrete type of the latter is needed.
    ///
    /// See the [Downcasting](trait.Recurrent.html#downcasting) section for an example.
    ///
    fn periodicity(&self) -> &Periodicity {
        &self.periodicity
    }

    /// Updates the current occurence date with the given value. Returns the previous value.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, time::macros::datetime};
    /// let mut event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    ///
    /// // Change the hour part.
    /// let new_date = event.current_date().replace_hour(12).unwrap();
    ///
    /// let previous_date = event.update_current_date(new_date);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), previous_date);
    /// assert_eq!(datetime!(2022-12-25 12:00 UTC), *event.current_date());
    /// ```
    fn update_current_date(&mut self, new_date: OffsetDateTime) -> OffsetDateTime {
        let previous_date = self.current_date.to_owned();
        self.current_date = new_date;
        previous_date
    }

    /// Updates the frequency with the value given. For `DailyEvent`, the frequency is expressed in days.
    /// Returns the previous value.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, time::macros::datetime};
    /// let mut event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    ///
    /// // Now the event recurs every four days.
    /// let previous = event.update_frequency(4);
    ///
    /// assert_eq!(4, event.frequency());
    /// assert_eq!(1, previous);
    /// ```
    fn update_frequency(&mut self, frequency: u16) -> u16 {
        let previous_frequency = self.frequency;
        self.frequency = frequency;
        previous_frequency
    }

    /// Returns a reference to self as a dynamic type.
    ///
    /// This method is useful when [`Recurrent`] has been used as a trait object to type an event, and a downcast to the concrete type of the latter is needed.
    ///
    /// See the [Downcasting](trait.Recurrent.html#downcasting) section for an example.
    fn as_any(&mut self) -> &mut dyn Any {
        self
    }
}

impl Iterator for DailyEvent {
    type Item = OffsetDateTime;

    /// Try to determine the next occurrence date, starting from a day after the current date.
    ///
    /// When successful, updates the current date with the next date and returns the next date.
    ///
    /// Returns `None` if an error occured.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, time::macros::datetime};
    /// let mut event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let mut next_date = event.next().unwrap();
    ///
    /// assert_eq!(datetime!(2022-12-26 00:00 UTC), next_date);
    /// assert_eq!(datetime!(2022-12-26 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// # Iterator
    ///
    /// This method becomes particularly useful when implicitly used by iterators to get many values at once,
    /// like in the next example with the `take` iterator.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, time::{OffsetDateTime, macros::datetime}};
    /// let event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    ///
    /// let next_dates: Vec<OffsetDateTime> = event.take(10).collect();
    ///
    /// let expected = vec![datetime!(2022-12-26 00:00 UTC),
    ///     datetime!(2022-12-27 00:00 UTC),
    ///     datetime!(2022-12-28 00:00 UTC),
    ///     datetime!(2022-12-29 00:00 UTC),
    ///     datetime!(2022-12-30 00:00 UTC),
    ///     datetime!(2022-12-31 00:00 UTC),
    ///     datetime!(2023-01-01 00:00 UTC),
    ///     datetime!(2023-01-02 00:00 UTC),
    ///     datetime!(2023-01-03 00:00 UTC),
    ///     datetime!(2023-01-04 00:00 UTC)];
    ///
    /// assert_eq!(expected, next_dates);
    /// ```
    ///
    /// ## Warning
    ///
    /// *Be careful*, with iterators like [`collect`] or [`last`], you may get much more dates than anticipated,
    /// because the method will be called until an error occur, which in that case will be an [`Error::DateOverflow`]
    /// due to the fact that the next occurence date will eventually be after 31st December 9999.
    ///
    /// [`collect`]: std::iter::Iterator::collect
    /// [`last`]: std::iter::Iterator::last
    fn next(&mut self) -> Option<Self::Item> {
        self.next_date().ok()
    }
}

impl DailyEvent {
    /// Returns a new `DailyEvent`, having :
    ///
    /// * [`Periodicity::Daily`]
    /// * Fequency set to 1 (hence, by default the event occurs every day).
    /// * Current occurence date set to the given date.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, time::OffsetDateTime};
    /// // Create a daily event that starts recurring from the system date.
    /// let event = DailyEvent::new(OffsetDateTime::now_local().unwrap());
    /// # assert!(true);
    /// ```
    pub fn new(current_date: OffsetDateTime) -> DailyEvent {
        DailyEvent {
            current_date,
            periodicity: Periodicity::Daily,
            frequency: 1,
        }
    }
}

impl From<WeeklyEvent> for DailyEvent {
    /// Converts `WeeklyEvent` to `DailyEvent`.
    ///
    /// * Recurrence rules for weekdays are lost.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, WeeklyEvent, time::macros::datetime};
    /// let mut weekly_event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// weekly_event.update_frequency(4);
    ///
    /// let daily_event = DailyEvent::from(weekly_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *daily_event.current_date());
    /// assert_eq!(4, daily_event.frequency());
    /// ```
    fn from(weekly_event: WeeklyEvent) -> Self {
       let date = weekly_event.current_date().to_owned();
       let frequency = weekly_event.frequency;
       let mut daily_event = DailyEvent::new(date);
       daily_event.update_frequency(frequency);
       daily_event
   }
}

impl From<MonthlyEvent> for DailyEvent {
    /// Converts `MonthlyEvent` to `DailyEvent`.
    ///
    /// * Recurrence rules for weekdays are lost.
    /// * Recurrence rules for monthly days ordinals are lost.
    /// * Recurrence rules for monthly weekdays ordinals are lost.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, MonthlyEvent, time::macros::datetime};
    /// let mut monthly_event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// monthly_event.update_frequency(4);
    ///
    /// let daily_event = DailyEvent::from(monthly_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *daily_event.current_date());
    /// assert_eq!(4, daily_event.frequency());
    /// ```
    fn from(monthly_event: MonthlyEvent) -> Self {
        let date = monthly_event.current_date().to_owned();
        let frequency = monthly_event.frequency;
        let mut daily_event = DailyEvent::new(date);
        daily_event.update_frequency(frequency);
        daily_event
    }
}

impl From<YearlyEvent> for DailyEvent {
    /// Converts `YearlyEvent` to `DailyEvent`.
    ///
    /// For all months :
    ///
    /// * Recurrence rules for weekdays are lost.
    /// * Recurrence rules for monthly days ordinals are lost.
    /// * Recurrence rules for monthly weekdays ordinals are lost.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, YearlyEvent, time::macros::datetime};
    /// let mut yearly_event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// yearly_event.update_frequency(4);
    ///
    /// let daily_event = DailyEvent::from(yearly_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *daily_event.current_date());
    /// assert_eq!(4, daily_event.frequency());
    /// ```
    fn from(yearly_event: YearlyEvent) -> Self {
        let date = yearly_event.current_date().to_owned();
        let frequency = yearly_event.frequency;
        let mut daily_event = DailyEvent::new(date);
        daily_event.update_frequency(frequency);
        daily_event
    }
}

/// An event whose recurrence rules are defined over a weekly period.
///
/// # Core methods
///
/// See [`implementation of the Recurrent trait`](struct.WeeklyEvent.html#impl-Recurrent) and
/// the [`implementation of the Iterator trait`](struct.WeeklyEvent.html#impl-Iterator)
/// for the core methods of `WeeklyEvent`.
///
/// # Recurrence Rules Supported
///
/// * Days of the week, with the [`Weekday`] type.
///
/// # First day of the week
///
/// This crate considers that the first day of the week is Monday, in accordance with the  [`ISO 8601`](https://en.wikipedia.org/wiki/ISO_8601) standard.
///
/// # Example
///
/// ```
/// use recurring_event::{Recurrent, WeeklyEvent, time::{Weekday, macros::datetime}};
///
/// // An event that happens every four weeks.
/// let mut event = WeeklyEvent::new(datetime!(2022-12-26 00:00 UTC));
/// event.update_frequency(4);
///
/// // On a week, the event happens on Monday and Thursday.
/// event.insert_weekday(Weekday::Monday);
/// event.insert_weekday(Weekday::Thursday);
///
/// let next_date = event.next_date().unwrap();
///
/// assert_eq!(datetime!(2022-12-29 00:00 UTC), next_date);
///
/// let next_date = event.next_date().unwrap();
///
/// assert_eq!(datetime!(2023-01-23 00:00 UTC), next_date);
/// ```
/// [`Weekday`]: time::Weekday
#[derive (Debug, Deserialize, Serialize)]
pub struct WeeklyEvent {
    current_date: OffsetDateTime,
    periodicity: Periodicity,
    frequency: u16,
    recurrences: Recurrences,
}

#[typetag::serde]
impl Recurrent for WeeklyEvent {
    /// Returns a reference to the current occurrence date.
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, Recurrent, time::macros::datetime};
    /// let event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let current_date = event.current_date();
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *current_date);
    /// ```
    fn current_date(&self) -> &OffsetDateTime {
        &self.current_date
    }

    /// Returns the frequency. For `WeeklyEvent`, the frequency is expressed in weeks.
    ///
    /// For a newly created `WeeklyEvent`, the frequency defaults to 1, which means the event recurs every week.
    /// ```
    /// # use recurring_event::{WeeklyEvent, Recurrent, time::macros::datetime};
    /// let event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let frequency = event.frequency();
    ///
    /// assert_eq!(1, frequency);
    /// ```
    fn frequency(&self) -> u16 {
        self.frequency
    }

    /// Try to determine the next occurrence date, starting from a day after the current date.
    ///
    /// When successful, updates the current date with the next date and returns the next date.
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, Recurrent, time::{Weekday, macros::datetime}};
    /// let mut event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Thursday);
    /// let next_date = event.next_date().unwrap();
    ///
    /// assert_eq!(datetime!(2022-12-29 00:00 UTC), next_date);
    /// assert_eq!(datetime!(2022-12-29 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// Call `next_date` several times to get consecutive values (or call the [`next`] method
    /// if you want to get many values at once, and don't need to use potentially returned errors).
    ///
    /// [`next`]: WeeklyEvent::next
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, Recurrent, time::{Weekday, macros::datetime}};
    /// let mut event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Thursday);
    ///
    /// let mut next_date = event.next_date().unwrap();
    /// next_date = event.next_date().unwrap();
    /// next_date = event.next_date().unwrap();
    ///
    /// assert_eq!(datetime!(2023-01-12 00:00 UTC), next_date);
    /// ```
    ///
    /// # Errors
    ///
    /// See [`Error`] for errors that can be returned.
    ///
    fn next_date(&mut self) -> Result<OffsetDateTime, Error> {
        /* If current_date is the last day of the week, the search must start from current week + frequency */
        if utility::next_day(&self.current_date)? == utility::first_date_of_next_week(&self.current_date)? {
            let second_week = self.current_date.checked_add(Duration::weeks(i64::from(self.frequency))).ok_or(Error::DateOverflow)?;
            let second_week_date = utility::first_date_of_week(&second_week)?;
            self.next_date_from(&second_week_date)
        } else {
            let next_day = utility::next_day(&self.current_date)?.to_owned();
            self.next_date_from(&next_day)
        }
    }

    /// Try to determine the next occurrence date, starting from the given date _included_,
    /// and thus ignoring the current occurrence date.
    /// Also, the frequency applies from the week of the given date.
    ///
    /// When successful, updates the current date with the next date and returns the next date.
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, Recurrent, time::{Weekday, macros::datetime}};
    /// let mut event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Monday);
    /// event.insert_weekday(Weekday::Thursday);
    ///
    /// // Start the search from the 10th of January 2023 included.
    /// // Ignoring the current occurence date of 25 December 2022.
    /// let next_date = event.next_date_from(&datetime!(2023-01-10 00:00 UTC)).unwrap();
    ///
    /// assert_eq!(datetime!(2023-01-12 00:00 UTC), next_date);
    /// assert_eq!(datetime!(2023-01-12 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// # Errors
    ///
    /// See [`Error`] for errors that can be returned.
    ///
    fn next_date_from(&mut self, from_date: &OffsetDateTime) -> Result<OffsetDateTime, Error> {
        if self.recurrences.weekdays().count() == 0 {
            return Err(Error::NoRecurrencesDefined);
        };

        let second_week = from_date.checked_add(Duration::weeks(i64::from(self.frequency))).ok_or(Error::DateOverflow)?;
        let second_week_date = utility::first_date_of_week(&second_week)?;

        let recurrences = EventRecurrences::Single(&self.recurrences);

        let mut new_date = matcher::check_the_from_and_frequenced_periods(matcher::check_week, *from_date, second_week_date, &recurrences)?.ok_or(Error::NoMatchingRecurrences)?;
        /* Keep the time of current_date. */
        new_date = new_date.replace_time(self.current_date.time());

        self.current_date = new_date;
        Ok(self.current_date)
    }

    /// Returns a reference to the periodicity of the event. For `WeeklyEvent`, it's always [`Periodicity::Weekly`].
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, Periodicity, Recurrent, time::macros::datetime};
    /// let event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let periodicity = event.periodicity();
    ///
    /// assert_eq!(Periodicity::Weekly, *periodicity);
    /// ```
    ///
    /// This method is useful when [`Recurrent`] has been used as a trait object to type the event, and a downcast to the concrete type of the latter is needed.
    ///
    /// See the [Downcasting](trait.Recurrent.html#downcasting) section for an example.
    ///
    fn periodicity(&self) -> &Periodicity {
        &self.periodicity
    }

    /// Updates the current occurence date with the given value. Returns the previous value.
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, Recurrent, time::macros::datetime};
    /// let mut event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    ///
    /// // Change the hour part.
    /// let new_date = event.current_date().replace_hour(12).unwrap();
    ///
    /// let previous_date = event.update_current_date(new_date);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), previous_date);
    /// assert_eq!(datetime!(2022-12-25 12:00 UTC), *event.current_date());
    /// ```
    fn update_current_date(&mut self, new_date: OffsetDateTime) -> OffsetDateTime {
        let previous_date = self.current_date.to_owned();
        self.current_date = new_date;
        previous_date
    }

    /// Updates the frequency with the value given. For `WeeklyEvent`, the frequency is expressed in weeks.
    /// Returns the previous value.
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, Recurrent, time::macros::datetime};
    /// let mut event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    ///
    /// // Now the event recurs every four weeks.
    /// let previous = event.update_frequency(4);
    ///
    /// assert_eq!(4, event.frequency());
    /// assert_eq!(1, previous);
    /// ```
    fn update_frequency(&mut self, frequency: u16) -> u16 {
        let previous_frequency = self.frequency;
        self.frequency = frequency;
        previous_frequency
    }

    /// Returns a mutable reference to self as a dynamic type.
    ///
    /// This method is useful when [`Recurrent`] has been used as a trait object to type an event, and a downcast to the concrete type of the latter is needed.
    ///
    /// See the [Downcasting](trait.Recurrent.html#downcasting) section for an example.
    fn as_any(&mut self) -> &mut dyn Any {
        self
    }
}

impl Iterator for WeeklyEvent {
    type Item = OffsetDateTime;

    /// Try to determine the next occurrence date, starting from a day after the current date.
    ///
    /// When successful, updates the current date with the next date and returns the next date.
    ///
    /// Returns `None` if an error occured.
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, Recurrent, time::{Weekday, macros::datetime}};
    /// let mut event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Thursday);
    /// let next_date = event.next().unwrap();
    ///
    /// assert_eq!(datetime!(2022-12-29 00:00 UTC), next_date);
    /// assert_eq!(datetime!(2022-12-29 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// # Iterator
    ///
    /// This method becomes particularly useful when implicitly used by iterators to get many values at once,
    /// like in the next example with the `take` iterator.
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, Recurrent, time::{OffsetDateTime, Weekday, macros::datetime}};
    /// let mut event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Monday);
    /// event.insert_weekday(Weekday::Thursday);
    ///
    /// let next_dates: Vec<OffsetDateTime> = event.take(10).collect();
    ///
    /// let expected = vec![datetime!(2022-12-26 00:00 UTC),
    ///     datetime!(2022-12-29 00:00 UTC),
    ///     datetime!(2023-01-02 00:00 UTC),
    ///     datetime!(2023-01-05 00:00 UTC),
    ///     datetime!(2023-01-09 00:00 UTC),
    ///     datetime!(2023-01-12 00:00 UTC),
    ///     datetime!(2023-01-16 00:00 UTC),
    ///     datetime!(2023-01-19 00:00 UTC),
    ///     datetime!(2023-01-23 00:00 UTC),
    ///     datetime!(2023-01-26 00:00 UTC)];
    ///
    /// assert_eq!(expected, next_dates);
    /// ```
    ///
    /// ## Warning
    ///
    /// *Be careful*, with iterators like [`collect`] or [`last`], you may get much more dates than anticipated,
    /// because the method will be called until an error occur, which in that case will be an [`Error::DateOverflow`]
    /// due to the fact that the next occurence date will eventually be after 31st December 9999.
    ///
    /// [`collect`]: std::iter::Iterator::collect
    /// [`last`]: std::iter::Iterator::last
    fn next(&mut self) -> Option<Self::Item> {
        self.next_date().ok()
    }
}

impl WeeklyEvent {
    /// Insert a weekday as a new recurrence rule.
    ///
    /// Returns whether the value was newly inserted. That is:
    /// * If the weekday rules did not previously contain this value, true is returned.
    /// * If the weekday rules already contained this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, time::{Weekday, macros::datetime}};
    /// let mut event = WeeklyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// let new_rule = event.insert_weekday(Weekday::Tuesday);
    ///
    /// assert!(new_rule);
    ///
    /// let new_rule = event.insert_weekday(Weekday::Tuesday);
    ///
    /// assert_eq!(false, new_rule);
    /// ```
    pub fn insert_weekday(&mut self, weekday: Weekday) -> bool {
        self.recurrences.insert_weekday(weekday)
    }

    /// Returns a new `WeeklyEvent`, having :
    ///
    /// * [`Periodicity::Weekly`]
    /// * Fequency set to 1 (hence, by default the event occurs every week).
    /// * Current occurence date set to the given date.
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, time::OffsetDateTime};
    /// // Create a weekly event that starts recurring from the system date.
    /// let event = WeeklyEvent::new(OffsetDateTime::now_local().unwrap());
    /// # assert!(true);
    /// ```
    pub fn new(current_date: OffsetDateTime) -> WeeklyEvent {
        WeeklyEvent {
            current_date,
            periodicity: Periodicity::Weekly,
            frequency: 1,
            recurrences: Recurrences::new(),
        }
    }

    /// Removes given weekday from recurrence rules.
    ///
    /// Returns whether the value was present in the rules. That is:
    /// * If the weekday rules did previously contain this value, true is returned.
    /// * If the weekday rules did not previously contain this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{WeeklyEvent, time::{Weekday, macros::datetime}};
    /// let mut event = WeeklyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// event.insert_weekday(Weekday::Tuesday);
    ///
    /// let present = event.remove_weekday(&Weekday::Tuesday);
    ///
    /// assert!(present);
    ///
    /// let present = event.remove_weekday(&Weekday::Tuesday);
    ///
    /// assert_eq!(false, present);
    /// ```
    pub fn remove_weekday(&mut self, weekday: &Weekday) -> bool {
        self.recurrences.remove_weekday(weekday)
    }

    /// Returns an iterator to the weekdays present in the recurrence rules.
    /// The iterator visits all elements in arbitrary order. The iterator element type is `&'a Weekday`.
    ///
    /// ```
    /// # use recurring_event::{ WeeklyEvent, time::{Weekday, macros::datetime}};
    /// let mut event = WeeklyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// event.insert_weekday(Weekday::Tuesday);
    /// event.insert_weekday(Weekday::Sunday);
    ///
    /// let weekdays = event.weekdays();
    ///
    /// assert_eq!(2, weekdays.count());
    /// ```
    pub fn weekdays(&self) -> Iter<Weekday> {
        self.recurrences.weekdays()
    }
}

impl From<DailyEvent> for WeeklyEvent {
    /// Converts `DailyEvent` to `WeeklyEvent` losslessly.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, WeeklyEvent, time::macros::datetime};
    /// let mut daily_event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// daily_event.update_frequency(4);
    ///
    /// let weekly_event = WeeklyEvent::from(daily_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *weekly_event.current_date());
    /// assert_eq!(4, weekly_event.frequency());
    /// ```
    fn from(daily_event: DailyEvent) -> Self {
        let date = daily_event.current_date().to_owned();
        let frequency = daily_event.frequency;
        let mut weekly_event = WeeklyEvent::new(date);
        weekly_event.update_frequency(frequency);
        weekly_event
    }
}

impl From<MonthlyEvent> for WeeklyEvent {
    /// Converts `MonthlyEvent` to `WeeklyEvent`.
    ///
    /// * Recurrence rules for weekdays are transferred.
    /// * Recurrence rules for monthly days ordinals are lost.
    /// * Recurrence rules for monthly weekdays ordinals are lost.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, Recurrent, WeeklyEvent, time::macros::datetime};
    /// let mut monthly_event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// monthly_event.update_frequency(4);
    ///
    /// let weekly_event = WeeklyEvent::from(monthly_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *weekly_event.current_date());
    /// assert_eq!(4, weekly_event.frequency());
    /// ```
    fn from(monthly_event: MonthlyEvent) -> Self {
        let date = monthly_event.current_date().to_owned();
        let frequency = monthly_event.frequency;
        let weekdays = monthly_event.weekdays().cloned();

        let mut weekly_event = WeeklyEvent::new(date);
        weekly_event.update_frequency(frequency);
        for weekday in weekdays {
            weekly_event.insert_weekday(weekday);
        };

        weekly_event
    }
}

impl From<YearlyEvent> for WeeklyEvent {
    /// Converts `YearlyEvent` to `WeeklyEvent`.
    ///
    /// For all months :
    ///
    /// * Recurrence rules for weekdays are lost.
    /// * Recurrence rules for monthly days ordinals are lost.
    /// * Recurrence rules for monthly weekdays ordinals are lost.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, Recurrent, WeeklyEvent, time::macros::datetime};
    /// let mut yearly_event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// yearly_event.update_frequency(4);
    ///
    /// let weekly_event = WeeklyEvent::from(yearly_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *weekly_event.current_date());
    /// assert_eq!(4, weekly_event.frequency());
    /// ```
    fn from(yearly_event: YearlyEvent) -> Self {
        let date = yearly_event.current_date().to_owned();
        let frequency = yearly_event.frequency;
        let mut weekly_event = WeeklyEvent::new(date);
        weekly_event.update_frequency(frequency);
        weekly_event
    }
}


/// An event whose recurrence rules are defined over a monthly period.
///
/// # Core methods
///
/// See [`implementation of the Recurrent trait`](struct.MonthlyEvent.html#impl-Recurrent) and
/// the [`implementation of the Iterator trait`](struct.MonthlyEvent.html#impl-Iterator)
/// for the core methods of `MonthlyEvent`.
///
/// # Recurrence Rules Supported
///
/// * Days of the week, with the [`Weekday`] type.
/// * Monthly day ordinal (e.g. the 20th day of the month), with the [`MonthlyDayOrdinal`] type.
/// * Monthly weekday ordinal (e.g. the second tuesday of the month), with the [`MonthlyWeekdayOrdinal`] type.
///
/// # Example
///
/// ```
/// use recurring_event::{MonthlyEvent, MonthlyWeekdayOrdinal, Ordinal, Recurrent,
///     time::{Weekday, macros::datetime}};
///
/// // An event that happens every four months.
/// let mut event = MonthlyEvent::new(datetime!(2022-12-26 00:00 UTC));
/// event.update_frequency(4);
///
/// // On a month, the event happens on Monday and Thursday.
/// event.insert_weekday(Weekday::Monday);
/// event.insert_weekday(Weekday::Thursday);
///
/// // And also on the 7th and the 25th days of the month.
/// event.insert_monthly_day_ordinal(7);
/// event.insert_monthly_day_ordinal(25);
///
/// // And also on the second Tuesday and the fourth Sunday of the month.
/// event.insert_monthly_weekday_ordinal(
///     MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Tuesday));
/// event.insert_monthly_weekday_ordinal(
///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday));
///
/// let next_date = event.next_date().unwrap();
///
/// assert_eq!(datetime!(2022-12-29 00:00 UTC), next_date);
///
/// let next_date = event.next_date().unwrap();
///
/// assert_eq!(datetime!(2023-04-03 00:00 UTC), next_date);
/// ```
/// [`Weekday`]: time::Weekday
#[derive (Debug, Deserialize, Serialize)]
pub struct MonthlyEvent {
    current_date: OffsetDateTime,
    periodicity: Periodicity,
    frequency: u16,
    recurrences: Recurrences,
}

#[typetag::serde]
impl Recurrent for MonthlyEvent {
    /// Returns a reference to the current occurrence date.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, Recurrent, time::macros::datetime};
    /// let event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let current_date = event.current_date();
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *current_date);
    /// ```
    fn current_date(&self) -> &OffsetDateTime {
        &self.current_date
    }

    /// Returns the frequency. For `MonthlyEvent`, the frequency is expressed in months.
    ///
    /// For a newly created `MonthlyEvent`, the frequency defaults to 1, which means the event recurs every month.
    /// ```
    /// # use recurring_event::{MonthlyEvent, Recurrent, time::macros::datetime};
    /// let event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let frequency = event.frequency();
    ///
    /// assert_eq!(1, frequency);
    /// ```
    fn frequency(&self) -> u16 {
        self.frequency
    }

    /// Try to determine the next occurrence date, starting from a day after the current date.
    ///
    /// When successful, updates the current date with the next date and returns the next date.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, MonthlyWeekdayOrdinal, Ordinal, Recurrent,
    ///     time::{Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Thursday);
    /// event.insert_monthly_day_ordinal(7);
    /// event.insert_monthly_weekday_ordinal(MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Wednesday));
    ///
    /// let next_date = event.next_date().unwrap();
    ///
    /// assert_eq!(datetime!(2022-12-29 00:00 UTC), next_date);
    /// assert_eq!(datetime!(2022-12-29 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// Call `next_date` several times to get consecutive values (or call the [`next`] method
    /// if you want to get many values at once, and don't need to use potentially returned errors).
    ///
    /// [`next`]: MonthlyEvent::next
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, MonthlyWeekdayOrdinal, Ordinal, Recurrent,
    ///     time::{Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Thursday);
    /// event.insert_monthly_day_ordinal(7);
    /// event.insert_monthly_weekday_ordinal(MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Wednesday));
    ///
    /// let mut next_date = event.next_date().unwrap();
    /// next_date = event.next_date().unwrap();
    /// next_date = event.next_date().unwrap();
    ///
    /// assert_eq!(datetime!(2023-01-07 00:00 UTC), next_date);
    /// ```
    ///
    /// # Errors
    ///
    /// See [`Error`] for errors that can be returned.
    ///
    fn next_date(&mut self) -> Result<OffsetDateTime, Error> {
        /* If current_date is the last day of the month, the search must start from current month + frequency */
        if utility::next_day(&self.current_date)? == utility::first_date_of_next_month(&self.current_date)? {
            let second_month = utility::first_date_of_month(&self.current_date)?;
            let second_month_date = utility::months_later(&second_month, self.frequency)?;
            self.next_date_from(&second_month_date)
        } else {
            let next_day = utility::next_day(&self.current_date)?.to_owned();
            self.next_date_from(&next_day)
        }
    }

    /// Try to determine the next occurrence date, starting from the given date _included_,
    /// and thus ignoring the current occurrence date.
    /// Also, the frequency applies from the month of the given date.
    ///
    /// When successful, updates the current date with the next date and returns the next date.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, MonthlyWeekdayOrdinal, Ordinal, Recurrent,
    ///     time::{Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Monday);
    /// event.insert_monthly_day_ordinal(7);
    /// event.insert_monthly_weekday_ordinal(MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Wednesday));
    ///
    /// // Start the search from the 10th of January 2023 included.
    /// // Ignoring the current occurence date of 25 December 2022.
    /// let next_date = event.next_date_from(&datetime!(2023-01-10 00:00 UTC)).unwrap();
    ///
    /// assert_eq!(datetime!(2023-01-11 00:00 UTC), next_date);
    /// assert_eq!(datetime!(2023-01-11 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// # Errors
    ///
    /// See [`Error`] for errors that can be returned.
    ///
    fn next_date_from(&mut self, from_date: &OffsetDateTime) -> Result<OffsetDateTime, Error> {
        if self.recurrences.weekdays().count() == 0 && self.recurrences.monthly_days_ordinals().count() == 0 && self.recurrences.monthly_weekdays_ordinals().count() == 0 {
            return Err(Error::NoRecurrencesDefined);
        };

        let second_month = utility::first_date_of_month(from_date)?;
        let second_month_date = utility::months_later(&second_month, self.frequency)?;

        let recurrences = EventRecurrences::Single(&self.recurrences);

        let mut new_date = matcher::check_the_from_and_frequenced_periods(matcher::check_month, *from_date, second_month_date, &recurrences)?.ok_or(Error::NoMatchingRecurrences)?;
        /* Keep the time of current_date. */
        new_date = new_date.replace_time(self.current_date.time());

        self.current_date = new_date;
        Ok(self.current_date)
    }

    /// Returns a reference to the periodicity of the event. For `MonthlyEvent`, it's always [`Periodicity::Monthly`].
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, Periodicity, Recurrent, time::macros::datetime};
    /// let event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let periodicity = event.periodicity();
    ///
    /// assert_eq!(Periodicity::Monthly, *periodicity);
    /// ```
    ///
    /// This method is useful when [`Recurrent`] has been used as a trait object to type the event, and a downcast to the concrete type of the latter is needed.
    ///
    /// See the [Downcasting](trait.Recurrent.html#downcasting) section for an example.
    ///
    fn periodicity(&self) -> &Periodicity {
        &self.periodicity
    }

    /// Updates the current occurence date with the given value. Returns the previous value.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, Recurrent, time::macros::datetime};
    /// let mut event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    ///
    /// // Change the hour part.
    /// let new_date = event.current_date().replace_hour(12).unwrap();
    ///
    /// let previous_date = event.update_current_date(new_date);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), previous_date);
    /// assert_eq!(datetime!(2022-12-25 12:00 UTC), *event.current_date());
    /// ```
    fn update_current_date(&mut self, new_date: OffsetDateTime) -> OffsetDateTime {
        let previous_date = self.current_date.to_owned();
        self.current_date = new_date;
        previous_date
    }

    /// Updates the frequency with the value given. For `MonthlyEvent`, the frequency is expressed in months.
    /// Returns the previous value.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, Recurrent, time::macros::datetime};
    /// let mut event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    ///
    /// // Now the event recurs every four months.
    /// let previous = event.update_frequency(4);
    ///
    /// assert_eq!(4, event.frequency());
    /// assert_eq!(1, previous);
    /// ```
    fn update_frequency(&mut self, frequency: u16) -> u16 {
        let previous_frequency = self.frequency;
        self.frequency = frequency;
        previous_frequency
    }

    /// Returns a mutable reference to self as a dynamic type.
    ///
    /// This method is useful when [`Recurrent`] has been used as a trait object to type an event, and a downcast to the concrete type of the latter is needed.
    ///
    /// See the [Downcasting](trait.Recurrent.html#downcasting) section for an example.
    fn as_any(&mut self) -> &mut dyn Any {
        self
    }
}

impl Iterator for MonthlyEvent {
    type Item = OffsetDateTime;

    /// Try to determine the next occurrence date, starting from a day after the current date.
    ///
    /// When successful, updates the current date with the next date and returns the next date.
    ///
    /// Returns `None` if an error occured.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, MonthlyWeekdayOrdinal, Ordinal, Recurrent,
    ///     time::{Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Thursday);
    /// event.insert_monthly_day_ordinal(7);
    /// event.insert_monthly_weekday_ordinal(MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Wednesday));
    ///
    /// let next_date = event.next().unwrap();
    ///
    /// assert_eq!(datetime!(2022-12-29 00:00 UTC), next_date);
    /// assert_eq!(datetime!(2022-12-29 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// # Iterator
    ///
    /// This method becomes particularly useful when implicitly used by iterators to get many values at once,
    /// like in the next example with the `take` iterator.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, MonthlyWeekdayOrdinal, Ordinal, Recurrent,
    ///     time::{OffsetDateTime, Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Monday);
    /// event.insert_weekday(Weekday::Thursday);
    /// event.insert_monthly_day_ordinal(7);
    /// event.insert_monthly_day_ordinal(25);
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Tuesday));
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday));
    ///
    /// let next_dates: Vec<OffsetDateTime> = event.take(20).collect();
    ///
    /// let expected = vec![datetime!(2022-12-26 00:00 UTC),
    ///     datetime!(2022-12-29 00:00 UTC),
    ///     datetime!(2023-01-02 00:00 UTC),
    ///     datetime!(2023-01-05 00:00 UTC),
    ///     datetime!(2023-01-07 00:00 UTC),
    ///     datetime!(2023-01-09 00:00 UTC),
    ///     datetime!(2023-01-10 00:00 UTC),
    ///     datetime!(2023-01-12 00:00 UTC),
    ///     datetime!(2023-01-16 00:00 UTC),
    ///     datetime!(2023-01-19 00:00 UTC),
    ///     datetime!(2023-01-22 00:00 UTC),
    ///     datetime!(2023-01-23 00:00 UTC),
    ///     datetime!(2023-01-25 00:00 UTC),
    ///     datetime!(2023-01-26 00:00 UTC),
    ///     datetime!(2023-01-30 00:00 UTC),
    ///     datetime!(2023-02-02 00:00 UTC),
    ///     datetime!(2023-02-06 00:00 UTC),
    ///     datetime!(2023-02-07 00:00 UTC),
    ///     datetime!(2023-02-09 00:00 UTC),
    ///     datetime!(2023-02-13 00:00 UTC)];
    ///
    /// assert_eq!(expected, next_dates);
    /// ```
    ///
    /// ## Warning
    ///
    /// *Be careful*, with iterators like [`collect`] or [`last`], you may get much more dates than anticipated,
    /// because the method will be called until an error occur, which in that case will be an [`Error::DateOverflow`]
    /// due to the fact that the next occurence date will eventually be after 31st December 9999.
    ///
    /// [`collect`]: std::iter::Iterator::collect
    /// [`last`]: std::iter::Iterator::last
    fn next(&mut self) -> Option<Self::Item> {
        self.next_date().ok()
    }
}

impl MonthlyEvent {
    /// Insert a monthly day ordinal as a new recurrence rule.
    ///
    /// Returns whether the value was newly inserted. That is:
    /// * If the monthly day ordinal rules did not previously contain this value, true is returned.
    /// * If the monthly day ordinal rules already contained this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, time::macros::datetime};
    /// let mut event = MonthlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// let new_rule = event.insert_monthly_day_ordinal(7);
    ///
    /// assert!(new_rule);
    ///
    /// let new_rule = event.insert_monthly_day_ordinal(7);
    ///
    /// assert_eq!(false, new_rule);
    /// ```
    pub fn insert_monthly_day_ordinal(&mut self, day_ordinal: MonthlyDayOrdinal) -> bool {
        self.recurrences.insert_monthly_day_ordinal(day_ordinal)
    }

    /// Insert a monthly weekday ordinal as a new recurrence rule.
    ///
    /// Returns whether the value was newly inserted. That is:
    /// * If the monthly weekday ordinal rules did not previously contain this value, true is returned.
    /// * If the monthly weekday ordinal rules already contained this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, Ordinal, MonthlyWeekdayOrdinal,
    ///     time::{Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// let new_rule = event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday));
    ///
    /// assert!(new_rule);
    ///
    /// let new_rule = event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday));
    ///
    /// assert_eq!(false, new_rule);
    /// ```
    pub fn insert_monthly_weekday_ordinal(&mut self, monthly_weekday_ordinal: MonthlyWeekdayOrdinal) -> bool  {
        self.recurrences.insert_monthly_weekday_ordinal(monthly_weekday_ordinal)
    }

    /// Insert a weekday as a new recurrence rule.
    ///
    /// Returns whether the value was newly inserted. That is:
    /// * If the weekday rules did not previously contain this value, true is returned.
    /// * If the weekday rules already contained this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, time::{Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// let new_rule = event.insert_weekday(Weekday::Tuesday);
    ///
    /// assert!(new_rule);
    ///
    /// let new_rule = event.insert_weekday(Weekday::Tuesday);
    ///
    /// assert_eq!(false, new_rule);
    /// ```
    pub fn insert_weekday(&mut self, weekday: Weekday) -> bool {
        self.recurrences.insert_weekday(weekday)
    }

    /// Returns an iterator to the monthly days ordinals present in the recurrence rules.
    /// The iterator visits all elements in arbitrary order. The iterator element type is `&'a MonthlyDayOrdinal`.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, time::macros::datetime};
    /// let mut event = MonthlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// event.insert_monthly_day_ordinal(7);
    /// event.insert_monthly_day_ordinal(29);
    ///
    /// let monthly_days_ordinals = event.monthly_days_ordinals();
    ///
    /// assert_eq!(2, monthly_days_ordinals.count());
    /// ```
    pub fn monthly_days_ordinals(&self) -> Iter<MonthlyDayOrdinal> {
        self.recurrences.monthly_days_ordinals()
    }

    /// Returns an iterator to the monthly weekdays ordinals present in the recurrence rules.
    /// The iterator visits all elements in arbitrary order. The iterator element type is `&'a MonthlyWeekdayOrdinal`.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, MonthlyWeekdayOrdinal, Ordinal,
    ///     time::{Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday));
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::First, Weekday::Thursday));
    ///
    /// let monthly_weekdays_ordinals = event.monthly_weekdays_ordinals();
    ///
    /// assert_eq!(2, monthly_weekdays_ordinals.count());
    /// ```
    pub fn monthly_weekdays_ordinals(&self) -> Iter<MonthlyWeekdayOrdinal> {
        self.recurrences.monthly_weekdays_ordinals()
    }

    /// Returns a new `MonthlyEvent`, having :
    ///
    /// * [`Periodicity::Monthly`]
    /// * Fequency set to 1 (hence, by default the event occurs every month).
    /// * Current occurence date set to the given date.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, time::OffsetDateTime};
    /// // Create a monthly event that starts recurring from the system date.
    /// let event = MonthlyEvent::new(OffsetDateTime::now_local().unwrap());
    /// # assert!(true);
    /// ```
    pub fn new(current_date: OffsetDateTime) -> MonthlyEvent {
        MonthlyEvent {
            current_date,
            periodicity: Periodicity::Monthly,
            frequency: 1,
            recurrences: Recurrences::new(),
        }
    }

    /// Removes given monthly day ordinal from recurrence rules.
    ///
    /// Returns whether the value was present in the rules. That is:
    /// * If the monthly day ordinal rules did previously contain this value, true is returned.
    /// * If the monthly day ordinal rules did not previously contain this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, time::{Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// let new_rule = event.insert_monthly_day_ordinal(7);
    ///
    /// let present = event.remove_monthly_day_ordinal(&7);
    ///
    /// assert!(present);
    ///
    /// let present = event.remove_monthly_day_ordinal(&7);
    ///
    /// assert_eq!(false, present);
    /// ```
    pub fn remove_monthly_day_ordinal(&mut self, day_ordinal: &MonthlyDayOrdinal) -> bool {
        self.recurrences.remove_monthly_day_ordinal(day_ordinal)
    }

    /// Removes given monthly weekday ordinal from recurrence rules.
    ///
    /// Returns whether the value was present in the rules. That is:
    /// * If the monthly weekday ordinal rules did previously contain this value, true is returned.
    /// * If the monthly weekday ordinal rules did not previously contain this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, MonthlyWeekdayOrdinal, Ordinal,
    ///     time::{Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// let new_rule = event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday));
    ///
    /// let present = event.remove_monthly_weekday_ordinal(
    ///     &MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday));
    ///
    /// assert!(present);
    ///
    /// let present = event.remove_monthly_weekday_ordinal(
    ///     &MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday));
    ///
    /// assert_eq!(false, present);
    /// ```
    pub fn remove_monthly_weekday_ordinal(&mut self, monthly_weekday_ordinal: &MonthlyWeekdayOrdinal) -> bool {
        self.recurrences.remove_monthly_weekday_ordinal(&monthly_weekday_ordinal)
    }

    /// Removes given weekday from recurrence rules.
    ///
    /// Returns whether the value was present in the rules. That is:
    /// * If the weekday rules did previously contain this value, true is returned.
    /// * If the weekday rules did not previously contain this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, time::{Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// event.insert_weekday(Weekday::Tuesday);
    ///
    /// let present = event.remove_weekday(&Weekday::Tuesday);
    ///
    /// assert!(present);
    ///
    /// let present = event.remove_weekday(&Weekday::Tuesday);
    ///
    /// assert_eq!(false, present);
    /// ```
    pub fn remove_weekday(&mut self, weekday: &Weekday) -> bool {
        self.recurrences.remove_weekday(weekday)
    }

    /// Returns an iterator to the weekdays present in the recurrence rules.
    /// The iterator visits all elements in arbitrary order. The iterator element type is `&'a Weekday`.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, time::{Weekday, macros::datetime}};
    /// let mut event = MonthlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// event.insert_weekday(Weekday::Tuesday);
    /// event.insert_weekday(Weekday::Sunday);
    ///
    /// let weekdays = event.weekdays();
    ///
    /// assert_eq!(2, weekdays.count());
    /// ```
    pub fn weekdays(&self) -> Iter<Weekday> {
        self.recurrences.weekdays()
    }
}

impl From<DailyEvent> for MonthlyEvent {
    /// Converts `DailyEvent` to `MonthlyEvent` losslessly.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, MonthlyEvent, time::macros::datetime};
    /// let mut daily_event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// daily_event.update_frequency(4);
    ///
    /// let monthly_event = MonthlyEvent::from(daily_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *monthly_event.current_date());
    /// assert_eq!(4, monthly_event.frequency());
    /// ```
    fn from(daily_event: DailyEvent) -> Self {
        let date = daily_event.current_date().to_owned();
        let frequency = daily_event.frequency;
        let mut monthly_event = MonthlyEvent::new(date);
        monthly_event.update_frequency(frequency);
        monthly_event
    }
}

impl From<WeeklyEvent> for MonthlyEvent {
    /// Converts `WeeklyEvent` to `MonthlyEvent`.
    ///
    /// * Recurrence rules for weekdays are transferred.
    ///
    /// ```
    /// # use recurring_event::{MonthlyEvent, Recurrent, WeeklyEvent, time::macros::datetime};
    /// let mut weekly_event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// weekly_event.update_frequency(4);
    ///
    /// let monthly_event = MonthlyEvent::from(weekly_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *monthly_event.current_date());
    /// assert_eq!(4, monthly_event.frequency());
    /// ```
    fn from(weekly_event: WeeklyEvent) -> Self {
        let date = weekly_event.current_date().to_owned();
        let frequency = weekly_event.frequency;
        let weekdays = weekly_event.weekdays().cloned();

        let mut monthly_event = MonthlyEvent::new(date);
        monthly_event.update_frequency(frequency);
        for weekday in weekdays {
            monthly_event.insert_weekday(weekday);
        };

        monthly_event
    }
}

impl From<YearlyEvent> for MonthlyEvent {
    /// Converts `YearlyEvent` to `MonthlyEvent` losslessly.
    ///
    /// For all months :
    ///
    /// * Recurrence rules for weekdays are lost.
    /// * Recurrence rules for monthly days ordinals are lost.
    /// * Recurrence rules for monthly weekdays ordinals are lost.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, Recurrent, MonthlyEvent, time::macros::datetime};
    /// let mut yearly_event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// yearly_event.update_frequency(4);
    ///
    /// let monthly_event = MonthlyEvent::from(yearly_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *monthly_event.current_date());
    /// assert_eq!(4, monthly_event.frequency());
    /// ```
    fn from(yearly_event: YearlyEvent) -> Self {
        let date = yearly_event.current_date().to_owned();
        let frequency = yearly_event.frequency;
        let mut monthly_event = MonthlyEvent::new(date);
        monthly_event.update_frequency(frequency);
        monthly_event
    }
}

/// An event whose recurrence rules are defined over a yearly period.
///
/// # Core methods
///
/// See [`implementation of the Recurrent trait`](struct.YearlyEvent.html#impl-Recurrent) and
/// the [`implementation of the Iterator trait`](struct.YearlyEvent.html#impl-Iterator)
/// for the core methods of `MonthlyEvent`.
///
/// # Recurrence Rules Supported
///
/// * _for a given month_, days of the week, with the [`Weekday`] type.
/// * _for a given month_, monthly day ordinal (e.g. the 20th day of the month), with the [`MonthlyDayOrdinal`] type.
/// * _for a given month_, monthly weekday ordinal (e.g. the second tuesday of the month), with the [`MonthlyWeekdayOrdinal`] type.
///
/// YearlyEvent differentiates from [`MonthlyEvent`] in that the recurrences rules are defined
/// for specific [`Month`]s of the year.
///
/// # Example
///
/// ```
/// use recurring_event::{Ordinal, Recurrent, MonthlyWeekdayOrdinal, YearlyEvent,
///     time::{Month, Weekday, macros::datetime}};
///
/// // An event that happens every four years.
/// let mut event = YearlyEvent::new(datetime!(2022-02-27 00:00 UTC));
/// event.update_frequency(4);
///
/// // On a year, the event happens on every Monday and Thursday of February.
/// event.insert_weekday(Weekday::Monday, Month::February);
/// event.insert_weekday(Weekday::Thursday, Month::February);
///
/// // And also on the 7th and 15th of February.
/// event.insert_monthly_day_ordinal(7, Month::February);
/// event.insert_monthly_day_ordinal(25, Month::February);
///
/// // And also on the second Tuesday and fourth Sunday of February.
/// event.insert_monthly_weekday_ordinal(MonthlyWeekdayOrdinal::new(
///     Ordinal::Second, Weekday::Tuesday), Month::February);
/// event.insert_monthly_weekday_ordinal(MonthlyWeekdayOrdinal::new(
///     Ordinal::Fourth, Weekday::Sunday), Month::February);
///
/// // The event also happens on August, every Tuesday and Saturday.
/// event.insert_weekday(Weekday::Tuesday, Month::August);
/// event.insert_weekday(Weekday::Saturday, Month::August);
///
/// // And on the 13th and 29th of August.
/// event.insert_monthly_day_ordinal(13, Month::August);
/// event.insert_monthly_day_ordinal(29, Month::August);
///
/// // And of the first Wednesday and third Friday of August.
/// event.insert_monthly_weekday_ordinal(MonthlyWeekdayOrdinal::new(
///     Ordinal::First, Weekday::Wednesday), Month::August);
/// event.insert_monthly_weekday_ordinal(MonthlyWeekdayOrdinal::new(
///     Ordinal::Third, Weekday::Friday), Month::August);
///
/// let next_date = event.next_date().unwrap();
///
/// assert_eq!(datetime!(2022-02-28 00:00 UTC), next_date);
///
/// let next_date = event.next_date().unwrap();
///
/// assert_eq!(datetime!(2022-08-02 00:00 UTC), next_date);
/// ```
/// [`Month`]: time::Month
/// [`MonthlyEvent`]: MonthlyEvent
/// [`Weekday`]: time::Weekday
/// [`MonthlyWeekdayOrdinal`]: MonthlyWeekdayOrdinal
#[derive (Debug, Deserialize, Serialize)]
pub struct YearlyEvent {
    current_date: OffsetDateTime,
    periodicity: Periodicity,
    frequency: u16,
    recurrences_by_month: HashMap<Month, Recurrences>,
}

#[typetag::serde]
impl Recurrent for YearlyEvent {
    /// Returns a reference to the current occurrence date.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, Recurrent, time::macros::datetime};
    /// let event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let current_date = event.current_date();
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *current_date);
    /// ```
    fn current_date(&self) -> &OffsetDateTime {
        &self.current_date
    }

    /// Returns the frequency. For `YearlyEvent`, the frequency is expressed in years.
    ///
    /// For a newly created `YearlyEvent`, the frequency defaults to 1, which means the event recurs every year.
    /// ```
    /// # use recurring_event::{YearlyEvent, Recurrent, time::macros::datetime};
    /// let event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let frequency = event.frequency();
    ///
    /// assert_eq!(1, frequency);
    /// ```
    fn frequency(&self) -> u16 {
        self.frequency
    }

    /// Try to determine the next occurrence date, starting from a day after the current date.
    ///
    /// When successful, updates the current date with the next date and returns the next date.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, MonthlyWeekdayOrdinal, Ordinal, Recurrent,
    ///     time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Thursday, Month::February);
    /// event.insert_monthly_day_ordinal(7, Month::February);
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Wednesday), Month::February);
    ///
    /// let next_date = event.next_date().unwrap();
    ///
    /// assert_eq!(datetime!(2023-02-02 00:00 UTC), next_date);
    /// assert_eq!(datetime!(2023-02-02 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// Call `next_date` several times to get consecutive values (or call the [`next`] method
    /// if you want to get many values at once, and don't need to use potentially returned errors).
    ///
    /// [`next`]: YearlyEvent::next
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, MonthlyWeekdayOrdinal, Ordinal, Recurrent,
    ///     time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Thursday, Month::February);
    /// event.insert_monthly_day_ordinal(7, Month::February);
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Wednesday), Month::February);
    ///
    /// let mut next_date = event.next_date().unwrap();
    /// next_date = event.next_date().unwrap();
    /// next_date = event.next_date().unwrap();
    ///
    /// assert_eq!(datetime!(2023-02-08 00:00 UTC), next_date);
    /// ```
    ///
    /// # Errors
    ///
    /// See [`Error`] for errors that can be returned.
    ///
    fn next_date(&mut self) -> Result<OffsetDateTime, Error> {
        /* If current_date is the last day of the year, the search must start from current year + frequency */
        if  utility::next_day(&self.current_date)? == utility::first_date_of_next_year(&self.current_date)? {
            let second_year_date = self.current_date.replace_day(1)?.replace_month(Month::January)?.replace_year(self.current_date.year() + self.frequency() as i32)?;
            self.next_date_from(&second_year_date)
        } else {
            let next_day = utility::next_day(&self.current_date)?.to_owned();
            self.next_date_from(&next_day)
        }
    }

    /// Try to determine the next occurrence date, starting from the given date _included_,
    /// and thus ignoring the current occurrence date.
    /// Also, the frequency applies from the year of the given date.
    ///
    /// When successful, updates the current date with the next date and returns the next date.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, MonthlyWeekdayOrdinal, Ordinal, Recurrent,
    ///     time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Monday, Month::February);
    /// event.insert_monthly_day_ordinal(7, Month::February);
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Wednesday), Month::February);
    ///
    /// // Start the search from the 7th of March 2023 included.
    /// // Ignoring the current occurence date of 25 December 2022.
    /// let next_date = event.next_date_from(&datetime!(2023-03-07 00:00 UTC)).unwrap();
    ///
    /// assert_eq!(datetime!(2024-02-05 00:00 UTC), next_date);
    /// assert_eq!(datetime!(2024-02-05 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// # Errors
    ///
    /// See [`Error`] for errors that can be returned.
    ///
    fn next_date_from(&mut self, from_date: &OffsetDateTime) -> Result<OffsetDateTime, Error> {
     if self.recurrences_by_month.is_empty() ||
     self.recurrences_by_month.iter().all(|(_month, recurrences)| recurrences.weekdays().count() == 0 && recurrences.monthly_days_ordinals().count() == 0
        && recurrences.monthly_weekdays_ordinals().count() ==0) {
        return Err(Error::NoRecurrencesDefined);
    }

    let second_year_date = from_date.replace_day(1)?.replace_month(Month::January)?.replace_year(from_date.year() + self.frequency() as i32)?;

    let recurrences = EventRecurrences::Multiple(&self.recurrences_by_month);

    let mut new_date = matcher::check_the_from_and_frequenced_periods(matcher::check_year, *from_date, second_year_date, &recurrences)?.ok_or(Error::NoMatchingRecurrences)?;
    /* Keep the time of current_date. */
    new_date = new_date.replace_time(self.current_date.time());

    self.current_date = new_date;
    Ok(self.current_date)
}

    /// Returns a reference to the periodicity of the event. For `YearlyEvent`, it's always [`Periodicity::Yearly`].
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, Periodicity, Recurrent,
    ///     time::macros::datetime};
    /// let event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// let periodicity = event.periodicity();
    ///
    /// assert_eq!(Periodicity::Yearly, *periodicity);
    /// ```
    ///
    /// This method is useful when [`Recurrent`] has been used as a trait object to type the event, and a downcast to the concrete type of the latter is needed.
    ///
    /// See the [Downcasting](trait.Recurrent.html#downcasting) section for an example.
    ///
    fn periodicity(&self) -> &Periodicity {
        &self.periodicity
    }

    /// Updates the current occurence date with the given value. Returns the previous value.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, Recurrent, time::macros::datetime};
    /// let mut event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    ///
    /// // Change the hour part.
    /// let new_date = event.current_date().replace_hour(12).unwrap();
    ///
    /// let previous_date = event.update_current_date(new_date);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), previous_date);
    /// assert_eq!(datetime!(2022-12-25 12:00 UTC), *event.current_date());
    /// ```
    fn update_current_date(&mut self, new_date: OffsetDateTime) -> OffsetDateTime {
        let previous_date = self.current_date.to_owned();
        self.current_date = new_date;
        previous_date
    }

    /// Updates the frequency with the value given. For `YearlyEvent`, the frequency is expressed in years.
    /// Returns the previous value.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, Recurrent, time::macros::datetime};
    /// let mut event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    ///
    /// // Now the event recurs every four years.
    /// let previous = event.update_frequency(4);
    ///
    /// assert_eq!(4, event.frequency());
    /// assert_eq!(1, previous);
    /// ```
    fn update_frequency(&mut self, frequency: u16) -> u16 {
        let previous_frequency = self.frequency;
        self.frequency = frequency;
        previous_frequency
    }

    /// Returns a mutable reference to self as a dynamic type.
    ///
    /// This method is useful when [`Recurrent`] has been used as a trait object to type an event, and a downcast to the concrete type of the latter is needed.
    ///
    /// See the [Downcasting](trait.Recurrent.html#downcasting) section for an example.
    fn as_any(&mut self) -> &mut dyn Any {
        self
    }
}

impl Iterator for YearlyEvent {
    type Item = OffsetDateTime;

    /// Try to determine the next occurrence date, starting from a day after the current date.
    ///
    /// When successful, updates the current date with the next date and returns the next date.
    ///
    /// Returns `None` if an error occured.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, MonthlyWeekdayOrdinal, Ordinal, Recurrent,
    ///     time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// event.insert_weekday(Weekday::Monday, Month::February);
    /// event.insert_monthly_day_ordinal(7, Month::February);
    /// event.insert_monthly_weekday_ordinal(MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Wednesday), Month::February);
    ///
    /// // Start the search from the 7th of March 2023 included.
    /// // Ignoring the current occurence date of 25 December 2022.
    /// let next_date = event.next_date_from(&datetime!(2023-03-07 00:00 UTC)).unwrap();
    ///
    /// assert_eq!(datetime!(2024-02-05 00:00 UTC), next_date);
    /// assert_eq!(datetime!(2024-02-05 00:00 UTC), *event.current_date());
    /// ```
    ///
    /// # Iterator
    ///
    /// This method becomes particularly useful when implicitly used by iterators to get many values at once,
    /// like in the next example with the `take` iterator.
    ///
    /// ```
    /// use recurring_event::{MonthlyWeekdayOrdinal, Ordinal, Recurrent, YearlyEvent,
    ///     time::{Month, OffsetDateTime, Weekday, macros::datetime}};
    ///
    /// let mut event = YearlyEvent::new(datetime!(2018-11-14 00:00 UTC));
    /// event.update_frequency(4);
    ///
    /// event.insert_weekday(Weekday::Monday, Month::February);
    /// event.insert_weekday(Weekday::Thursday, Month::February);
    ///
    /// event.insert_monthly_day_ordinal(7, Month::February);
    /// event.insert_monthly_day_ordinal(25, Month::February);
    ///
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Tuesday),
    ///     Month::February);
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday),
    ///     Month::February);
    ///
    /// let next_occurrences_dates: Vec<OffsetDateTime> = event.take(20).collect();
    ///
    /// let expected_dates = vec![datetime!(2022-02-03 00:00 UTC),
    ///     datetime!(2022-02-07 00:00 UTC),
    ///     datetime!(2022-02-08 00:00 UTC),
    ///     datetime!(2022-02-10 00:00 UTC),
    ///     datetime!(2022-02-14 00:00 UTC),
    ///     datetime!(2022-02-17 00:00 UTC),
    ///     datetime!(2022-02-21 00:00 UTC),
    ///     datetime!(2022-02-24 00:00 UTC),
    ///     datetime!(2022-02-25 00:00 UTC),
    ///     datetime!(2022-02-27 00:00 UTC),
    ///     datetime!(2022-02-28 00:00 UTC),
    ///     datetime!(2026-02-02 00:00 UTC),
    ///     datetime!(2026-02-05 00:00 UTC),
    ///     datetime!(2026-02-07 00:00 UTC),
    ///     datetime!(2026-02-09 00:00 UTC),
    ///     datetime!(2026-02-10 00:00 UTC),
    ///     datetime!(2026-02-12 00:00 UTC),
    ///     datetime!(2026-02-16 00:00 UTC),
    ///     datetime!(2026-02-19 00:00 UTC),
    ///     datetime!(2026-02-22 00:00 UTC)];
    ///
    /// assert_eq!(expected_dates, next_occurrences_dates)
    /// ```
    ///
    /// ## Warning
    ///
    /// *Be careful*, with iterators like [`collect`] or [`last`], you may get much more dates than anticipated,
    /// because the method will be called until an error occur, which in that case will be an [`Error::DateOverflow`]
    /// due to the fact that the next occurence date will eventually be after 31st December 9999.
    ///
    /// [`collect`]: std::iter::Iterator::collect
    /// [`last`]: std::iter::Iterator::last
    fn next(&mut self) -> Option<Self::Item> {
        self.next_date().ok()
    }
}

impl YearlyEvent {

    /// Insert a monthly day ordinal as a new recurrence rule, for a given month.
    ///
    /// Returns whether the value was newly inserted. That is:
    /// * If the monthly day ordinal rules did not previously contain this value, true is returned.
    /// * If the monthly day ordinal rules already contained this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, time::{Month, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// let new_rule = event.insert_monthly_day_ordinal(7, Month::February);
    ///
    /// assert!(new_rule);
    ///
    /// let new_rule = event.insert_monthly_day_ordinal(7, Month::February);
    ///
    /// assert_eq!(false, new_rule);
    /// ```
    pub fn insert_monthly_day_ordinal(&mut self, monthly_day_ordinal: MonthlyDayOrdinal, month: Month) -> bool {
        self.recurrences_by_month.entry(month).or_insert_with(|| {Recurrences::new()}).insert_monthly_day_ordinal(monthly_day_ordinal)
    }

    /// Insert a monthly weekday ordinal as a new recurrence rule, for a given month.
    ///
    /// Returns whether the value was newly inserted. That is:
    /// * If the monthly weekday ordinal rules did not previously contain this value, true is returned.
    /// * If the monthly weekday ordinal rules already contained this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, Ordinal, MonthlyWeekdayOrdinal,
    ///     time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// let new_rule = event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday),
    ///     Month::February);
    ///
    /// assert!(new_rule);
    ///
    /// let new_rule = event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday),
    ///     Month::February);
    ///
    /// assert_eq!(false, new_rule);
    /// ```
    pub fn insert_monthly_weekday_ordinal(&mut self, monthly_weekday_ordinal: MonthlyWeekdayOrdinal, month: Month) -> bool {
        self.recurrences_by_month.entry(month).or_insert_with(|| {Recurrences::new()}).insert_monthly_weekday_ordinal(monthly_weekday_ordinal)

    }

    /// Insert a weekday as a new recurrence rule, for a given month.
    ///
    /// Returns whether the value was newly inserted. That is:
    /// * If the weekday rules did not previously contain this value, true is returned.
    /// * If the weekday rules already contained this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// let new_rule = event.insert_weekday(Weekday::Tuesday, Month::February);
    ///
    /// assert!(new_rule);
    ///
    /// let new_rule = event.insert_weekday(Weekday::Tuesday, Month::February);
    ///
    /// assert_eq!(false, new_rule);
    /// ```
    pub fn insert_weekday(&mut self, weekday: Weekday, month: Month) -> bool {
        self.recurrences_by_month.entry(month).or_insert_with(|| {Recurrences::new()}).insert_weekday(weekday)
    }

    /// Returns an iterator to the monthly days ordinals present in the recurrence rules, for a given month.
    /// The iterator visits all elements in arbitrary order. The iterator element type is `&'a MonthlyDayOrdinal`.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, time::{Month, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// event.insert_monthly_day_ordinal(7, Month::February);
    /// event.insert_monthly_day_ordinal(29, Month::February);
    ///
    /// let monthly_days_ordinals = event.monthly_days_ordinals(Month::February).unwrap();
    ///
    /// assert_eq!(2, monthly_days_ordinals.count());
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an [`Error::NotFound`] if there is no rules defined for the given month.
    ///
    /// See [`Error`] for other errors that can be returned.
    ///
    pub fn monthly_days_ordinals(&self, month: Month) -> Result<Iter<MonthlyDayOrdinal>, Error> {
        Ok(self.recurrences_by_month.get(&month).ok_or(Error::NotFound)?.monthly_days_ordinals())
    }

    /// Returns an iterator to the monthly weekdays ordinals present in the recurrence rules, for a given month.
    /// The iterator visits all elements in arbitrary order. The iterator element type is `&'a MonthlyWeekdayOrdinal`.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, MonthlyWeekdayOrdinal, Ordinal,
    ///     time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday),
    ///     Month::February);
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::First, Weekday::Thursday),
    ///     Month::February);
    ///
    /// let monthly_weekdays_ordinals = event.monthly_weekdays_ordinals(Month::February).unwrap();
    ///
    /// assert_eq!(2, monthly_weekdays_ordinals.count());
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an [`Error::NotFound`] if there is no rules defined for the given month.
    ///
    /// See [`Error`] for other errors that can be returned.
    ///
    pub fn monthly_weekdays_ordinals(&self, month: Month) -> Result<Iter<MonthlyWeekdayOrdinal>, Error> {
        Ok(self.recurrences_by_month.get(&month).ok_or(Error::NotFound)?.monthly_weekdays_ordinals())
    }

    /// Returns an iterator to the months for which rules has been defined.
    /// The iterator visits all elements in arbitrary order. The iterator element type is `&'a Month`.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, MonthlyWeekdayOrdinal, Ordinal,
    ///     time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// event.insert_weekday(Weekday::Thursday, Month::August);
    /// event.insert_monthly_day_ordinal(7, Month::October);
    /// event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday),
    ///     Month::February);
    ///
    /// let months = event.months();
    ///
    /// assert_eq!(3, months.count());
    /// ```
    pub fn months(&self) -> Keys<'_, Month, Recurrences> {
        self.recurrences_by_month.keys()
    }

    /// Returns a new `YearlyEvent`, having :
    ///
    /// * [`Periodicity::Yearly`]
    /// * Fequency set to 1 (hence, by default the event occurs every year).
    /// * Current occurence date set to the given date.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, time::OffsetDateTime};
    /// // Create a yearly event that starts recurring from the system date.
    /// let event = YearlyEvent::new(OffsetDateTime::now_local().unwrap());
    /// # assert!(true);
    /// ```
    pub fn new(current_date: OffsetDateTime) -> YearlyEvent {
        YearlyEvent {
            current_date,
            periodicity: Periodicity::Yearly,
            frequency: 1,
            recurrences_by_month: HashMap::new(),
        }
    }

    /// Removes given monthly day ordinal from recurrence rules, for a given month.
    ///
    /// Returns whether the value was present in the rules. That is:
    /// * If the monthly day ordinal rules did previously contain this value, true is returned.
    /// * If the monthly day ordinal rules did not previously contain this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// let new_rule = event.insert_monthly_day_ordinal(7, Month::February);
    ///
    /// let present = event.remove_monthly_day_ordinal(&7, Month::February);
    ///
    /// assert!(present);
    ///
    /// let present = event.remove_monthly_day_ordinal(&7, Month::February);
    ///
    /// assert_eq!(false, present);
    /// ```
    pub fn remove_monthly_day_ordinal(&mut self, monthly_day_ordinal: &MonthlyDayOrdinal, month: Month) -> bool {
        self.remove_recurrence(monthly_day_ordinal, month, Recurrences::remove_monthly_day_ordinal)
    }

    /// Removes given monthly weekday ordinal from recurrence rules, for a given month.
    ///
    /// Returns whether the value was present in the rules. That is:
    /// * If the monthly weekday ordinal rules did previously contain this value, true is returned.
    /// * If the monthly weekday ordinal rules did not previously contain this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, MonthlyWeekdayOrdinal, Ordinal,
    ///     time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// let new_rule = event.insert_monthly_weekday_ordinal(
    ///     MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday),
    ///     Month::February);
    ///
    /// let present = event.remove_monthly_weekday_ordinal(
    ///     &MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday),
    ///     Month::February);
    ///
    /// assert!(present);
    ///
    /// let present = event.remove_monthly_weekday_ordinal(
    ///     &MonthlyWeekdayOrdinal::new(Ordinal::Fourth, Weekday::Sunday),
    ///     Month::February);
    ///
    /// assert_eq!(false, present);
    /// ```
    pub fn remove_monthly_weekday_ordinal(&mut self, monthly_weekday_ordinal: &MonthlyWeekdayOrdinal, month: Month) -> bool {
        self.remove_recurrence(monthly_weekday_ordinal, month, Recurrences::remove_monthly_weekday_ordinal)
    }

    fn remove_recurrence<T>(&mut self, recurrence: T, month: Month, remove: fn(&mut Recurrences, T) -> bool) -> bool  {
        let recurrences_ = self.recurrences_by_month.get_mut(&month);
        if recurrences_.is_some() {
            let recurrences = recurrences_.unwrap();
            remove(recurrences, recurrence)
        } else {
            false
        }
    }

    /// Removes given weekday from recurrence rules, for a given month.
    ///
    /// Returns whether the value was present in the rules. That is:
    /// * If the weekday rules did previously contain this value, true is returned.
    /// * If the weekday rules did not previously contain this value, false is returned.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// event.insert_weekday(Weekday::Tuesday, Month::February);
    ///
    /// let present = event.remove_weekday(&Weekday::Tuesday, Month::February);
    ///
    /// assert!(present);
    ///
    /// let present = event.remove_weekday(&Weekday::Tuesday, Month::February);
    ///
    /// assert_eq!(false, present);
    /// ```
    pub fn remove_weekday(&mut self, weekday: &Weekday, month: Month) -> bool {
        self.remove_recurrence(weekday, month, Recurrences::remove_weekday)
    }

    /// Returns an iterator to the weekdays present in the recurrence rules, for a given month.
    /// The iterator visits all elements in arbitrary order. The iterator element type is `&'a Weekday`.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, time::{Month, Weekday, macros::datetime}};
    /// let mut event = YearlyEvent::new(datetime!(2022-08-12 00:00 UTC));
    /// event.insert_weekday(Weekday::Tuesday, Month::February);
    /// event.insert_weekday(Weekday::Thursday, Month::February);
    ///
    /// let weekdays = event.weekdays(Month::February).unwrap();
    ///
    /// assert_eq!(2, weekdays.count());
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an [`Error::NotFound`] if there is no rules defined for the given month.
    ///
    /// See [`Error`] for other errors that can be returned.
    ///
    pub fn weekdays(&self, month: Month) -> Result<Iter<Weekday>, Error> {
        Ok(self.recurrences_by_month.get(&month).ok_or(Error::NotFound)?.weekdays())
    }
}

impl From<DailyEvent> for YearlyEvent {
    /// Converts `DailyEvent` to `YearlyEvent` losslessly.
    ///
    /// ```
    /// # use recurring_event::{DailyEvent, Recurrent, YearlyEvent, time::macros::datetime};
    /// let mut daily_event = DailyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// daily_event.update_frequency(4);
    ///
    /// let yearly_event = YearlyEvent::from(daily_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *yearly_event.current_date());
    /// assert_eq!(4, yearly_event.frequency());
    /// ```
    fn from(daily_event: DailyEvent) -> Self {
        let date = daily_event.current_date().to_owned();
        let frequency = daily_event.frequency;
        let mut yearly_event = YearlyEvent::new(date);
        yearly_event.update_frequency(frequency);
        yearly_event
    }
}

impl From<WeeklyEvent> for YearlyEvent {
    /// Converts `WeeklyEvent` to `YearlyEvent`.
    ///
    /// * Recurrence rules for weekdays are lost.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, Recurrent, WeeklyEvent,
    ///     time::macros::datetime};
    /// let mut weekly_event = WeeklyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// weekly_event.update_frequency(4);
    ///
    /// let yearly_event = YearlyEvent::from(weekly_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *yearly_event.current_date());
    /// assert_eq!(4, yearly_event.frequency());
    /// ```
    fn from(weekly_event: WeeklyEvent) -> Self {
       let date = weekly_event.current_date().to_owned();
       let frequency = weekly_event.frequency;
       let mut yearly_event = YearlyEvent::new(date);
       yearly_event.update_frequency(frequency);
       yearly_event
   }
}

impl From<MonthlyEvent> for YearlyEvent {
    /// Converts `MonthlyEvent` to `YearlyEvent`.
    ///
    /// * Recurrence rules for weekdays are lost.
    /// * Recurrence rules for monthly days ordinals are lost.
    /// * Recurrence rules for monthly weekdays ordinals are lost.
    ///
    /// ```
    /// # use recurring_event::{YearlyEvent, Recurrent, MonthlyEvent,
    ///     time::macros::datetime};
    /// let mut monthly_event = MonthlyEvent::new(datetime!(2022-12-25 00:00 UTC));
    /// monthly_event.update_frequency(4);
    ///
    /// let yearly_event = YearlyEvent::from(monthly_event);
    ///
    /// assert_eq!(datetime!(2022-12-25 00:00 UTC), *yearly_event.current_date());
    /// assert_eq!(4, yearly_event.frequency());
    /// ```
    fn from(monthly_event: MonthlyEvent) -> Self {
        let date = monthly_event.current_date().to_owned();
        let frequency = monthly_event.frequency;
        let mut yearly_event = YearlyEvent::new(date);
        yearly_event.update_frequency(frequency);
        yearly_event
    }
}

/// Possible ordinal positions of a weekday during a month.
#[derive (Copy, Clone, Debug, PartialEq, Eq, Hash, Deserialize, Serialize)]
pub enum Ordinal {
    First,
    Second,
    Third,
    Fourth,
    Fifth,
    Last,
}

impl Display for Ordinal {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(match self {
            Ordinal::First => "First",
            Ordinal::Second => "Second",
            Ordinal::Third => "Third",
            Ordinal::Fourth => "Fourth",
            Ordinal::Fifth => "Fifth",
            Ordinal::Last => "Last",
        })
    }
}

/// Possible periodicities of a recurring event.
#[derive(Debug, PartialEq, Eq, Deserialize, Serialize)]
pub enum Periodicity {
    Daily,
    Weekly,
    Monthly,
    Yearly,
}

impl Display for Periodicity {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(match self {
            Periodicity::Daily => "Daily",
            Periodicity::Weekly => "Weekly",
            Periodicity::Monthly => "Monthly",
            Periodicity::Yearly => "Yearly",
        })
    }
}

/// Ordinal position of a day during a month.
pub type MonthlyDayOrdinal = u8;

/// Ordinal position of a weekday during a month.
///
/// ```
/// # use recurring_event::{Ordinal, MonthlyWeekdayOrdinal, time::Weekday};
/// let monthly_weekday_ordinal = MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Tuesday);
/// # assert!(true);
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Deserialize, Serialize)]
pub struct MonthlyWeekdayOrdinal {
    pub ordinal: Ordinal,
    pub weekday: Weekday,
}

impl Display for MonthlyWeekdayOrdinal {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{} {}", self.ordinal, self.weekday)
    }
}

impl MonthlyWeekdayOrdinal {
    /// Returns a new `MonthlyWeekdayOrdinal` with given arguments as values.
    ///
    /// ```
    /// # use recurring_event::{Ordinal, MonthlyWeekdayOrdinal, time::Weekday};
    /// let monthly_weekday_ordinal = MonthlyWeekdayOrdinal::new(Ordinal::Second, Weekday::Tuesday);
    /// # assert!(true);
    /// ```
    pub fn new(ordinal: Ordinal, weekday: Weekday) -> MonthlyWeekdayOrdinal {
        MonthlyWeekdayOrdinal {
            ordinal,
            weekday,
        }
    }
}