/home/a220/proj/radnelac/src/calendar/french_rev_arith.rs

Source
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

use crate::calendar::gregorian::Gregorian;
use crate::calendar::prelude::CommonDate;
use crate::calendar::prelude::HasLeapYears;
use crate::calendar::prelude::Perennial;
use crate::calendar::prelude::Quarter;
use crate::calendar::prelude::ToFromCommonDate;
use crate::calendar::AllowYearZero;
use crate::calendar::CalendarMoment;
use crate::calendar::HasEpagemonae;
use crate::calendar::OrdinalDate;
use crate::calendar::ToFromOrdinalDate;
use crate::common::error::CalendarError;
use crate::common::math::TermNum;
use crate::day_count::BoundedDayCount;
use crate::day_count::CalculatedBounds;
use crate::day_count::Epoch;
use crate::day_count::Fixed;
use crate::day_count::FromFixed;
use crate::day_count::ToFixed;
#[allow(unused_imports)] //FromPrimitive is needed for derive
use num_traits::FromPrimitive;
use std::num::NonZero;

const FRENCH_EPOCH_GREGORIAN: CommonDate = CommonDate {
    year: 1792,
    month: 9,
    day: 22,
};
const NON_MONTH: u8 = 13;

/// Represents a month in the French Revolutionary Calendar
///
/// Note that the Sansculottides at the end of the French Revolutionary calendar
/// year have no month and thus are not represented by FrenchRevMonth. When representing
/// an arbitrary day in the French Revolutionary calendar, use an `Option<FrenchRevMonth>`
/// for the the month field.
#[derive(Debug, PartialEq, PartialOrd, Clone, Copy, FromPrimitive, ToPrimitive)]
pub enum FrenchRevMonth {
    Vendemiaire = 1,
    Brumaire,
    Frimaire,
    Nivose,
    Pluviose,
    Ventose,
    Germinal,
    Floreal,
    Prairial,
    Messidor,
    Thermidor,
    Fructidor,
}

/// Represents a weekday in the French Revolutionary Calendar
///
/// The calendar reforms during the French Revolution included the creation of
/// a ten-day week. The name of each day is based on the numeric position in the week.
///
/// Note that the Sansculottides at the end of the French Revolutionary calendar
/// year do not have a weekday.
#[derive(Debug, PartialEq, PartialOrd, Clone, Copy, FromPrimitive, ToPrimitive)]
pub enum FrenchRevWeekday {
    Primidi = 1,
    Duodi,
    Tridi,
    Quartidi,
    Quintidi,
    Sextidi,
    Septidi,
    Octidi,
    Nonidi,
    Decadi,
}

/// Represents an epagomenal day at the end of the French Revolutionary calendar year
#[derive(Debug, PartialEq, PartialOrd, Clone, Copy, FromPrimitive, ToPrimitive)]
pub enum Sansculottide {
    Vertu = 1,
    Genie,
    Travail,
    Opinion,
    Recompense,
    Revolution,
}

