CPCA - Chinese Province City Area Parser

中国省市区地址解析库，用于从自由文本地址中提取省、市、区信息。

功能特性

• 🚀 高性能 - 基于前缀树实现，O(n) 时间复杂度
• 📦 零依赖 - 纯 Rust 实现，无需外部分词库
• 🎯 智能匹配 - 支持省份简称、城市简称、区县简称
• 🏛️ 完整数据 - 内置 2025 年最新行政区划（3600+ 条记录）
• 🔧 易于使用 - 简洁的 API，开箱即用

安装

[dependencies]
cpca = "0.1"

快速开始

use cpca::AddressParser;

fn main() {
    let parser = AddressParser::new();

    // 解析完整地址
    let result = parser.parse("广东省深圳市南山区科技园路1号");
    println!("省份: {:?}", result.province);  // Some("广东省")
    println!("城市: {:?}", result.city);      // Some("深圳市")
    println!("区县: {:?}", result.district);  // Some("南山区")
    println!("详址: {}", result.detail);      // "科技园路1号"

    // 支持简称
    let result = parser.parse("深圳南山科技园");
    assert_eq!(result.province, Some("广东省".to_string()));
    assert_eq!(result.city, Some("深圳市".to_string()));
    assert_eq!(result.district, Some("南山区".to_string()));
}

便捷函数

// 使用全局解析器（无需手动创建实例）
let result = cpca::parse("北京市朝阳区望京");

// 标准化地址（简称转全称）
let full = cpca::normalize("广东", "深圳", Some("南山"));
assert_eq!(full, "广东省深圳市南山区");

支持的场景

完整地址

parser.parse("广东省深圳市南山区科技园");
// 省份: 广东省, 城市: 深圳市, 区县: 南山区

省份简称

parser.parse("广东深圳市南山区");
// 自动识别 "广东" -> "广东省"

缺省省份

parser.parse("深圳市南山区科技园");
// 自动推断省份为 "广东省"

直辖市

parser.parse("北京市朝阳区");
// 省份: 北京市, 城市: 北京市, 区县: 朝阳区

自治区

parser.parse("广西南宁市");
// 自动识别 "广西" -> "广西壮族自治区"

自治州

parser.parse("云南省大理白族自治州大理市");
// 正确识别自治州级城市

API 文档

AddressParser

impl AddressParser {
    /// 创建新的解析器实例
    fn new() -> Self;

    /// 获取全局单例
    fn global() -> &'static AddressParser;

    /// 解析地址
    fn parse(&self, address: &str) -> ParsedAddress;

    /// 标准化地址
    fn normalize(&self, province: &str, city: &str, district: Option<&str>) -> String;

    /// 批量解析
    fn parse_batch(&self, addresses: &[&str]) -> Vec<ParsedAddress>;

    /// 验证地址有效性
    fn is_valid_address(&self, address: &str) -> bool;

    /// 获取所有省份
    fn provinces(&self) -> Vec<&String>;

    /// 获取某省的所有城市
    fn cities_of_province(&self, province: &str) -> Vec<&String>;

    /// 获取某市的所有区县
    fn districts_of_city(&self, city: &str) -> Vec<&String>;
}

ParsedAddress

pub struct ParsedAddress {
    pub province: Option<String>,  // 省份
    pub city: Option<String>,      // 城市
    pub district: Option<String>,  // 区县
    pub detail: String,            // 详细地址
}

impl ParsedAddress {
    fn is_complete(&self) -> bool;   // 是否完整（省市区都有）
    fn full_address(&self) -> String; // 拼接完整地址
}

特性 (Features)

• serde - 启用 serde 序列化支持

[dependencies]
cpca = { version = "0.1", features = ["serde"] }

数据来源

行政区划数据来自 AreaCity-JsSpider-StatsGov，包含：

• 34 个省级行政区（含港澳台）
• 300+ 个地级市/自治州
• 2800+ 个区县

数据更新至 2025 年。

性能

在 M1 Mac 上的基准测试结果：

与 Python cpca 的对比

License

MIT License

贡献

欢迎提交 Issue 和 Pull Request！