Rust国际化组件库icu_capi的使用指南

概述

icu_capi是Rust中用于国际化和本地化操作的C语言绑定库，它基于ICU(International Components for Unicode)库，提供了强大的Unicode文本处理、日期格式化和区域敏感操作功能。

主要功能

1. Unicode文本处理
2. 日期和时间格式化
3. 区域敏感操作(排序、数字格式化等)
4. 字符集转换
5. 复数规则处理

安装

在Cargo.toml中添加依赖：

[dependencies]
icu_capi = "0.7"

基本使用方法

1. Unicode文本处理

use icu_capi::normalizer::*;
use std::ffi::CString;

fn main() {
    // 创建规范化器
    let normalizer = unsafe { unorm2_getNFCInstance(std::ptr::null_mut()) };
    
    // 要规范化的字符串
    let input = CString::new("Café").unwrap();
    let mut output = [0u8; 32];
    
    // 执行规范化
    let status = unsafe {
        unorm2_normalize(
            normalizer,
            input.as_ptr() as *const u16,
            input.as_bytes().len() as i32,
            output.as_mut_ptr() as *mut u16,
            32,
            std::ptr::null_mut(),
        )
    };
    
    if status.is_ok() {
        println!("Normalization successful");
    }
}

2. 日期格式化

use icu_capi::udat::*;
use icu_capi::uloc::*;
use std::ffi::CString;

fn main() {
    // 设置区域
    let locale = CString::new("en-US").unwrap();
    let loc = unsafe { uloc_open(locale.as_ptr(), std::ptr::null(), std::ptr::null_mut()) };
    
    // 创建日期格式化器
    let pattern = CString::new("yyyy-MM-dd").unwrap();
    let df = unsafe {
        udat_open(
            UDAT_PATTERN,
            UDAT_PATTERN,
            loc,
            std::ptr::null(),
            -1,
            pattern.as_ptr() as *const u16,
            pattern.as_bytes().len() as i32,
            std::ptr::null_mut(),
        )
    };
    
    // 格式化当前时间
    let mut buffer = [0u16; 64];
    let now = unsafe { udat_getNow() };
    let len = unsafe {
        udat_format(
            df,
            now,
            buffer.as_mut_ptr(),
            64,
            std::ptr::null(),
            std::ptr::null_mut(),
        )
    };
    
    if len > 0 {
        let formatted = String::from_utf16_lossy(&buffer[..len as usize]);
        println!("Formatted date: {}", formatted);
    }
    
    // 清理资源
    unsafe {
        udat_close(df);
        uloc_close(loc);
    }
}

3. 区域敏感操作(数字格式化)

use icu_capi::unum::*;
use icu_capi::uloc::*;
use std::ffi::CString;

fn main() {
    // 设置区域
    let locale = CString::new("fr-FR").unwrap();
    let loc = unsafe { uloc_open(locale.as_ptr(), std::ptr::null(), std::ptr::null_mut()) };
    
    // 创建数字格式化器
    let nf = unsafe { unum_open(UNUM_DECIMAL, std::ptr::null(), -1, loc, std::ptr::null(), std::ptr::null_mut()) };
    
    // 格式化数字
    let number = 1234567.89;
    let mut buffer = [0u16; 64];
    let len = unsafe {
        unum_formatDouble(
            nf,
            number,
            buffer.as_mut_ptr(),
            64,
            std::ptr::null(),
            std::ptr::null_mut(),
        )
    };
    
    if len > 0 {
        let formatted = String::from_utf16_lossy(&buffer[..len as usize]);
        println!("Formatted number (French): {}", formatted); // 输出 "1 234 567,89"
    }
    
    // 清理资源
    unsafe {
        unum_close(nf);
        uloc_close(loc);
    }
}

完整示例demo

下面是一个综合使用icu_capi的完整示例，展示了文本规范化、日期格式化和数字格式化的组合使用：

use icu_capi::{normalizer::*, udat::*, unum::*, uloc::*};
use std::ffi::CString;

