abin

一个用于处理二进制和字符串的库。该库尽可能避免堆分配/内存复制，通过自动选择合理的策略：对小二进制使用栈；静态生命周期二进制或引用计数。它易于使用（没有生命周期；二进制类型有大小），Send + Sync 是可选的（因此没有同步开销），提供可选的 serde 支持，并具有类似字符串和二进制的 API。可以实现自定义二进制/字符串类型以进行精细调整。

提供类似功能的库

• https://github.com/tokio-rs/bytes
• https://github.com/rust-analyzer/smol_str

许可协议

许可协议为以下之一

• Apache 许可证版本 2.0 (LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任选其一。

详细信息

使用说明

[dependencies]
abin = "*"

use std::iter::FromIterator;
use std::ops::Deref;

use abin::{AnyBin, AnyStr, Bin, BinFactory, NewBin, NewStr, Str, StrFactory};

#[test]
fn usage_basics() {
    // static binary / static string
    let static_bin: Bin = NewBin::from_static("I'm a static binary, hello!".as_bytes());
    let static_str: Str = NewStr::from_static("I'm a static binary, hello!");
    assert_eq!(&static_bin, static_str.as_bin());
    assert_eq!(static_str.as_str(), "I'm a static binary, hello!");
    // non-static (but small enough to be stored on the stack)
    let hello_bin: Bin = NewBin::from_iter([72u8, 101u8, 108u8, 108u8, 111u8].iter().copied());
    let hello_str: Str = NewStr::copy_from_str("Hello");
    assert_eq!(&hello_bin, hello_str.as_bin());
    assert_eq!(hello_str.as_ref() as &str, "Hello");

    // operations for binaries / strings

    // length (number of bytes / number of utf-8 bytes)
    assert_eq!(5, hello_bin.len());
    assert_eq!(5, hello_str.len());
    // is_empty
    assert_eq!(false, hello_bin.is_empty());
    assert_eq!(false, hello_str.is_empty());
    // as_slice / as_str / deref / as_bin
    assert_eq!(&[72u8, 101u8, 108u8, 108u8, 111u8], hello_bin.as_slice());
    assert_eq!("Hello", hello_str.as_str());
    assert_eq!("Hello", hello_str.deref());
    assert_eq!(&hello_bin, hello_str.as_bin());
    // slice
    assert_eq!(
        NewBin::from_static(&[72u8, 101u8]),
        hello_bin.slice(0..2).unwrap()
    );
    assert_eq!(NewStr::from_static("He"), hello_str.slice(0..2).unwrap());
    // clone
    assert_eq!(hello_bin.clone(), hello_bin);
    assert_eq!(hello_str.clone(), hello_str);
    // compare
    assert!(NewBin::from_static(&[255u8]) > hello_bin);
    assert!(NewStr::from_static("Z") > hello_str);
    // convert string into binary and binary into string
    let hello_bin_from_str: Bin = hello_str.clone().into_bin();
    assert_eq!(hello_bin_from_str, hello_bin);
    let hello_str_from_bin: Str = AnyStr::from_utf8(hello_bin.clone()).expect("invalid utf8!");
    assert_eq!(hello_str_from_bin, hello_str);
    // convert into Vec<u8> / String
    assert_eq!(
        Vec::from_iter([72u8, 101u8, 108u8, 108u8, 111u8].iter().copied()),
        hello_bin.into_vec()
    );
    assert_eq!("Hello".to_owned(), hello_str.into_string());
}

值得注意的结构体、特质和类型及命名

接口

• Bin: 二进制（它是一个结构体）。
• SBin: 同步二进制（它是一个结构体）。
• Str: 字符串 (type Str = AnyStr<Bin>)
• SStr: 同步字符串 (type SStr = AnyStr<SBin>)。

默认实现提供工厂

• NewBin: 创建 Bin。
• NewSBin: 创建 SBin。
• NewStr：创建Str。
• NewSStr：创建SStr。

参见

• AnyBin：由Bin和SBin实现的特性。
• AnyStr：参见Str和SStr；由Bin或SBin支持的字符串。
• BinFactory：由NewBin和NewSBin实现的工厂特性。
• StrFactory：由NewStr和NewSStr实现的工厂特性。

学习

查看示例测试

• usage_1_basics.rs：基本用法。
• usage_2_creating.rs：如何创建二进制和字符串。
• usage_3_builder.rs：如何使用构建器创建二进制/字符串。
• usage_4_operations.rs：二进制和字符串提供的操作，例如切片、将二进制转换为字符串以及将二进制/字符串转换为Vec<u8>和String。
• usage_5_boo.rs："借用的或拥有的"（boo），Cow的替代方案，适用于未实现ToOwned的类型。
• usage_6_serde_boo.rs：使用Boo与serde。
• usage_7_serde_ri.rs：使用serde与重集成（也参见问题和答案）。
• usage_8_send_sync.rs：同步（Send + Sync）和非同步的二进制/字符串。
• usage_9_re_integration.rs：重集成（也参见问题和答案）

let large_binary_from_network : Vec<u8> = <...>;
let bin = NewBin::from_given_vec(large_binary_from_network);
let slice_of_that_bin : &[u8] = &bin.as_slice()[45..458];

// it's now possible to re-integrate that `slice_of_that_bin` into the `bin` it was sliced from.
// re-integration converts the borrowed type `&[u8]` (`slice_of_that_bin`) into an owned
// type (`Bin`) without memory-allocation or memory-copy.
let bin_re_integrated : Bin = bin.try_re_integrate(slice_of_that_bin).unwrap();

cd benchmark
cargo bench
cargo test

{ allocations: 3154, deallocations: 3154, reallocations: 12, bytes_allocated: 388755346,
bytes_deallocated: 388755346, bytes_reallocated: 11520 }

{ allocations: 15454, deallocations: 15454, reallocations: 2212, bytes_allocated: 494895196,
bytes_deallocated: 494895196, bytes_reallocated: 520 }

{ allocations: 18154, deallocations: 18154, reallocations: 12, bytes_allocated: 495272868,
bytes_deallocated: 495272868, bytes_reallocated: 14400 }

{ allocations: 21754, deallocations: 21754, reallocations: 1212, bytes_allocated: 848171274,
bytes_deallocated: 848171274, bytes_reallocated: 105981240 }

{ allocations: 34354, deallocations: 34354, reallocations: 1212, bytes_allocated: 1201859852,
bytes_deallocated: 1201859852, bytes_reallocated: 105978360 }

time:   [65.503 ms 67.157 ms 68.869 ms]
Found 1 outliers among 100 measurements (1.00%)

time:   [71.207 ms 72.825 ms 74.546 ms]
Found 3 outliers among 100 measurements (3.00%)

time:   [89.518 ms 91.279 ms 93.124 ms]
Found 13 outliers among 100 measurements (13.00%)

time:   [78.972 ms 79.765 ms 80.556 ms]
Found 4 outliers among 100 measurements (4.00%)

time:   [118.53 ms 121.24 ms 124.15 ms]
Found 21 outliers among 100 measurements (21.00%)

time:   [118.36 ms 118.90 ms 119.56 ms]
Found 10 outliers among 100 measurements (10.00%)