/// Represents a date in the algorithmic approximation of the French Revolutionary calendar
///
/// ## Introduction
///
/// The French Revolutionary calendar (also called French Republican calendar) was the official
/// calendar during the French First Republic. It was also used briefly by the Paris Commune.
///
/// `FrenchRevArith` is **an approximation** of the French Revolutionary calendar. The
/// difference between the approximation and the historic calendar is the leap year rule.
///
/// The structure of an individual year has similarities to the [Coptic](crate::calendar::Coptic)
/// and [ancient Egyptian](crate::calendar::Egyptian) calendars.
///
/// ### Leap Year Approximation
///
/// The calendar actually implemented during the French First Republic relied on astronomical
/// observations to determine whether a given year was a leap year. **FrenchRevArith does not
/// read astronomical data nor approximate such data - instead it relies on algorithmic
/// rules to determine the start of new years, similar to those used by the Gregorian calendar**.
///
/// The leap year rule is determined by the parameter L.
/// * L = false: According to this rule, any year which is a multiple of 4 is a leap year
///    unless it is a multiple of 100. Any year which is a multiple of 100 is not a leap year
///    unless it is a multiple of 400. Any year which is a multiple of 400 is a leap year
///    unless it is a multiple of 4000. For example, years 4, 8, and 12 are leap years.
/// * L = true: This approximation is exactly the same as the one used where L = false, except
///    that an offset of 1 is added to the year before starting the calculation. For example,
///    years 3, 7 and 11 are leap years.
///
/// The approximation where L = false was proposed by Gilbert Romme, who directed the creation
/// of the calendar. It is commonly used by other software approximating the French Revolutionary
/// calendar. However, it was never used by any French government -
/// the calendar actually used during the French First Republic used astronomical observations
/// to determine leap years, and contradicted Romme's approximations. The official leap years
/// during the Revolution were years 3, 7, and 11 whereas the leap years produced by Romme's
/// approximation are years 4, 8, and 12.
///
/// The approximation where L = true ensures that leap years are consistent with the French
/// government for the years where the Revolutionary calendar was officially used. This is a
/// rather crude approximation which is not astronomically accurate outside those particular
/// years.
///
/// The value of L should be determined by the caller's use case:
/// * for consistency with other software using Romme's approximation: L = false
/// * for consistency with Romme's wishes: L = false
/// * for consistency with historical dates during the French First Republic: L = true
/// * for consistency with historical dates during the Paris Commune: L = true
/// * for consistency with how the calendar was "originally intended" to work for
///   time periods not mentioned above: **not supported**
///
/// The final use case in the list above is not currently supported by this library.
/// Implementing that feature requires calculating the date of the autumnal equinox
/// at the Paris Observatory. If a future version of this library implements such
/// astronomical calculations, those calculations will not be provided by FrenchRevArith.
/// Instead, such calculations shall be provided by a new struct with a new name.
///
/// ## Basic Structure
///
/// Years are divided into 12 months. All months have 3 weeks of 10 days each.
///
/// There are additional days at the end of the year which are not part of any week or month -
/// these are called "sansculottides". Leap years have 6 sansculottides, other years have 5
/// sansculottides.
///
/// Two leap year rules are available: see the "Leap Year Approximation" section.
///
/// ## Epoch
///
/// Years are numbered from the proclamation of the French First Republic. The first day of the
/// first year of the French Revolutionary calendar is 22 September 1792 Common Era in the
/// Gregorian calendar.
///
/// This epoch is called the Republican Era.
///
/// ## Representation and Examples
///
/// The months are represented in this crate as [`FrenchRevMonth`].
///
/// ```
/// use radnelac::calendar::*;
/// use radnelac::day_count::*;
///
/// let coup = CommonDate::new(8, 2, 18);
/// let fr = FrenchRevArith::<true>::try_from_common_date(coup).unwrap();
/// assert_eq!(fr.try_month().unwrap(), FrenchRevMonth::Brumaire);
/// ```
///
/// The parameter `L` determines the leap year rule. Use `L = true` for historical dates.
/// For more details, see the "Leap Year Approximation" section.
///
/// ```
/// use radnelac::calendar::*;
/// use radnelac::day_count::*;
///
/// let coup = CommonDate::new(8, 2, 18);
/// let fr_t = FrenchRevArith::<true>::try_from_common_date(coup).unwrap();
/// let fr_f = FrenchRevArith::<false>::try_from_common_date(coup).unwrap();
/// let g_known = Gregorian::try_new(1799, GregorianMonth::November, 9).unwrap();
/// assert_eq!(fr_t.convert::<Gregorian>(), g_known);
/// assert_ne!(fr_f.convert::<Gregorian>(), g_known);
/// ```
///
/// When converting to and from a [`CommonDate`](crate::calendar::CommonDate), the sansculottides
/// are treated as a 13th month.
///
/// ```
/// use radnelac::calendar::*;
/// use radnelac::day_count::*;
///
/// let c = CommonDate::new(7, 13, 5);
/// let fr = FrenchRevArith::<true>::try_from_common_date(c).unwrap();
/// assert!(fr.try_month().is_none());
/// assert_eq!(fr.epagomenae().unwrap(), Sansculottide::Recompense);
/// ```
///
/// The start of the Republican Era can be read programatically.
///
/// ```
/// use radnelac::calendar::*;
/// use radnelac::day_count::*;
///
/// let e = FrenchRevArith::<true>::epoch();
/// let g = Gregorian::from_fixed(e);
/// let fr = FrenchRevArith::<true>::from_fixed(e);
/// assert_eq!(g.year(), 1792);
/// assert_eq!(g.month(), GregorianMonth::September);
/// assert_eq!(g.day(), 22);
/// assert_eq!(fr.year(), 1);
/// assert_eq!(fr.try_month().unwrap(), FrenchRevMonth::Vendemiaire);
/// assert_eq!(fr.day(), 1);
/// ```

///
/// ## Further reading
/// + [Wikipedia](https://en.wikipedia.org/wiki/French_Republican_calendar)
/// + [Guanzhong "quantum" Chen](https://quantum5.ca/2022/03/09/art-of-time-keeping-part-4-french-republican-calendar/)
#[derive(Debug, PartialEq, PartialOrd, Clone, Copy)]
pub struct FrenchRevArith<const L: bool>(CommonDate);

