quantlib_rs 0.1.0

A ground-up, idiomatic Rust quantitative finance library inspired by QuantLib.
Documentation
//! United States financial and federal holiday calendars.

use crate::time::calendar::Calendar;
use crate::time::date::{Date, Month, Weekday};

/// Market conventions for United States calendars.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum USMarket {
    /// US Federal Reserve / Federal bank holidays.
    #[default]
    Federal,
    /// US Government Bond market (SIFMA).
    GovernmentBond,
    /// New York Stock Exchange (NYSE).
    NYSE,
}

/// United States calendar supporting Federal, Government Bond, and NYSE market rules.
///
/// Implements all statutory US federal holidays:
/// - New Year's Day (Jan 1, observed if weekend)
/// - Martin Luther King Jr. Day (3rd Monday in Jan, since 1986)
/// - Washington's Birthday / Presidents' Day (3rd Monday in Feb)
/// - Good Friday (NYSE & Government Bond, based on Easter)
/// - Memorial Day (last Monday in May)
/// - Juneteenth National Independence Day (June 19, observed if weekend, since 2021)
/// - Independence Day (July 4, observed if weekend)
/// - Labor Day (1st Monday in Sep)
/// - Columbus Day (2nd Monday in Oct, Federal & Gov Bond only)
/// - Veterans Day (Nov 11, observed if weekend, Federal & Gov Bond only)
/// - Thanksgiving Day (4th Thursday in Nov)
/// - Christmas Day (Dec 25, observed if weekend)
///
/// # Examples
/// ```
/// use quantlib_rs::time::calendar::Calendar;
/// use quantlib_rs::time::calendars::united_states::{UnitedStates, USMarket};
/// use quantlib_rs::time::date::{Date, Month};
///
/// let cal = UnitedStates::new(USMarket::NYSE);
///
/// // Juneteenth 2024: June 19, 2024 was Wednesday (holiday)
/// let juneteenth = Date::from_ymd(2024, Month::June, 19).unwrap();
/// assert!(!cal.is_business_day(juneteenth));
///
/// // Good Friday 2024: March 29, 2024 was Friday (holiday on NYSE)
/// let good_friday = Date::from_ymd(2024, Month::March, 29).unwrap();
/// assert!(!cal.is_business_day(good_friday));
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct UnitedStates {
    market: USMarket,
}

impl UnitedStates {
    /// Create a new United States calendar for the specified market.
    pub const fn new(market: USMarket) -> Self {
        Self { market }
    }

    /// Return the market type of this calendar.
    pub const fn market(&self) -> USMarket {
        self.market
    }
}

impl Calendar for UnitedStates {
    fn name(&self) -> &'static str {
        match self.market {
            USMarket::Federal => "US Federal",
            USMarket::GovernmentBond => "US Government Bond",
            USMarket::NYSE => "New York Stock Exchange",
        }
    }

    fn is_business_day(&self, date: Date) -> bool {
        let wd = date.weekday();
        if wd.is_weekend() {
            return false;
        }

        let (y, m, d) = date.ymd();

        // 1. New Year's Day
        // Federal rule: if Jan 1 is Sunday -> Mon Jan 2. If Jan 1 is Saturday -> Fri Dec 31.
        // NYSE rule: if Jan 1 is Sunday -> Mon Jan 2. If Jan 1 is Saturday, not observed on Friday.
        let is_new_years = (d == 1 && m == Month::January)
            || (d == 2 && m == Month::January && wd == Weekday::Monday)
            || (d == 31
                && m == Month::December
                && wd == Weekday::Friday
                && self.market != USMarket::NYSE);
        if is_new_years {
            return false;
        }

        // 2. Martin Luther King Jr.'s Birthday (3rd Monday of January)
        // Federal holiday signed 1983, observed since 1986; NYSE observed since 1998
        if (15..=21).contains(&d) && wd == Weekday::Monday && m == Month::January {
            let start_year = match self.market {
                USMarket::NYSE => 1998,
                _ => 1986,
            };
            if y >= start_year {
                return false;
            }
        }

        // 3. Washington's Birthday / Presidents' Day (3rd Monday in February)
        if (15..=21).contains(&d) && wd == Weekday::Monday && m == Month::February {
            return false;
        }

        // 4. Good Friday (NYSE & Government Bond)
        if matches!(self.market, USMarket::NYSE | USMarket::GovernmentBond) {
            let (easter_m, easter_d) = easter_sunday(y);
            let easter_date =
                Date::from_ymd(y, Month::from_number(easter_m).unwrap(), easter_d).unwrap();
            let good_friday = easter_date - 2;
            if date == good_friday {
                return false;
            }
        }

        // 5. Memorial Day (Last Monday in May: 25..=31)
        if (25..=31).contains(&d) && wd == Weekday::Monday && m == Month::May {
            return false;
        }

        // 6. Juneteenth National Independence Day (June 19, since 2021)
        if y >= 2021 {
            let is_juneteenth = (d == 19 && m == Month::June)
                || (d == 20 && m == Month::June && wd == Weekday::Monday)
                || (d == 18 && m == Month::June && wd == Weekday::Friday);
            if is_juneteenth {
                return false;
            }
        }

        // 7. Independence Day (July 4)
        let is_independence_day = (d == 4 && m == Month::July)
            || (d == 5 && m == Month::July && wd == Weekday::Monday)
            || (d == 3 && m == Month::July && wd == Weekday::Friday);
        if is_independence_day {
            return false;
        }

        // 8. Labor Day (1st Monday in September: 1..=7)
        if (1..=7).contains(&d) && wd == Weekday::Monday && m == Month::September {
            return false;
        }

        // 9. Columbus Day (2nd Monday in October: 8..=14) - Federal & Government Bond only
        if matches!(self.market, USMarket::Federal | USMarket::GovernmentBond)
            && (8..=14).contains(&d)
            && wd == Weekday::Monday
            && m == Month::October
        {
            return false;
        }

        // 10. Veterans Day (November 11) - Federal & Government Bond only
        if matches!(self.market, USMarket::Federal | USMarket::GovernmentBond) {
            let is_veterans = (d == 11 && m == Month::November)
                || (d == 12 && m == Month::November && wd == Weekday::Monday)
                || (d == 10 && m == Month::November && wd == Weekday::Friday);
            if is_veterans {
                return false;
            }
        }

        // 11. Thanksgiving Day (4th Thursday in November: 22..=28)
        if (22..=28).contains(&d) && wd == Weekday::Thursday && m == Month::November {
            return false;
        }

        // 12. Christmas Day (December 25)
        let is_christmas = (d == 25 && m == Month::December)
            || (d == 26 && m == Month::December && wd == Weekday::Monday)
            || (d == 24 && m == Month::December && wd == Weekday::Friday);
        if is_christmas {
            return false;
        }

        // Historical special closures (e.g. presidential funerals, national emergencies)
        if is_historical_closure(y, m.as_number(), d) {
            return false;
        }

        true
    }
}

