ifsc 0.1.1

A fast offline directory for Indian bank branches and IFSCs
Documentation
mod bank;
mod branch;

use crate::{
    Bank, BankCode, BankProfile, Branch, BranchRail, Error, ErrorKind, Ifsc, Result, RoutingCode,
};

pub use bank::{BankProfiles, Banks};
pub use branch::Branches;

use self::{bank::BankFilter, branch::BranchFilter};

/// A zero-sized handle to the embedded Razorpay IFSC directory.
#[derive(Clone, Copy, Debug)]
pub struct Directory {
    _private: (),
}

/// Returns a handle to the embedded directory.
pub const fn directory() -> Directory {
    Directory { _private: () }
}

/// Looks up a parsed IFSC code in the embedded directory.
pub fn lookup(ifsc: Ifsc) -> Option<Branch> {
    directory().lookup(ifsc)
}

impl Default for Directory {
    fn default() -> Self {
        directory()
    }
}

/// Parses `input`, then looks it up in the embedded directory.
pub fn lookup_str(input: &str) -> Result<Option<Branch>> {
    Ok(lookup(crate::parse(input)?))
}

impl Directory {
    /// Looks up an IFSC code and returns its branch when listed.
    pub fn lookup(self, ifsc: Ifsc) -> Option<Branch> {
        crate::snapshot::find_branch(ifsc).map(Branch)
    }

    /// Reports whether an IFSC code is listed.
    pub fn contains(self, ifsc: Ifsc) -> bool {
        self.lookup(ifsc).is_some()
    }

    /// Iterates over every listed branch in ascending IFSC order.
    pub fn branches(self) -> Branches {
        Branches::all()
    }

    /// Iterates over every named bank in ascending bank-code order.
    pub fn banks(self) -> Banks {
        Banks::all()
    }

    /// Iterates over every bank that has a metadata profile.
    pub fn bank_profiles(self) -> BankProfiles {
        BankProfiles::all()
    }

    /// Looks up a bank name by its four-character code.
    pub fn bank(self, code: BankCode) -> Option<Bank> {
        crate::snapshot::find_bank_name(code).map(Bank)
    }

    /// Looks up source-reported metadata for a bank code.
    pub fn bank_profile(self, code: BankCode) -> Option<BankProfile> {
        crate::snapshot::find_bank_profile(code).map(BankProfile)
    }

    /// Iterates over branches with the given routing code.
    pub fn branches_for_routing_code(self, code: RoutingCode) -> Branches {
        Branches::range(crate::snapshot::routing_range(code))
    }

    /// Iterates over branches whose MICR value exactly matches trimmed `value`.
    ///
    /// # Errors
    ///
    /// Returns [`ErrorKind::TooLong`] for inputs longer than 64 bytes and
    /// [`ErrorKind::InvalidQuery`] for empty or ASCII-whitespace-only input.
    pub fn branches_by_micr(self, value: &str) -> Result<Branches> {
        validate_term(value)?;
        Ok(Branches::filtered(BranchFilter::Micr(
            value
                .trim_matches(|character: char| character.is_ascii_whitespace())
                .to_owned(),
        )))
    }

    /// Iterates over branches whose SWIFT value matches trimmed `value`.
    ///
    /// Matching ignores ASCII letter case.
    ///
    /// # Errors
    ///
    /// Returns [`ErrorKind::TooLong`] for inputs longer than 64 bytes and
    /// [`ErrorKind::InvalidQuery`] for empty or ASCII-whitespace-only input.
    pub fn branches_by_swift(self, value: &str) -> Result<Branches> {
        validate_term(value)?;
        Ok(Branches::filtered(BranchFilter::Swift(
            value
                .trim_matches(|character: char| character.is_ascii_whitespace())
                .to_ascii_uppercase(),
        )))
    }

    /// Iterates over branches for which Razorpay reports `rail`.
    pub fn branches_reporting(self, rail: BranchRail) -> Branches {
        Branches::filtered(BranchFilter::Rail(rail))
    }

    /// Iterates over banks with the reported service status.
    pub fn banks_reporting(
        self,
        service: crate::BankService,
        status: crate::ReportedStatus,
    ) -> Banks {
        Banks::filtered(BankFilter::Service(service, status))
    }

    /// Returns the exact sublet mapping for `ifsc`, if one exists.
    pub fn exact_sublet(self, ifsc: Ifsc) -> Option<crate::SubletMatch> {
        crate::snapshot::find_exact_sublet(ifsc)
    }

    /// Iterates over custom sublet rules that match `ifsc`.
    pub fn custom_sublets(self, ifsc: Ifsc) -> crate::CustomSubletMatches {
        crate::CustomSubletMatches { ifsc, cursor: 0 }
    }
}

fn validate_term(value: &str) -> Result<()> {
    if value.len() > 64 {
        Err(Error::new(ErrorKind::TooLong))
    } else if value
        .trim_matches(|character: char| character.is_ascii_whitespace())
        .is_empty()
    {
        Err(Error::new(ErrorKind::InvalidQuery))
    } else {
        Ok(())
    }
}