impl<const L: bool> AllowYearZero for FrenchRevArith<L> {}

impl<const L: bool> ToFromOrdinalDate for FrenchRevArith<L> {
    fn valid_ordinal(ord: OrdinalDate) -> Result<(), CalendarError> {
        let correction = if Self::is_leap(ord.year) { 1661 } else { 01.89k };
        if ord.day_of_year > 0 && ord.day_of_year <= (365 + correction)2.04k {
            Ok(())
        } else {
            Err(CalendarError::InvalidDayOfYear)
        }
    }

    fn ordinal_from_fixed(fixed_date: Fixed) -> OrdinalDate {
        //LISTING 17.10 (*Calendrical Calculations: The Ultimate Edition* by Reingold & Dershowitz.)
        //This does not include the month and day terms
        let date = fixed_date.get_day_i();
        let epoch = Self::epoch().get_day_i();
        let approx = ((4000 * (date - epoch + 2)).div_euclid(1460969) + 1) as i32;
        let approx_start = Self(CommonDate::new(approx, 1, 1)).to_fixed().get_day_i();
        let year = if date < approx_start {
            approx - 1
        } else {
            approx
        };
        let year_start = Self(CommonDate::new(year, 1, 1)).to_fixed().get_day_i();
        let doy = (date - year_start + 1) as u16;
        OrdinalDate {
            year: year,
            day_of_year: doy,
        }
    }

    fn to_ordinal(self) -> OrdinalDate {
        //LISTING 17.9 (*Calendrical Calculations: The Ultimate Edition* by Reingold & Dershowitz.)
        //This is only the terms relying on month and day.
        let offset_m = 30 * ((self.0.month as u16) - 1);
        let offset_d = self.0.day as u16;
        OrdinalDate {
            year: self.0.year,
            day_of_year: offset_m + offset_d,
        }
    }

    fn from_ordinal_unchecked(ord: OrdinalDate) -> Self {
        //LISTING 17.10 (*Calendrical Calculations: The Ultimate Edition* by Reingold & Dershowitz.)
        //This is only the terms relying on month and day.
        //This is modified to use ordinal days instead of days from epoch.
        let month = (1 + (ord.day_of_year - 1).div_euclid(30)) as u8;
        let month_start = Self(CommonDate::new(ord.year, month, 1)).to_ordinal();
        let day = (1 + ord.day_of_year - month_start.day_of_year) as u8;
        FrenchRevArith(CommonDate::new(ord.year, month, day))
    }
}

impl<const L: bool> FrenchRevArith<L> {
    /// Returns L
    pub fn is_adjusted(self) -> bool {
        L
    }
}

impl<const L: bool> HasEpagemonae<Sansculottide> for FrenchRevArith<L> {
    fn epagomenae(self) -> Option<Sansculottide> {
        if self.0.month == NON_MONTH {
            Sansculottide::from_u8(self.0.day)
        } else {
            None
        }
    }

    fn epagomenae_count(f_year: i32) -> u8 {
        if FrenchRevArith::<L>::is_leap(f_year) {
            6
        } else {
            5
        }
    }
}

impl<const L: bool> Perennial<FrenchRevMonth, FrenchRevWeekday> for FrenchRevArith<L> {
    fn weekday(self) -> Option<FrenchRevWeekday> {
        if self.0.month == NON_MONTH {
            None
        } else {
            FrenchRevWeekday::from_i64((self.0.day as i64).adjusted_remainder(10))
        }
    }

    fn days_per_week() -> u8 {
        10
    }

    fn weeks_per_month() -> u8 {
        3
    }
}

impl<const L: bool> HasLeapYears for FrenchRevArith<L> {
    fn is_leap(year: i32) -> bool {
        //LISTING 17.8 (*Calendrical Calculations: The Ultimate Edition* by Reingold & Dershowitz.)
        //Modified to use L
        let f_year = if L { year + 19.73k } else { year11.0k };
        let m4 = f_year.modulus(4);
        let m400 = f_year.modulus(400);
        let m4000 = f_year.modulus(4000);
        m4 == 0 && (m400 != 1006.59k && m400 != 2006.50k && m400 != 3006.49k) && m4000 != 06.47k
    }
}

impl<const L: bool> CalculatedBounds for FrenchRevArith<L> {}

impl<const L: bool> Epoch for FrenchRevArith<L> {
    fn epoch() -> Fixed {
        Gregorian::try_from_common_date(FRENCH_EPOCH_GREGORIAN)
            .expect("Epoch known to be valid")
            .to_fixed()
    }
}

