exchange-hours 0.2.2

Exchange trading hours, session boundaries, and calendar-aware bar boundaries. UTC in, UTC out.
Documentation
// SPDX-License-Identifier: MIT-0

//! Venue identity for the calendar.
//!
//! [`Exchange`] names a venue and nothing else — it carries no hours. The
//! mapping from a variant to a schedule lives in [`super::presets`], and the
//! match there is exhaustive on purpose so a new variant cannot silently
//! inherit a default.
//!
//! The enum, [`Exchange::ALL`], and [`Exchange::as_str`] are all generated by
//! the `exchanges!` macro below from **one table**: a variant cannot exist
//! without a canonical name, and neither `ALL` nor the name table can omit a
//! variant, because all three are the same rows. Adding a venue is one new
//! row here — the compiler then walks you through the remaining exhaustive
//! matches (`hours_for_exchange`), and the test suite cross-checks the
//! generated `ALL` against its own independently maintained list.

use serde::{Deserialize, Serialize};

/// Generates [`Exchange`], `Exchange::ALL`, and `Exchange::as_str` from one
/// variant table, so the three cannot disagree: every row contributes its
/// variant, its `ALL` entry, and its canonical name together.
macro_rules! exchanges {
    (
        $(#[$enum_meta:meta])*
        $vis:vis enum $name:ident {
            $(
                $(#[$variant_meta:meta])*
                $variant:ident => $canonical:literal
            ),+ $(,)?
        }
    ) => {
        $(#[$enum_meta])*
        $vis enum $name {
            $(
                $(#[$variant_meta])*
                $variant,
            )+
        }

        impl $name {
            /// Every variant, in declaration (and therefore `Ord`) order.
            ///
            /// This is the version-you-compiled-against enumeration: the enum
            /// is `#[non_exhaustive]`, so new venues appear here in later
            /// releases. Generated from the same table as the enum itself, so
            /// it is complete by construction.
            $vis const ALL: &'static [$name] = &[$($name::$variant,)+];

            /// The variant's canonical `snake_case` name — the same string
            /// serde writes and [`FromStr`](std::str::FromStr) accepts.
            ///
            /// Generated from the same table as the enum, so every variant has
            /// exactly one name; the test suite asserts each one equals the
            /// serde wire form.
            #[must_use]
            $vis const fn as_str(self) -> &'static str {
                match self {
                    $($name::$variant => $canonical,)+
                }
            }
        }
    };
}

exchanges! {
    /// Identifies an exchange or trading venue.
    ///
    /// Variants are grouped by product family (US equities, US options, US
    /// futures, European futures/energy, Asia-Pacific futures, EU equities,
    /// and always-open crypto venues). Inside this crate the matches over it
    /// stay exhaustive, so adding a venue forces the match in
    /// [`hours_for_exchange`](super::hours_for_exchange) to be updated and
    /// keeps the calendar surface complete.
    ///
    /// The enum is `#[non_exhaustive]`, mirroring
    /// [`MarketHoursKey`](super::MarketHoursKey): venue coverage grows over
    /// time, and adding a variant must not be a breaking change for
    /// dependents. Match it with a wildcard arm; [`Exchange::ALL`] enumerates
    /// the variants of the version you compiled against.
    ///
    /// Holidays and product-level calendar variations are deliberately not
    /// modeled here: this enum drives only normal-week, exchange-level
    /// session defaults. [`Exchange::Unknown`] maps to a 24×7 UTC fallback.
    /// Variants have one canonical `snake_case` name (e.g.
    /// `Exchange::NasdaqBx` ↔ `"nasdaq_bx"`) used identically by serde,
    /// [`Exchange::as_str`], [`std::fmt::Display`], and
    /// [`std::str::FromStr`]; that wire form is asserted variant-by-variant
    /// in the test suite and must stay stable.
    #[non_exhaustive]
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
    #[serde(rename_all = "snake_case")]
    pub enum Exchange {
        /// Unrecognized or unset venue; [`hours_for_exchange`](super::hours_for_exchange)
        /// returns a 24×7 UTC fallback. Reaching this variant is always a
        /// deliberate act: neither `FromStr` nor serde will produce it from an
        /// unrecognized name, and it is not a `Default`.
        Unknown => "unknown",

        // US Equities (ET)
        /// The Nasdaq Stock Market — the primary Nasdaq listing venue; early
        /// session from 04:00 ET.
        Nasdaq => "nasdaq",
        /// Nasdaq BX, the former Boston Stock Exchange book; early session
        /// from 04:00 ET.
        NasdaqBx => "nasdaq_bx",
        /// Nasdaq PSX, the former Philadelphia Stock Exchange equities book;
        /// early session from 04:00 ET.
        NasdaqPsx => "nasdaq_psx",
        /// Cboe BZX Equities — early session from 04:00 ET (07:00 before
        /// 2025-05-01).
        CboeBzx => "cboe_bzx",
        /// Cboe BYX Equities — early session from 07:00 ET.
        CboeByx => "cboe_byx",
        /// Cboe EDGA Equities — early session from 07:00 ET.
        CboeEdga => "cboe_edga",
        /// Cboe EDGX Equities — early session from 04:00 ET (07:00 before
        /// 2021-03-08).
        CboeEdgx => "cboe_edgx",
        /// New York Stock Exchange — the core session only; NYSE Group
        /// extended trading happens on Arca, American, National, and Texas.
        Nyse => "nyse",
        /// NYSE Arca — early session from 04:00 ET, unlike the NYSE core book.
        NyseArca => "nyse_arca",
        /// NYSE American, formerly the American Stock Exchange — early
        /// session from 07:00 ET.
        NyseAmerican => "nyse_american",
        /// NYSE National — early session from 07:00 ET.
        NyseNational => "nyse_national",
        /// NYSE Texas, formerly NYSE Chicago — no sessions before its
        /// 2025-03-31 go-live.
        NyseTexas => "nyse_texas",
        /// MEMX, the Members Exchange — early session from 04:00 ET, with no
        /// recorded cutover (see `hours_for_exchange_as_of`).
        MemxEq => "memx_eq",
        /// MIAX Pearl Equities — early session from 04:00 ET, with no
        /// recorded cutover (see `hours_for_exchange_as_of`).
        MiaxPearlEq => "miax_pearl_eq",
        /// IEX, the Investors Exchange — System Hours 08:00–17:00 ET,
        /// narrower than the Reg NMS extended default at both ends.
        Iex => "iex",
        /// `IntelligentCross`, an ATS whose IQX book executes during regular
        /// hours.
        IntelligentcrossIqx => "intelligentcross_iqx",
        /// Blue Ocean ATS, an overnight-only US equities ATS.
        BlueOceanAts => "blue_ocean_ats",
        /// FINRA/Nasdaq Trade Reporting Facility, Carteret — an off-exchange
        /// reporting facility rather than a matching venue.
        FinraTrfCarteret => "finra_trf_carteret",
        /// FINRA/Nasdaq Trade Reporting Facility, Chicago.
        FinraTrfChicago => "finra_trf_chicago",
        /// FINRA/NYSE Trade Reporting Facility.
        FinraTrfNyse => "finra_trf_nyse",

        // US Options (ET)
        /// Cboe Options Exchange (C1) — the only US options venue here with a
        /// Global Trading Hours wrap and a post-close curb session.
        CboeOptionsC1 => "cboe_options_c1",
        /// Cboe C2 Options Exchange.
        CboeC2Options => "cboe_c2_options",
        /// Cboe BZX Options Exchange.
        CboeBzxOptions => "cboe_bzx_options",
        /// Cboe EDGX Options Exchange.
        CboeEdgxOptions => "cboe_edgx_options",
        /// NYSE Arca Options.
        NyseArcaOptions => "nyse_arca_options",
        /// NYSE American Options.
        NyseAmericanOptions => "nyse_american_options",
        /// Nasdaq PHLX, the former Philadelphia options exchange.
        NasdaqPhlx => "nasdaq_phlx",
        /// Nasdaq ISE, the International Securities Exchange.
        NasdaqIse => "nasdaq_ise",
        /// The Nasdaq Options Market (NOM).
        NasdaqNom => "nasdaq_nom",
        /// Nasdaq MRX, formerly ISE Mercury.
        NasdaqMrx => "nasdaq_mrx",
        /// Nasdaq GEMX, formerly ISE Gemini.
        NasdaqGemx => "nasdaq_gemx",
        /// Nasdaq BX Options.
        NasdaqBxOptions => "nasdaq_bx_options",
        /// MIAX Options, the original Miami International Securities
        /// Exchange.
        MiaxOptions => "miax_options",
        /// MIAX Emerald Options.
        MiaxEmeraldOptions => "miax_emerald_options",
        /// MIAX Pearl Options.
        MiaxPearlOptions => "miax_pearl_options",
        /// MIAX Sapphire Options.
        MiaxSapphireOptions => "miax_sapphire_options",
        /// BOX Options Exchange.
        BoxOptions => "box_options",
        /// MEMX Options.
        MemxOptions => "memx_options",

        // US Futures
        /// CME, the Chicago Mercantile Exchange; the venue default is the
        /// Globex equity-index profile.
        Cme => "cme",
        /// CBOT, the Chicago Board of Trade; the venue default is the Globex
        /// grains profile, which keeps its own day session.
        Cbot => "cbot",
        /// COMEX metals, sharing the Globex energy/metals profile.
        Comex => "comex",
        /// NYMEX energy, sharing the Globex energy/metals profile.
        Nymex => "nymex",
        /// CFE, the Cboe Futures Exchange; the venue default is the VIX
        /// profile.
        Cfe => "cfe",

        // European Futures / Energy
        /// Eurex, the European derivatives exchange.
        Eurex => "eurex",
        /// EEX, the European Energy Exchange.
        Eex => "eex",
        /// ICE Futures U.S.
        Iceus => "iceus",
        /// ICE Futures Europe.
        Iceeu => "iceeu",
        /// ICE Futures Europe, commodities products.
        IceEuropeCommodities => "ice_europe_commodities",
        /// ICE Futures Europe, financial products.
        IceEuropeFinancials => "ice_europe_financials",
        /// ICE Endex, the Amsterdam gas and power market.
        IceEndex => "ice_endex",
        /// ICE Futures Abu Dhabi.
        IceAbuDhabi => "ice_abu_dhabi",
        /// ICE Futures Canada.
        IceCanada => "ice_canada",

        // Asia-Pacific Futures
        /// SGX, the Singapore Exchange — derivatives market.
        Sgx => "sgx",

        // EU Equities
        /// London Stock Exchange (SETS).
        Lse => "lse",
        /// Xetra, Deutsche Börse's electronic order book.
        Xetra => "xetra",
        /// SIX Swiss Exchange.
        Six => "six",
        /// Euronext Paris.
        EuronextParis => "euronext_paris",
        /// Euronext Amsterdam.
        EuronextAmsterdam => "euronext_amsterdam",
        /// Euronext Brussels.
        EuronextBrussels => "euronext_brussels",
        /// Euronext Lisbon.
        EuronextLisbon => "euronext_lisbon",
        /// Euronext Dublin.
        EuronextDublin => "euronext_dublin",
        /// Euronext Milan, formerly Borsa Italiana.
        EuronextMilan => "euronext_milan",
        /// BME, the Spanish exchange operator (Bolsa de Madrid).
        Bme => "bme",
        /// Nasdaq Stockholm.
        NasdaqStockholm => "nasdaq_stockholm",
        /// Nasdaq Helsinki — the one Nordic book quoted in EET rather than
        /// CET.
        NasdaqHelsinki => "nasdaq_helsinki",
        /// Nasdaq Copenhagen.
        NasdaqCopenhagen => "nasdaq_copenhagen",
        /// Wiener Börse, the Vienna Stock Exchange.
        Vienna => "vienna",

        // Crypto / always-open venues
        //
        // These venues trade continuously without daily maintenance breaks.
        // They are modeled as 24×7 UTC sessions and must remain explicitly
        // separated from futures-session venues that have daily and weekend
        // boundaries. See `default_24x7` for the profile and the
        // `always_open_*` tests for the behavioral contract.
        /// Binance futures — a 24×7 venue with no daily or weekend close.
        BinanceFutures => "binance_futures",
    }
}