Rust UCS2编解码库ucs2的使用指南

概述

ucs2是一个专门用于处理UCS-2和UTF-16编码转换的Rust库，提供了高效的编码解码功能，特别适合处理遗留系统和特定协议中的UCS-2编码数据。

安装方法

在Cargo.toml中添加依赖：

[dependencies]
ucs2 = "0.1"

核心功能

1. 字符串编码

use ucs2;

fn main() {
    let text = "Hello 世界";
    let encoded = ucs2::encode(text).unwrap();
    println!("编码结果: {:?}", encoded);
}

2. 字节解码

use ucs2;

fn main() {
    let bytes: Vec<u8> = vec![0x48, 0x00, 0x65, 0x00, 0x6C, 0x00, 0x6C, 0x00, 0x6F, 0x00];
    let decoded = ucs2::decode(&bytes).unwrap();
    println!("解码结果: {}", decoded);
}

3. 处理UCS-2字节流

use ucs2;

fn process_ucs2_data(data: &[u8]) -> Result<String, ucs2::Error> {
    ucs2::decode_with_bom(data)
}

fn main() {
    let ucs2_data = include_bytes!("data.ucs2");
    match process_ucs2_data(ucs2_data) {
        Ok(text) => println!("处理结果: {}", text),
        Err(e) => println!("处理错误: {:?}", e),
    }
}

高级用法

批量处理

use ucs2;

fn batch_encode(strings: Vec<&str>) -> Vec<Vec<u8>> {
    strings.into_iter()
        .filter_map(|s| ucs2::encode(s).ok())
        .collect()
}

fn main() {
    let texts = vec!["文本1", "text2", "另一个文本"];
    let encoded_data = batch_encode(texts);
    println!("批量编码结果: {:?}", encoded_data);
}

错误处理

use ucs2;

fn safe_decode(bytes: &[u8]) -> Result<String, String> {
    ucs2::decode(bytes)
        .map_err(|e| format!("解码失败: {:?}", e))
}

fn main() {
    let invalid_data = vec![0xFF, 0xFF]; // 无效的UCS-2数据
    match safe_decode(&invalid_data) {
        Ok(text) => println!("成功: {}", text),
        Err(e) => println!("错误: {}", e),
    }
}

完整示例demo

// 完整UCS2编解码示例
use ucs2;

fn main() {
    // 示例1: 字符串编码
    println!("=== 字符串编码示例 ===");
    let text = "Hello UCS2 编码测试";
    match ucs2::encode(text) {
        Ok(encoded) => {
            println!("原始文本: {}", text);
            println!("编码结果: {:?}", encoded);
        }
        Err(e) => println!("编码错误: {:?}", e),
    }

    println!("\n=== 字节解码示例 ===");
    // 示例2: 字节解码
    let ucs2_bytes = vec![
        0x48, 0x00, 0x65, 0x00, 0x6C, 0x00, 0x6C, 0x00, 0x6F, 0x00, // Hello
        0x20, 0x00, // 空格
        0x57, 0x00, 0x6F, 0x00, 0x72, 0x00, 0x6C, 0x00, 0x64, 0x00  // World
    ];
    
    match ucs2::decode(&ucs2_bytes) {
        Ok(decoded) => {
            println!("UCS2字节: {:?}", ucs2_bytes);
            println!("解码文本: {}", decoded);
        }
        Err(e) => println!("解码错误: {:?}", e),
    }

    println!("\n=== 批量处理示例 ===");
    // 示例3: 批量编码
    let texts = vec!["第一个文本", "second text", "第三段文字内容"];
    let encoded_results: Vec<Vec<u8>> = texts.iter()
        .filter_map(|s| ucs2::encode(s).ok())
        .collect();
    
    for (i, encoded) in encoded_results.iter().enumerate() {
        println!("文本{}编码结果: {:?}", i + 1, encoded);
    }

    println!("\n=== 错误处理示例 ===");
    // 示例4: 错误处理
    let invalid_bytes = vec![0xFF, 0xFF, 0x00, 0xD8]; // 无效的UCS-2数据
    
    match ucs2::decode(&invalid_bytes) {
        Ok(text) => println!("解码成功: {}", text),
        Err(e) => println!("预期中的解码错误: {:?}", e),
    }

    println!("\n=== 带BOM处理示例 ===");
    // 示例5: 带BOM标记的数据处理
    let data_with_bom = vec![0xFF, 0xFE, 0x48, 0x00, 0x65, 0x00, 0x6C, 0x00, 0x6C, 0x00, 0x6F, 0x00];
    
    match ucs2::decode_with_bom(&data_with_bom) {
        Ok(text) => println!("带BOM解码结果: {}", text),
        Err(e) => println!("BOM处理错误: {:?}", e),
    }
}

// 高级用法：自定义错误处理函数
fn robust_ucs2_decode(data: &[u8]) -> Result<String, String> {
    ucs2::decode(data)
        .map_err(|e| match e {
            ucs2::Error::OddLength => "数据长度不是偶数".to_string(),
            ucs2::Error::InvalidChar => "包含无效UCS-2字符".to_string(),
            _ => "未知解码错误".to_string(),
        })
}

// 高级用法：流式处理函数
fn stream_ucs2_processor(chunks: Vec<Vec<u8>>) -> Vec<String> {
    chunks.into_iter()
        .filter_map(|chunk| ucs2::decode(&chunk).ok())
        .collect()
}

性能提示

• 对于大量数据处理，建议复用编码器实例
• 使用decode_with_bom自动处理字节顺序标记
• 考虑使用迭代器模式处理流式数据

注意事项

• UCS-2不支持Unicode增补平面字符（代码点大于0xFFFF）
• 在处理未知数据时始终检查解码结果
• 注意字节序问题，特别是在跨平台应用中

这个库为处理传统的UCS-2编码数据提供了简单高效的解决方案，特别适合与遗留系统交互和处理特定协议数据。