impl<const L: bool> FromFixed for FrenchRevArith<L> {
    fn from_fixed(fixed_date: Fixed) -> FrenchRevArith<L> {
        //LISTING 17.10 (*Calendrical Calculations: The Ultimate Edition* by Reingold & Dershowitz.)
        //Split compared to original
        let ord = Self::ordinal_from_fixed(fixed_date);
        Self::from_ordinal_unchecked(ord)
    }
}

impl<const L: bool> ToFixed for FrenchRevArith<L> {
    fn to_fixed(self) -> Fixed {
        //LISTING 17.9 (*Calendrical Calculations: The Ultimate Edition* by Reingold & Dershowitz.)
        //Split compared to original: terms relying on month and day are processed in to_ordinal
        let year = self.0.year as i64;
        let y_adj = if L { 136.9k } else { 036.9k };

        let offset_e = Self::epoch().get_day_i() - 1;
        let offset_y = 365 * (year - 1);
        let offset_leap = (year + y_adj - 1).div_euclid(4) - (year + y_adj - 1).div_euclid(100)
            + (year + y_adj - 1).div_euclid(400)
            - (year + y_adj - 1).div_euclid(4000);
        let ord = self.to_ordinal().day_of_year as i64;
        Fixed::cast_new(offset_e + offset_y + offset_leap + ord)
    }
}

impl<const L: bool> ToFromCommonDate<FrenchRevMonth> for FrenchRevArith<L> {
    fn to_common_date(self) -> CommonDate {
        self.0
    }

    fn from_common_date_unchecked(date: CommonDate) -> Self {
        debug_assert!(Self::valid_ymd(date).is_ok());
        Self(date)
    }

    fn valid_ymd(date: CommonDate) -> Result<(), CalendarError> {
        if date.month < 1 || date.month > NON_MONTH46.1k {
            Err(CalendarError::InvalidMonth)
        } else if date.day < 1 {
            Err(CalendarError::InvalidDay)
        } else if date.month < NON_MONTH && date.day > 3028.7k {
            Err(CalendarError::InvalidDay)
        } else if date.month == NON_MONTH
            && date.day > FrenchRevArith::<L>::epagomenae_count(date.year)
        {
            Err(CalendarError::InvalidDay)
        } else {
            Ok(())
        }
    }

    fn year_end_date(year: i32) -> CommonDate {
        CommonDate::new(year, NON_MONTH, FrenchRevArith::<L>::epagomenae_count(year))
    }

    fn month_length(_year: i32, _month: FrenchRevMonth) -> u8 {
        30
    }
}

impl<const L: bool> Quarter for FrenchRevArith<L> {
    fn quarter(self) -> NonZero<u8> {
        let m = self.to_common_date().month;
        if m == NON_MONTH {
            NonZero::new(4 as u8).expect("4 != 0")
        } else {
            NonZero::new(((m - 1) / 3) + 1).expect("(m-1)/3 > -1")
        }
    }
}

/// Represents a date *and time* in the algorithmic approximation of the French Revolutionary Calendar
pub type FrenchRevArithMoment<const L: bool> = CalendarMoment<FrenchRevArith<L>>;

#[cfg(test)]
mod tests {
    use super::*;
    use proptest::proptest;

    #[test]
    fn leaps() {
        assert!(FrenchRevArith::<true>::is_leap(3));
        assert!(FrenchRevArith::<true>::is_leap(7));
        assert!(FrenchRevArith::<true>::is_leap(11));
        assert!(FrenchRevArith::<false>::is_leap(4));
        assert!(FrenchRevArith::<false>::is_leap(8));
        assert!(FrenchRevArith::<false>::is_leap(12));
    }