fn main() {
    // ==== 第一部分：Unicode文本规范化 ====
    println!("=== Unicode文本规范化 ===");
    
    // 创建NFC规范化器
    let normalizer = unsafe { unorm2_getNFCInstance(std::ptr::null_mut()) };
    let input = CString::new("Café").unwrap();
    let mut output = [0u8; 32];
    
    // 执行规范化
    let status = unsafe {
        unorm2_normalize(
            normalizer,
            input.as_ptr() as *const u16,
            input.as_bytes().len() as i32,
            output.as_mut_ptr() as *mut u16,
            32,
            std::ptr::null_mut(),
        )
    };
    
    if status.is_ok() {
        println!("文本规范化成功");
    }

    // ==== 第二部分：日期格式化 ====
    println!("\n=== 日期格式化 ===");
    
    // 设置英文(美国)区域
    let locale_en = CString::new("en-US").unwrap();
    let loc_en = unsafe { uloc_open(locale_en.as_ptr(), std::ptr::null(), std::ptr::null_mut()) };
    
    // 创建日期格式化器
    let pattern = CString::new("yyyy-MM-dd HH:mm:ss").unwrap();
    let df = unsafe {
        udat_open(
            UDAT_PATTERN,
            UDAT_PATTERN,
            loc_en,
            std::ptr::null(),
            -1,
            pattern.as_ptr() as *const u16,
            pattern.as_bytes().len() as i32,
            std::ptr::null_mut(),
        )
    };
    
    // 格式化当前时间
    let mut date_buffer = [0u16; 64];
    let now = unsafe { udat_getNow() };
    let len = unsafe {
        udat_format(
            df,
            now,
            date_buffer.as_mut_ptr(),
            64,
            std::ptr::null(),
            std::ptr::null_mut(),
        )
    };
    
    if len > 0 {
        let formatted = String::from_utf16_lossy(&date_buffer[..len as usize]);
        println!("英文日期格式: {}", formatted);
    }
    
    // ==== 第三部分：数字格式化 ====
    println!("\n=== 数字格式化 ===");
    
    // 设置法语(法国)区域
    let locale_fr = CString::new("fr-FR").unwrap();
    let loc_fr = unsafe { uloc_open(locale_fr.as_ptr(), std::ptr::null(), std::ptr::null_mut()) };
    
    // 创建数字格式化器
    let nf = unsafe { unum_open(UNUM_DECIMAL, std::ptr::null(), -1, loc_fr, std::ptr::null(), std::ptr::null_mut()) };
    
    // 格式化数字
    let number = 1234567.89;
    let mut num_buffer = [0u16; 64];
    let len = unsafe {
        unum_formatDouble(
            nf,
            number,
            num_buffer.as_mut_ptr(),
            64,
            std::ptr::null(),
            std::ptr::null_mut(),
        )
    };
    
    if len > 0 {
        let formatted = String::from_utf16_lossy(&num_buffer[..len as usize]);
        println!("法文数字格式: {}", formatted); // 输出 "1 234 567,89"
    }
    
    // ==== 清理资源 ====
    unsafe {
        // 释放文本规范化相关资源
        // (注意：unorm2_getNFCInstance返回的是共享实例，不需要关闭)
        
        // 释放日期格式化相关资源
        udat_close(df);
        uloc_close(loc_en);
        
        // 释放数字格式化相关资源
        unum_close(nf);
        uloc_close(loc_fr);
    }
}

注意事项

1. 大多数ICU C API函数需要手动管理内存，确保正确释放资源
2. 错误处理通过返回的UErrorCode进行
3. 字符串通常以UTF-16格式处理
4. 在多线程环境中使用时需要注意线程安全性

高级功能

icu_capi还支持更高级的功能，如：

• 双向文本处理(阿拉伯语、希伯来语等)
• 断词和断行
• 转换器(字符编码转换)
• 复数规则和消息格式化

性能建议

1. 重用格式化器实例，避免频繁创建和销毁
2. 对于固定模式，考虑预编译模式
3. 使用缓冲区重用技术减少内存分配

通过icu_capi，Rust开发者可以方便地利用ICU库的强大国际化功能，同时保持与C语言生态系统的互操作性。