Rust ISO3166国家代码库rust_iso3166使用指南

rust_iso3166是一个用于处理ISO 3166国际标准国家/地区编码的Rust库，它提供了高效的国家代码转换和查询功能。

主要特性

• 支持ISO 3166-1 alpha-2(两字母代码)
• 支持ISO 3166-1 alpha-3(三字母代码)
• 支持ISO 3166-1 numeric(数字代码)
• 国家/地区名称查询
• 轻量级且无依赖

安装

在Cargo.toml中添加依赖：

[dependencies]
rust_iso3166 = "1.0"

基本使用方法

1. 通过国家代码查询国家信息

use rust_iso3166::Country;

fn main() {
    // 通过两字母代码查询
    let country = Country::from_alpha2("CN").unwrap();
    println!("中国: {:?}", country);
    
    // 通过三字母代码查询
    let country = Country::from_alpha3("USA").unwrap();
    println!("美国: {:?}", country);
    
    // 通过数字代码查询
    let country = Country::from_numeric(840).unwrap();
    println!("美国(数字代码): {:?}", country);
}

2. 获取所有国家列表

use rust_iso3166::COUNTRIES;

fn main() {
    for country in COUNTRIES.iter() {
        println!("{}: {} ({})", 
            country.name, 
            country.alpha2, 
            country.alpha3);
    }
}

3. 国家代码转换

use rust_iso3166::Country;

fn main() {
    let country = Country::from_alpha2("JP").unwrap();
    
    println!("三字母代码: {}", country.alpha3); // 输出: JPN
    println!("数字代码: {}", country.numeric);  // 输出: 392
}

4. 验证国家代码

use rust_iso3166::Country;

fn main() {
    assert!(Country::is_valid_alpha2("FR"));
    assert!(!Country::is_valid_alpha2("XX"));
    
    assert!(Country::is_valid_alpha3("DEU"));
    assert!(!Country::is_valid_alpha3("XYZ"));
}

高级用法

自定义国家信息结构

use rust_iso3166::Country;

#[derive(Debug)]
struct ExtendedCountryInfo {
    country: Country,
    population: u64,
    capital: String,
}

fn main() {
    let china = ExtendedCountryInfo {
        country: Country::from_alpha2("CN").unwrap(),
        population: 1_411_000_000,
        capital: "Beijing".to_string(),
    };
    
    println!("{:?}", china);
}

与serde集成(序列化/反序列化)

use rust_iso3166::Country;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct User {
    name: String,
    country: Country,
}

fn main() {
    let user = User {
        name: "Alice".to_string(),
        country: Country::from_alpha2("GB").unwrap(),
    };
    
    let json = serde_json::to_string(&user).unwrap();
    println!("{}", json); // 输出: {"name":"Alice","country":"GB"}
    
    let user: User = serde_json::from_str(&json).unwrap();
    println!("{}来自{}", user.name, user.country.name);
}

性能提示

rust_iso3166内部使用静态数组存储国家信息，所有查询操作都是O(1)时间复杂度，适合高性能场景使用。

错误处理

所有查询方法都返回Option<Country>，当查询失败时返回None：

use rust_iso3166::Country;

fn main() {
    match Country::from_alpha2("XX") {
        Some(country) => println!("找到国家: {}", country.name),
        None => println!("无效的国家代码"),
    }
}

完整示例代码

// 完整示例展示rust_iso3166库的主要功能
use rust_iso3166::Country;
use serde::{Serialize, Deserialize};

fn main() {
    // 示例1: 基本查询功能
    println!("=== 基本查询功能 ===");
    let china = Country::from_alpha2("CN").unwrap();
    println!("中国: {} (Alpha2: {}, Alpha3: {}, 数字代码: {})", 
        china.name, china.alpha2, china.alpha3, china.numeric);

    // 示例2: 获取所有国家列表
    println!("\n=== 获取所有国家列表 ===");
    let total_countries = rust_iso3166::COUNTRIES.len();
    println!("总国家数量: {}", total_countries);

    // 示例3: 国家代码转换
    println!("\n=== 国家代码转换 ===");
    let japan = Country::from_alpha3("JPN").unwrap();
    println!("日本: Alpha2代码: {}", japan.alpha2);

    // 示例4: 验证国家代码
    println!("\n=== 验证国家代码 ===");
    println!("FR是有效的Alpha2代码吗? {}", Country::is_valid_alpha2("FR"));
    println!("XX是有效的Alpha2代码吗? {}", Country::is_valid_alpha2("XX"));

    // 示例5: 自定义国家信息结构
    println!("\n=== 自定义国家信息结构 ===");
    #[derive(Debug)]
    struct CountryDetails {
        country: Country,
        gdp: f64,  // 单位: 十亿美元
    }
    
    let usa_details = CountryDetails {
        country: Country::from_alpha2("US").unwrap(),
        gdp: 22996.1,
    };
    println!("美国经济详情: {:?}", usa_details);

    // 示例6: 与serde集成
    println!("\n=== 与serde集成 ===");
    #[derive(Serialize, Deserialize)]
    struct Business {
        name: String,
        headquarters: Country,
    }
    
    let company = Business {
        name: "TechCorp".to_string(),
        headquarters: Country::from_alpha2("DE").unwrap(),
    };
    
    let json = serde_json::to_string(&company).unwrap();
    println!("序列化结果: {}", json);
    
    // 示例7: 错误处理
    println!("\n=== 错误处理 ===");
    match Country::from_alpha2("ZZ") {
        Some(country) => println!("找到国家: {}", country.name),
        None => println!("无效的国家代码ZZ"),
    }
}

这个库是处理国际化应用时国家/地区代码的理想选择，特别是在需要验证或转换不同格式国家代码的场景下。