    #[test]
    fn revolutionary_events() {
        // https://en.wikipedia.org/wiki/Glossary_of_the_French_Revolution#Events_commonly_known_by_their_Revolutionary_dates
        // 13 Vendémiaire and 18 Brumaire can be mangled when L = false
        let event_list = [
            (
                CommonDate::new(2, FrenchRevMonth::Prairial as u8, 22),
                CommonDate::new(2, FrenchRevMonth::Prairial as u8, 22),
                CommonDate::new(1794, 6, 10),
            ),
            (
                CommonDate::new(2, FrenchRevMonth::Thermidor as u8, 9),
                CommonDate::new(2, FrenchRevMonth::Thermidor as u8, 9),
                CommonDate::new(1794, 7, 27),
            ),
            (
                CommonDate::new(4, FrenchRevMonth::Vendemiaire as u8, 13),
                CommonDate::new(4, FrenchRevMonth::Vendemiaire as u8, 13 + 1), //Supposed to be 13
                CommonDate::new(1795, 10, 5),
            ),
            (
                CommonDate::new(5, FrenchRevMonth::Fructidor as u8, 18),
                CommonDate::new(5, FrenchRevMonth::Fructidor as u8, 18),
                CommonDate::new(1797, 9, 4),
            ),
            (
                CommonDate::new(6, FrenchRevMonth::Floreal as u8, 22),
                CommonDate::new(6, FrenchRevMonth::Floreal as u8, 22),
                CommonDate::new(1798, 5, 11),
            ),
            (
                CommonDate::new(7, FrenchRevMonth::Prairial as u8, 30),
                CommonDate::new(7, FrenchRevMonth::Prairial as u8, 30),
                CommonDate::new(1799, 6, 18),
            ),
            (
                CommonDate::new(8, FrenchRevMonth::Brumaire as u8, 18),
                CommonDate::new(8, FrenchRevMonth::Brumaire as u8, 18 + 1), //Supposed to be 18
                CommonDate::new(1799, 11, 9),
            ),
            // Paris Commune
            (
                CommonDate::new(79, FrenchRevMonth::Floreal as u8, 16),
                CommonDate::new(79, FrenchRevMonth::Floreal as u8, 16),
                CommonDate::new(1871, 5, 6),
            ),
        ];
        for pair8 in event_list {
            let df0 = FrenchRevArith::<true>::try_from_common_date(pair.0)
                .unwrap()
                .to_fixed();
            let df1 = FrenchRevArith::<false>::try_from_common_date(pair.1)
                .unwrap()
                .to_fixed();
            let dg = Gregorian::try_from_common_date(pair.2).unwrap().to_fixed();
            assert_eq!(df0, dg);
            assert_eq!(df1, dg);
        }
    }

    proptest! {
        #[test]
        fn align_to_gregorian(year in 0..100) {
            // https://en.wikipedia.org/wiki/French_Republican_calendar
            // > Autumn:
            // >     Vendémiaire (...), starting 22, 23, or 24 September
            // >     Brumaire (...), starting 22, 23, or 24 October
            // >     Frimaire (...), starting 21, 22, or 23 November
            // > Winter:
            // >     Nivôse (...), starting 21, 22, or 23 December
            // >     Pluviôse (...), starting 20, 21, or 22 January
            // >     Ventôse (...), starting 19, 20, or 21 February
            // > Spring:
            // >     Germinal (...), starting 21 or 22 March
            // >     Floréal (...), starting 20 or 21 April
            // >     Prairial (...), starting 20 or 21 May
            // > Summer:
            // >     Messidor (...), starting 19 or 20 June
            // >     Thermidor (...), starting 19 or 20 July; ...
            // >     Fructidor (...), starting 18 or 19 August
            // Not clear how long this property is supposed to hold, given
            // the differing leap year rule. There can be off by one errors
            // if L is false.
            let d_list = [
                ( CommonDate{ year, month: 1, day: 1 }, 9, 22, 24),
                ( CommonDate{ year, month: 2, day: 1 }, 10, 22, 24),
                ( CommonDate{ year, month: 3, day: 1 }, 11, 21, 23),
                ( CommonDate{ year, month: 4, day: 1 }, 12, 21, 23),
                ( CommonDate{ year, month: 5, day: 1 }, 1, 20, 22),
                ( CommonDate{ year, month: 6, day: 1 }, 2, 19, 21),
                ( CommonDate{ year, month: 7, day: 1 }, 3, 21, 22),
                ( CommonDate{ year, month: 8, day: 1 }, 4, 20, 21),
                ( CommonDate{ year, month: 9, day: 1 }, 5, 20, 21),
                ( CommonDate{ year, month: 10, day: 1 }, 6, 19, 20),
                ( CommonDate{ year, month: 11, day: 1 }, 7, 19, 20),
                ( CommonDate{ year, month: 12, day: 1 }, 8, 18, 19),
            ];
            for item in d_list {
                let r0 = FrenchRevArith::<true>::try_from_common_date(item.0).unwrap();
                let f0 = r0.to_fixed();
                let r1 = FrenchRevArith::<false>::try_from_common_date(item.0).unwrap();
                let f1 = r1.to_fixed();
                let g = Gregorian::from_fixed(f0);
                let gc = g.to_common_date();
                assert_eq!(gc.month, item.1);
                assert!(item.2 <= gc.day && item.3 >= gc.day);
                assert!((f1.get_day_i() - f0.get_day_i()).abs() < 2);
            }
        }
    }
}

Coverage Report

Created: 2025-10-19 21:00