abin/lib.rs
1//! A library for working with binaries and strings. The library tries to avoid
2//! heap-allocations / memory-copy whenever possible by automatically choosing a reasonable
3//! strategy: stack for small binaries; static-lifetime-binary or reference-counting. It's
4//! easy to use (no lifetimes; the binary type is sized), `Send + Sync` is optional (thus
5//! no synchronization overhead), provides optional serde support and has a similar API for
6//! strings and binaries. Custom binary/string types can be implemented for fine-tuning.
7//!
8//! ```rust
9//! use std::iter::FromIterator;
10//! use std::ops::Deref;
11//! use abin::{AnyBin, AnyStr, Bin, BinFactory, NewBin, NewStr, Str, StrFactory};
12//!
13//! // static binary / static string
14//! let static_bin: Bin = NewBin::from_static("I'm a static binary, hello!".as_bytes());
15//! let static_str: Str = NewStr::from_static("I'm a static binary, hello!");
16//! assert_eq!(&static_bin, static_str.as_bin());
17//! assert_eq!(static_str.as_str(), "I'm a static binary, hello!");
18//! // non-static (but small enough to be stored on the stack)
19//! let hello_bin: Bin = NewBin::from_iter([72u8, 101u8, 108u8, 108u8, 111u8].iter().copied());
20//! let hello_str: Str = NewStr::copy_from_str("Hello");
21//! assert_eq!(&hello_bin, hello_str.as_bin());
22//! assert_eq!(hello_str.as_ref() as &str, "Hello");
23//!
24//! // operations for binaries / strings
25//!
26//! // length (number of bytes / number of utf-8 bytes)
27//! assert_eq!(5, hello_bin.len());
28//! assert_eq!(5, hello_str.len());
29//! // is_empty
30//! assert_eq!(false, hello_bin.is_empty());
31//! assert_eq!(false, hello_str.is_empty());
32//! // as_slice / as_str / deref / as_bin
33//! assert_eq!(&[72u8, 101u8, 108u8, 108u8, 111u8], hello_bin.as_slice());
34//! assert_eq!("Hello", hello_str.as_str());
35//! assert_eq!("Hello", hello_str.deref());
36//! assert_eq!(&hello_bin, hello_str.as_bin());
37//! // slice
38//! assert_eq!(
39//! NewBin::from_static(&[72u8, 101u8]),
40//! hello_bin.slice(0..2).unwrap()
41//! );
42//! assert_eq!(NewStr::from_static("He"), hello_str.slice(0..2).unwrap());
43//! // clone
44//! assert_eq!(hello_bin.clone(), hello_bin);
45//! assert_eq!(hello_str.clone(), hello_str);
46//! // compare
47//! assert!(NewBin::from_static(&[255u8]) > hello_bin);
48//! assert!(NewStr::from_static("Z") > hello_str);
49//! // convert string into binary and binary into string
50//! let hello_bin_from_str: Bin = hello_str.clone().into_bin();
51//! assert_eq!(hello_bin_from_str, hello_bin);
52//! let hello_str_from_bin: Str = AnyStr::from_utf8(hello_bin.clone()).expect("invalid utf8!");
53//! assert_eq!(hello_str_from_bin, hello_str);
54//! // convert into Vec<u8> / String
55//! assert_eq!(
56//! Vec::from_iter([72u8, 101u8, 108u8, 108u8, 111u8].iter().copied()),
57//! hello_bin.into_vec()
58//! );
59//! assert_eq!("Hello".to_owned(), hello_str.into_string());
60//! ```
61
62pub mod spi;
63#[cfg(any(test, feature = "serde"))]
64pub use serde_support::*;
65pub use {binary::*, boo::*, common::*, implementation::*, string::*};
66
67mod binary;
68mod boo;
69mod common;
70mod implementation;
71mod string;
72
73#[cfg(any(test, feature = "serde"))]
74mod serde_support;