Rust常量解码库const-decoder使用指南

概述

const-decoder是一个专门用于编译时高效解析与转换常量数据的Rust库。它通过过程宏和常量函数（const fn）的结合，实现了在编译期间对常量数据进行解码和转换操作，避免了运行时开销。

主要特性

• 编译时数据解析和转换
• 支持多种数据格式（十六进制、Base64、ASCII等）
• 零运行时开销
• 类型安全的解码操作

安装方法

在Cargo.toml中添加依赖：

[dependencies]
const-decoder = "0.3"

基本用法示例

1. 十六进制解码

use const_decoder::Decoder;

const HEX_DATA: &[u8] = Decoder::Hex.decode(b"48656c6c6f20576f726c64");
const EXPECTED: &[u8] = b"Hello World";

fn main() {
    assert_eq!(HEX_DATA, EXPECTED);
}

2. Base64解码

use const_decoder::Decoder;

const BASE64_DATA: &[u8] = Decoder::Base64.decode(b"SGVsbG8gV29ybGQ=");
const EXPECTED: &[u8] = b"Hello World";

fn main() {
    assert_eq!(BASE64_DATA, EXPECTED);
}

3. 自定义数组解码

use const_decoder::Decoder;

const ARRAY_DATA: [u8; 5] = Decoder::Hex.decode_array(b"0102030405");
const EXPECTED: [u8; 5] = [1, 2, 3, 4, 5];

fn main() {
    assert_eq!(ARRAY_DATA, EXPECTED);
}

4. 字符串转换

use const_decoder::Decoder;

const STR_DATA: &str = Decoder::Hex.decode_str(b"48656c6c6f");
const EXPECTED: &str = "Hello";

fn main() {
    assert_eq!(STR_DATA, EXPECTED);
}

高级用法

自定义解码器

use const_decoder::{Decoder, Decode};

// 自定义解码函数
const fn custom_decode(input: &[u8]) -> Vec<u8> {
    // 实现自定义解码逻辑
    let mut result = Vec::new();
    let mut i = 0;
    while i < input.len() {
        result.push(input[i] ^ 0xFF); // 简单的XOR解码示例
        i += 1;
    }
    result
}

const CUSTOM_DATA: Vec<u8> = custom_decode(b"test_data");

结合过程宏使用

use const_decoder::const_decode;

#[const_decode(hex = "48656c6c6f")]
const GREETING: &str = "decoded";

fn main() {
    println!("{}", GREETING); // 输出: Hello
}

完整示例demo

// 演示const-decoder库的完整使用示例
use const_decoder::{Decoder, const_decode};

// 基本解码示例
const HEX_DECODED: &[u8] = Decoder::Hex.decode(b"48656c6c6f20576f726c64"); // "Hello World"的十六进制编码
const BASE64_DECODED: &[u8] = Decoder::Base64.decode(b"SGVsbG8gV29ybGQ="); // "Hello World"的Base64编码

// 数组解码
const ARRAY_DECODED: [u8; 5] = Decoder::Hex.decode_array(b"0102030405"); // 解码为[1, 2, 3, 4, 5]

// 字符串解码
const STR_DECODED: &str = Decoder::Hex.decode_str(b"48656c6c6f"); // 解码为"Hello"

// 使用过程宏进行解码
#[const_decode(hex = "52657374206465636f646572")]
const MACRO_DECODED: &str = "placeholder";

// 自定义解码函数
const fn xor_decode(input: &[u8]) -> Vec<u8> {
    let mut result = Vec::with_capacity(input.len());
    let mut i = 0;
    while i < input.len() {
        result.push(input[i] ^ 0x55); // 使用0x55作为XOR密钥
        i += 1;
    }
    result
}

const CUSTOM_DECODED: Vec<u8> = xor_decode(b"test_data");

fn main() {
    // 验证十六进制解码
    assert_eq!(HEX_DECODED, b"Hello World");
    println!("十六进制解码: {:?}", String::from_utf8_lossy(HEX_DECODED));
    
    // 验证Base64解码
    assert_eq!(BASE64_DECODED, b"Hello World");
    println!("Base64解码: {:?}", String::from_utf8_lossy(BASE64_DECODED));
    
    // 验证数组解码
    assert_eq!(ARRAY_DECODED, [1, 2, 3, 4, 5]);
    println!("数组解码: {:?}", ARRAY_DECODED);
    
    // 验证字符串解码
    assert_eq!(STR_DECODED, "Hello");
    println!("字符串解码: {}", STR_DECODED);
    
    // 验证过程宏解码
    assert_eq!(MACRO_DECODED, "Rust decoder");
    println!("过程宏解码: {}", MACRO_DECODED);
    
    // 验证自定义解码
    println!("自定义XOR解码: {:?}", CUSTOM_DECODED);
    
    println!("所有解码操作均在编译时完成，零运行时开销！");
}

注意事项

1. 所有解码操作都在编译时完成
2. 输入数据必须是常量表达式
3. 解码失败会在编译时报错
4. 支持no_std环境

性能优势

由于所有解码操作都在编译时完成，生成的二进制文件中只包含解码后的结果，因此：

• 零运行时开销
• 不会增加二进制大小（相比运行时解码）
• 编译时错误检查

这个库特别适合处理嵌入式开发、密码学操作和需要高性能常量数据处理的场景。