ifsc 0.1.1

A fast offline directory for Indian bank branches and IFSCs
Documentation
use crate::{Bank, Branch, Error, ErrorKind, Result, SubletTarget};

use super::{
    BankMatches, BankOrder, BankQuery, BranchMatches, BranchOrder, BranchQuery, BranchTextField,
    LocationField, SearchCase, SearchOptions, Text, TextMatch,
};

impl crate::Directory {
    /// Returns one deterministic page of branches matching `query`.
    ///
    /// # Errors
    ///
    /// Returns an error when the page limit is outside `1..=10_000`, an IFSC
    /// prefix is malformed, a text value is empty or contains only ASCII
    /// whitespace, or a text value exceeds the configured byte limit.
    pub fn search_branches(
        self,
        query: &BranchQuery<'_>,
        options: SearchOptions,
    ) -> Result<BranchMatches> {
        validate_branch_query(query, options)?;
        let order = query.order.unwrap_or(BranchOrder::Ifsc);
        let (page, total, end) = if order == BranchOrder::Ifsc {
            page_in_order(
                self.branches()
                    .filter(|branch| branch_matches(*branch, query)),
                options,
            )
        } else {
            let mut matches: Vec<_> = self
                .branches()
                .filter(|branch| branch_matches(*branch, query))
                .collect();
            sort_branches(&mut matches, order);
            page_sorted(matches, options)
        };
        Ok(BranchMatches {
            iter: page.into_iter(),
            total,
            offset: options.page.offset,
            end,
        })
    }

    /// Counts branches matching `query` without constructing a result page.
    ///
    /// Text values use the default 256-byte query limit.
    ///
    /// # Errors
    ///
    /// Returns an error when an IFSC prefix is malformed, a text value is empty
    /// or contains only ASCII whitespace, or a text value exceeds 256 bytes.
    pub fn count_branches(self, query: &BranchQuery<'_>) -> Result<usize> {
        validate_branch_query(query, SearchOptions::new())?;
        Ok(self
            .branches()
            .filter(|branch| branch_matches(*branch, query))
            .count())
    }

    /// Returns one deterministic page of banks matching `query`.
    ///
    /// # Errors
    ///
    /// Returns an error when the page limit is outside `1..=10_000`, a name is
    /// empty or contains only ASCII whitespace, or a name exceeds the
    /// configured byte limit.
    pub fn search_banks(
        self,
        query: &BankQuery<'_>,
        options: SearchOptions,
    ) -> Result<BankMatches> {
        validate_bank_query(query, options)?;
        let order = query.order.unwrap_or(BankOrder::Code);
        let (page, total, end) = if order == BankOrder::Code {
            page_in_order(
                self.banks().filter(|bank| bank_matches(*bank, query)),
                options,
            )
        } else {
            let mut matches: Vec<_> = self
                .banks()
                .filter(|bank| bank_matches(*bank, query))
                .collect();
            sort_banks(&mut matches, order);
            page_sorted(matches, options)
        };
        Ok(BankMatches {
            iter: page.into_iter(),
            total,
            offset: options.page.offset,
            end,
        })
    }

    /// Counts banks matching `query` without constructing a result page.
    ///
    /// Name values use the default 256-byte query limit.
    ///
    /// # Errors
    ///
    /// Returns an error when a name is empty, contains only ASCII whitespace,
    /// or exceeds 256 bytes.
    pub fn count_banks(self, query: &BankQuery<'_>) -> Result<usize> {
        validate_bank_query(query, SearchOptions::new())?;
        Ok(self
            .banks()
            .filter(|bank| bank_matches(*bank, query))
            .count())
    }
}

fn validate_options(options: SearchOptions) -> Result<()> {
    if options.page.limit == 0 || options.page.limit > 10_000 {
        return Err(Error::new(ErrorKind::InvalidPage));
    }
    Ok(())
}

fn validate_branch_query(query: &BranchQuery<'_>, options: SearchOptions) -> Result<()> {
    validate_options(options)?;
    if query
        .ifsc_prefix
        .is_some_and(|value| !valid_ifsc_prefix(value))
    {
        return Err(Error::new(ErrorKind::InvalidQuery));
    }
    for value in [
        query.location.map(|(_, value)| value),
        query.micr,
        query.swift,
        query.text.map(|text| text.0.value),
    ]
    .into_iter()
    .flatten()
    {
        validate_text(value, options.max_text_bytes)?;
    }
    Ok(())
}

fn valid_ifsc_prefix(value: &str) -> bool {
    if value.is_empty() || value.len() > 11 || !value.is_ascii() {
        return false;
    }
    value.bytes().enumerate().all(|(index, byte)| match index {
        0..=3 => byte.is_ascii_alphabetic(),
        4 => byte == b'0',
        _ => byte.is_ascii_alphanumeric(),
    })
}

fn validate_bank_query(query: &BankQuery<'_>, options: SearchOptions) -> Result<()> {
    validate_options(options)?;
    if let Some(name) = query.name {
        validate_text(name.value, options.max_text_bytes)?;
    }
    Ok(())
}

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

