carbonfr-core 0.9.6

Domain, use cases and ports for carbon-fr's carbon-intensity core — pure, IO-free Rust (hexagonal architecture).
Documentation
//! Régions couvertes : le national agrégé + les 12 régions métropolitaines
//! d'éCO2mix régional (ADR-0003). Pas de DOM-TOM au lancement.

use std::fmt;

/// Périmètre géographique d'une mesure.
///
/// `National` correspond au jeu éCO2mix national ; les 12 variantes régionales
/// correspondent au découpage administratif métropolitain publié par RTE.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Region {
    National,
    AuvergneRhoneAlpes,
    BourgogneFrancheComte,
    Bretagne,
    CentreValDeLoire,
    GrandEst,
    HautsDeFrance,
    IleDeFrance,
    Normandie,
    NouvelleAquitaine,
    Occitanie,
    PaysDeLaLoire,
    ProvenceAlpesCoteDazur,
}

impl Region {
    /// Les 12 régions métropolitaines (hors `National`).
    pub const METROPOLITAN: [Region; 12] = [
        Region::AuvergneRhoneAlpes,
        Region::BourgogneFrancheComte,
        Region::Bretagne,
        Region::CentreValDeLoire,
        Region::GrandEst,
        Region::HautsDeFrance,
        Region::IleDeFrance,
        Region::Normandie,
        Region::NouvelleAquitaine,
        Region::Occitanie,
        Region::PaysDeLaLoire,
        Region::ProvenceAlpesCoteDazur,
    ];

    /// Identifiant stable, utilisable en clé d'API ou de stockage.
    pub fn slug(self) -> &'static str {
        match self {
            Region::National => "national",
            Region::AuvergneRhoneAlpes => "auvergne-rhone-alpes",
            Region::BourgogneFrancheComte => "bourgogne-franche-comte",
            Region::Bretagne => "bretagne",
            Region::CentreValDeLoire => "centre-val-de-loire",
            Region::GrandEst => "grand-est",
            Region::HautsDeFrance => "hauts-de-france",
            Region::IleDeFrance => "ile-de-france",
            Region::Normandie => "normandie",
            Region::NouvelleAquitaine => "nouvelle-aquitaine",
            Region::Occitanie => "occitanie",
            Region::PaysDeLaLoire => "pays-de-la-loire",
            Region::ProvenceAlpesCoteDazur => "provence-alpes-cote-d-azur",
        }
    }

    /// Code INSEE de la région métropolitaine, ou `None` pour `National`.
    /// Sert de clé robuste vers l'éCO2mix régional (`code_insee_region`).
    pub fn insee_code(self) -> Option<&'static str> {
        let code = match self {
            Region::National => return None,
            Region::AuvergneRhoneAlpes => "84",
            Region::BourgogneFrancheComte => "27",
            Region::Bretagne => "53",
            Region::CentreValDeLoire => "24",
            Region::GrandEst => "44",
            Region::HautsDeFrance => "32",
            Region::IleDeFrance => "11",
            Region::Normandie => "28",
            Region::NouvelleAquitaine => "75",
            Region::Occitanie => "76",
            Region::PaysDeLaLoire => "52",
            Region::ProvenceAlpesCoteDazur => "93",
        };
        Some(code)
    }

    /// Région correspondant à un [`slug`](Region::slug), ou `None` si inconnu.
    ///
    /// Réciproque de `slug()` : utilisée par les adapters pour reconstruire une
    /// région à partir de sa forme stockée ou reçue (clé d'URL, colonne SQL).
    pub fn from_slug(slug: &str) -> Option<Region> {
        std::iter::once(Region::National)
            .chain(Region::METROPOLITAN)
            .find(|region| region.slug() == slug)
    }

    /// Région métropolitaine correspondant à un [`insee_code`](Region::insee_code),
    /// ou `None` si absent/inconnu (Corse, DOM-TOM, code mal formé — hors
    /// périmètre éCO2mix régional, ADR-0003).
    ///
    /// Réciproque de `insee_code()` : utilisée par l'adapter ODRÉ pour
    /// reconstruire la région d'un enregistrement d'export de masse régional
    /// (`code_insee_region`), qui couvre toutes les régions en un seul
    /// téléchargement (addendum ADR-0003 2026-09-26). `National` n'a pas de
    /// code INSEE régional : n'est jamais renvoyé ici.
    pub fn from_insee_code(code: &str) -> Option<Region> {
        Region::METROPOLITAN
            .into_iter()
            .find(|region| region.insee_code() == Some(code))
    }

    /// Libellé humain.
    pub fn label(self) -> &'static str {
        match self {
            Region::National => "National",
            Region::AuvergneRhoneAlpes => "Auvergne-Rhône-Alpes",
            Region::BourgogneFrancheComte => "Bourgogne-Franche-Comté",
            Region::Bretagne => "Bretagne",
            Region::CentreValDeLoire => "Centre-Val de Loire",
            Region::GrandEst => "Grand Est",
            Region::HautsDeFrance => "Hauts-de-France",
            Region::IleDeFrance => "Île-de-France",
            Region::Normandie => "Normandie",
            Region::NouvelleAquitaine => "Nouvelle-Aquitaine",
            Region::Occitanie => "Occitanie",
            Region::PaysDeLaLoire => "Pays de la Loire",
            Region::ProvenceAlpesCoteDazur => "Provence-Alpes-Côte d'Azur",
        }
    }
}

impl fmt::Display for Region {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.label())
    }
}

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

    #[test]
    fn metropolitan_count_is_twelve() {
        assert_eq!(Region::METROPOLITAN.len(), 12);
    }

    #[test]
    fn slugs_are_unique() {
        let mut slugs: Vec<&str> = std::iter::once(Region::National)
            .chain(Region::METROPOLITAN)
            .map(Region::slug)
            .collect();
        slugs.sort_unstable();
        let before = slugs.len();
        slugs.dedup();
        assert_eq!(before, slugs.len());
    }

    #[test]
    fn from_slug_roundtrips_every_region() {
        for region in std::iter::once(Region::National).chain(Region::METROPOLITAN) {
            assert_eq!(Region::from_slug(region.slug()), Some(region));
        }
        assert_eq!(Region::from_slug("atlantide"), None);
    }

    #[test]
    fn from_insee_code_roundtrips_every_metropolitan_region() {
        for region in Region::METROPOLITAN {
            let code = region
                .insee_code()
                .expect("région métropolitaine : code INSEE présent");
            assert_eq!(Region::from_insee_code(code), Some(region));
        }
        // Code inconnu (ex. Corse, hors périmètre) → None, jamais une erreur.
        assert_eq!(Region::from_insee_code("94"), None);
        assert_eq!(Region::from_insee_code(""), None);
    }
}