[][src]Crate abin

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 Definitions

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.