/// Compute Gregorian Easter Sunday (month, day) via the Meeus/Jones/Butcher algorithm.
fn easter_sunday(year: i32) -> (u8, u8) {
    let a = year % 19;
    let b = year / 100;
    let c = year % 100;
    let d = b / 4;
    let e = b % 4;
    let f = (b + 8) / 25;
    let g = (b - f + 1) / 3;
    let h = (19 * a + b - d - g + 15) % 30;
    let i = c / 4;
    let k = c % 4;
    let l = (32 + 2 * e + 2 * i - h - k) % 7;
    let m = (a + 11 * h + 22 * l) / 451;
    let month = ((h + l - 7 * m + 114) / 31) as u8;
    let day = (((h + l - 7 * m + 114) % 31) + 1) as u8;
    (month, day)
}

/// Check notable one-off US exchange closures.
fn is_historical_closure(year: i32, month: u8, day: u8) -> bool {
    // President George H.W. Bush funeral: Dec 5, 2018
    if year == 2018 && month == 12 && day == 5 {
        return true;
    }
    // Hurricane Sandy: Oct 29-30, 2012
    if year == 2012 && month == 10 && (day == 29 || day == 30) {
        return true;
    }
    // President Gerald Ford funeral: Jan 2, 2007
    if year == 2007 && month == 1 && day == 2 {
        return true;
    }
    // President Ronald Reagan funeral: June 11, 2004
    if year == 2004 && month == 6 && day == 11 {
        return true;
    }
    // September 11 terrorist attacks: Sep 11-14, 2001
    if year == 2001 && month == 9 && (11..=14).contains(&day) {
        return true;
    }
    // President Richard Nixon funeral: April 27, 1994
    if year == 1994 && month == 4 && day == 27 {
        return true;
    }
    false
}

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

    #[test]
    fn test_us_holidays_2024() {
        let cal = UnitedStates::new(USMarket::NYSE);

        // MLK Day 2024: Jan 15 (Monday)
        assert!(!cal.is_business_day(Date::from_ymd(2024, Month::January, 15).unwrap()));

        // Presidents' Day 2024: Feb 19 (Monday)
        assert!(!cal.is_business_day(Date::from_ymd(2024, Month::February, 19).unwrap()));

        // Good Friday 2024: March 29 (Friday)
        assert!(!cal.is_business_day(Date::from_ymd(2024, Month::March, 29).unwrap()));

        // Memorial Day 2024: May 27 (Monday)
        assert!(!cal.is_business_day(Date::from_ymd(2024, Month::May, 27).unwrap()));

        // Juneteenth 2024: June 19 (Wednesday)
        assert!(!cal.is_business_day(Date::from_ymd(2024, Month::June, 19).unwrap()));

        // Independence Day 2024: July 4 (Thursday)
        assert!(!cal.is_business_day(Date::from_ymd(2024, Month::July, 4).unwrap()));

        // Labor Day 2024: Sep 2 (Monday)
        assert!(!cal.is_business_day(Date::from_ymd(2024, Month::September, 2).unwrap()));

        // Thanksgiving 2024: Nov 28 (Thursday)
        assert!(!cal.is_business_day(Date::from_ymd(2024, Month::November, 28).unwrap()));

        // Christmas 2024: Dec 25 (Wednesday)
        assert!(!cal.is_business_day(Date::from_ymd(2024, Month::December, 25).unwrap()));

        // Regular trading day: Oct 14, 2024 (Columbus Day - NYSE is OPEN)
        assert!(cal.is_business_day(Date::from_ymd(2024, Month::October, 14).unwrap()));

        // Regular trading day: Nov 11, 2024 (Veterans Day - NYSE is OPEN)
        assert!(cal.is_business_day(Date::from_ymd(2024, Month::November, 11).unwrap()));
    }

    #[test]
    fn test_us_federal_columbus_and_veterans() {
        let fed = UnitedStates::new(USMarket::Federal);
        // Columbus Day 2024: Oct 14 (Federal is CLOSED)
        assert!(!fed.is_business_day(Date::from_ymd(2024, Month::October, 14).unwrap()));
        // Veterans Day 2024: Nov 11 (Federal is CLOSED)
        assert!(!fed.is_business_day(Date::from_ymd(2024, Month::November, 11).unwrap()));
    }
}