Crate abin

Expand description

A library for working with binaries and strings. The library tries to avoid heap-allocations / memory-copy whenever possible by automatically choosing a reasonable strategy: stack for small binaries; static-lifetime-binary or reference-counting. It’s easy to use (no lifetimes; the binary type is sized), Send + Sync is optional (thus no synchronization overhead), provides optional serde support and has a similar API for strings and binaries. Custom binary/string types can be implemented for fine-tuning.

use std::iter::FromIterator;
use std::ops::Deref;
use abin::{AnyBin, AnyStr, Bin, BinFactory, NewBin, NewStr, Str, StrFactory};

// 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());

Modules§

spi: The SPI (Service Provider Interface) contains types you only need if you want to provide your own binary implementation. Most types/functions in this module are unsafe. If you’re using things from this module or if you need unsafe, this means two things: You’re either implementing your own binary type or you’re doing something wrong (as a user of this crate you won’t need unsafe code, nor things from this module).

Structs§

AnyStr: A utf-8 string backed by AnyBin (Bin or SBin), see also Str and SStr.
AnyStrUtf8Error: Error returned when trying to create a AnyStr from a binary that contains invalid utf-8.
Bin: A binary that does not implement Send + Sync. See AnyBin for documentation; see SBin if you need Send + Sync. See BinFactory on how to create binaries.
Bytes128: Up to 16 bytes / 128 bit stored on the stack.
DefaultExcessShrink: Default implementation of ExcessShrink - should be ok for most use cases.
IntoIter: Consuming iterator for a binary.
NeverShrink: Never performs an excess shrink.
NewBin: Default implementation used to create Bin. See BinFactory for documentation.
NewSBin: Default implementation used to create SBin. See BinFactory for documentation.
NewSStr: Default implementation used to create SStr. See StrFactory for documentation.
NewStr: Default implementation used to create Str. See StrFactory for documentation.
SBin: A binary that does implement Send + Sync. See AnyBin for documentation; see Bin if you don’t need Send + Sync. See BinFactory on how to create binaries.
SegmentsSlice: It’s an implementation of SegmentIterator that does not heap-allocate. Alternatives are BinBuilder and StrBuilder; SegmentsSlice is less flexible but cheaper (smaller stack; faster).
ShrinkResult: Whether to shrink the vector and if so, how much excess to keep.

Enums§

BinSegment: A segment; segments can be joined to create binaries. See BinBuilder, SegmentIterator and SegmentsSlice.
Boo: A borrowed-or-owned type (boo).
GivenVecOptimization: Hint on what optimization to perform when constructing a binary from a Vec<u8>. Optimize for construction (see BinFactory::from_given_vec) or optimize for operations (such as clone or slice).
StrSegment: A segment; segments can be joined to create strings. See StrBuilder, SegmentIterator and SegmentsSlice.

Traits§

AnyBin: Common trait implemented by Bin and SBin.
BinBuilder: Trait used to build a binary efficiently (with just one allocation & no re-allocation or even without allocation).
BinFactory: Use this factory to create binaries. There’s a built-in implementation in this crate; custom implementations (that implement this trait) are possible.
BooToOwned: Converts the borrowed value of Boo to owned. See Boo::into_owned_with for details.
ExcessShrink: Gives information whether the system should shrink a vector’s excess (capacity - len).
GivenVecConfig: Custom configuration used for BinFactory::from_given_vec / BinFactory::from_given_vec_with_config).
IntoSync: Converts this into a synchronized version.
IntoUnSync: Converts self into the un-synchronized version.
IntoUnSyncView: Returns the un-synchronized view of self.
Segment: Some sort of segment that knows its length (in bytes). It’s used for constructing binaries/strings efficiently (knowing the entire length in advance to avoid re-allocations).
SegmentIterator: An iterator for Segment.
StrBuilder: Trait used to build a string efficiently (with just one allocation & no re-allocation or even without allocation).
StrFactory: Use this factory to create strings. There’s a built-in implementation in this crate; custom implementations (that implement this trait) are possible.
ToBooConverter: Can convert &T to Boo::Borrowed and T to Boo:Owned.
UnSyncRef: Returns the un-synchronized view of self (as reference).

Functions§

maybe_shrink: Shrinks the vector (if T says to do so). Returns true if vec has been shrunk, returns false if not.

Type Aliases§

BooBin: Borrowed-or-owned Bin.
BooSBin: Borrowed-or-owned SBin.
BooSStr: Borrowed-or-owned SStr.
BooStr: Borrowed-or-owned Str.
FromUtf8IterResult: The result produced by from_utf8_iter. Is either a AnyStr or an AnyStrUtf8Error on error (invalid UTF-8).
SStr: A string backed by SBin (Sync + Send), see Str if you don’t need Sync + Send.
Str: A string backed by Bin (not Sync + Send), see SStr if you need Sync + Send.