fn branch_matches(branch: Branch, query: &BranchQuery<'_>) -> bool {
    query.ifsc_prefix.is_none_or(|value| {
        branch
            .ifsc()
            .as_str()
            .get(..value.len())
            .is_some_and(|prefix| prefix.eq_ignore_ascii_case(value))
    }) && query
        .routing
        .is_none_or(|value| branch.routing_code() == value)
        && query
            .location
            .is_none_or(|(field, value)| location(branch, field) == Some(value))
        && query
            .iso
            .is_none_or(|value| branch.iso_subdivision() == Some(value))
        && query.micr.is_none_or(|value| branch.micr() == Some(value))
        && query.swift.is_none_or(|value| {
            branch
                .swift()
                .is_some_and(|swift| swift.eq_ignore_ascii_case(value))
        })
        && query
            .rail
            .is_none_or(|(rail, reported)| branch.reports(rail) == reported)
        && query
            .exact
            .is_none_or(|expected| branch.exact_sublet().is_some() == expected)
        && query
            .custom
            .is_none_or(|expected| branch.custom_sublets().next().is_some() == expected)
        && query.sublet_bank.is_none_or(|bank| {
            branch
                .exact_sublet()
                .is_some_and(|mapping| mapping.target() == SubletTarget::Bank(bank))
                || branch
                    .custom_sublets()
                    .any(|mapping| mapping.target() == SubletTarget::Bank(bank))
        })
        && query
            .text
            .is_none_or(|text| branch_text_matches(branch, text.0))
}

fn bank_matches(bank: Bank, query: &BankQuery<'_>) -> bool {
    query
        .profile
        .is_none_or(|expected| bank.profile().is_some() == expected)
        && query
            .kind
            .is_none_or(|kind| bank.profile().is_some_and(|profile| profile.kind() == kind))
        && query.service.is_none_or(|(service, status)| {
            bank.profile()
                .is_some_and(|profile| profile.reported_status(service) == status)
        })
        && query
            .name
            .is_none_or(|query| text_matches(bank.name(), query.value, query.kind, query.case))
}

fn location(branch: Branch, field: LocationField) -> Option<&'static str> {
    match field {
        LocationField::Centre => Some(branch.centre()),
        LocationField::District => Some(branch.district()),
        LocationField::City => Some(branch.city()),
        LocationField::State => branch.state(),
    }
}

fn branch_text_matches(branch: Branch, query: Text<'_, BranchTextField>) -> bool {
    let fields = [
        branch.reported_bank_name(),
        Some(branch.name()),
        Some(branch.address()),
        branch.contact(),
        Some(branch.centre()),
        Some(branch.district()),
        Some(branch.city()),
        branch.state(),
        branch.micr(),
        branch.swift(),
    ];
    match query.field {
        BranchTextField::Any => fields
            .into_iter()
            .flatten()
            .any(|value| text_matches(value, query.value, query.kind, query.case)),
        field => fields[branch_text_index(field)]
            .is_some_and(|value| text_matches(value, query.value, query.kind, query.case)),
    }
}

const fn branch_text_index(field: BranchTextField) -> usize {
    match field {
        BranchTextField::ReportedBankName => 0,
        BranchTextField::BranchName => 1,
        BranchTextField::Address => 2,
        BranchTextField::Contact => 3,
        BranchTextField::Centre => 4,
        BranchTextField::District => 5,
        BranchTextField::City => 6,
        BranchTextField::State => 7,
        BranchTextField::Micr => 8,
        BranchTextField::Swift => 9,
        BranchTextField::Any => unreachable!(),
    }
}

fn text_matches(haystack: &str, needle: &str, kind: TextMatch, case: SearchCase) -> bool {
    if case == SearchCase::AsciiInsensitive {
        match kind {
            TextMatch::Exact => haystack.eq_ignore_ascii_case(needle),
            TextMatch::Prefix => haystack
                .get(..needle.len())
                .is_some_and(|value| value.eq_ignore_ascii_case(needle)),
            TextMatch::Contains => haystack
                .as_bytes()
                .windows(needle.len())
                .any(|value| value.eq_ignore_ascii_case(needle.as_bytes())),
        }
    } else {
        match kind {
            TextMatch::Exact => haystack == needle,
            TextMatch::Prefix => haystack.starts_with(needle),
            TextMatch::Contains => haystack.contains(needle),
        }
    }
}

fn sort_branches(branches: &mut [Branch], order: BranchOrder) {
    branches.sort_by(|left, right| match order {
        BranchOrder::Ifsc => left.ifsc().cmp(&right.ifsc()),
        BranchOrder::ReportedBankName => left
            .reported_bank_name()
            .cmp(&right.reported_bank_name())
            .then(left.ifsc().cmp(&right.ifsc())),
        BranchOrder::BranchName => left
            .name()
            .cmp(right.name())
            .then(left.ifsc().cmp(&right.ifsc())),
        BranchOrder::StateCityBranch => left
            .state()
            .cmp(&right.state())
            .then(left.city().cmp(right.city()))
            .then(left.name().cmp(right.name()))
            .then(left.ifsc().cmp(&right.ifsc())),
    })
}

fn sort_banks(banks: &mut [Bank], order: BankOrder) {
    match order {
        BankOrder::Code => banks.sort_by_key(|bank| bank.code()),
        BankOrder::Name => banks.sort_by(|left, right| {
            left.name()
                .cmp(right.name())
                .then(left.code().cmp(&right.code()))
        }),
    }
}

fn page_in_order<T>(
    matches: impl Iterator<Item = T>,
    options: SearchOptions,
) -> (Vec<T>, usize, usize) {
    let mut page = Vec::with_capacity(options.page.limit);
    let mut total = 0;
    for value in matches {
        if total >= options.page.offset && page.len() < options.page.limit {
            page.push(value);
        }
        total += 1;
    }
    let end = options.page.offset.min(total) + page.len();
    (page, total, end)
}

fn page_sorted<T>(matches: Vec<T>, options: SearchOptions) -> (Vec<T>, usize, usize) {
    let total = matches.len();
    let start = options.page.offset.min(total);
    let page: Vec<_> = matches
        .into_iter()
        .skip(start)
        .take(options.page.limit)
        .collect();
    let end = start + page.len();
    (page, total, end)
}