78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# bipack_ru: Rust Bipack implementation
|
|
|
|
Bipack serialization format is a compact binary format that was created as areplacement for a
|
|
BOSS format, mode compact, faster, and not revealing inner data structure as much as possible.
|
|
It is used in our next generation data protection systems, in DiWAN products as a base format and also in my newe communication package like [kiloparsec](https://gitea.sergeych.net/sergeych/kiloparsec)
|
|
(and in underlying [crypto2](https://gitea.sergeych.net/sergeych/crypto2)) which are intended
|
|
to replace older `Parsec` protocols family to cope with modern crazy world challenges.
|
|
|
|
>__IMPORTANT__ due to growing tensions in the world, the main development is moved to our [Gitea repository](https://gitea.sergeych.net/DiWAN/bipack_ru). We will try our best to make it available all around the world.
|
|
|
|
The most recent code will be there, and we encourage to use it also for issues/discussions.
|
|
|
|
> Beta test
|
|
|
|
# Use with serde:
|
|
|
|
Use `bipack_ru:ser:to_bytes()` and `bipack_ru:de:from_bytes()` functions:
|
|
```rust
|
|
fn test() -> Result<(),Error> {
|
|
let src = HashSet::from(["foo", "bar", "buz"].map(|i| i.to_string()));
|
|
let packed = to_bytes(&src)?;
|
|
println!("{}", to_dump(&packed));
|
|
|
|
let restored: HashSet<String> = from_bytes(&packed)?;
|
|
println!("{:?}", restored);
|
|
assert_eq!(src, restored);
|
|
}
|
|
```
|
|
|
|
|
|
serde module supports all Rust formats except floats/doubles which are not yet used and
|
|
standardised by bipack format.
|
|
|
|
- All integers, signed and unsigned, are encoded with variable-length `smartint`.
|
|
|
|
Fixed-size encoding is available using custom de/serializers (exactly as in postcard format):
|
|
|
|
```rust
|
|
#[derive(Serialize)]
|
|
pub struct DefinitelyBigEndian {
|
|
#[serde(with = "bipack_ru::fixint::be")]
|
|
// or #[serde(with = "bipack_ru::fixint::le")]
|
|
x: u16,
|
|
}
|
|
```
|
|
|
|
# Direct usage (no serde)
|
|
|
|
The sample code (see `src/lib.rs` for more:)
|
|
```rust
|
|
fn test() {
|
|
let mut data = Vec::<u8>::new();
|
|
data.put_str("Hello, rupack!");
|
|
println!("size ${}\n{}", data.len(), to_dump(&data));
|
|
let mut src = SliceSource::from(&data);
|
|
assert_eq!("Hello, rupack!", src.get_str().unwrap());
|
|
}
|
|
```
|
|
|
|
## Tools and macros
|
|
|
|
- `to_dump` to convert binary slice into human-readable dump
|
|
- `StringBuilder` super minimalistic string builder (footprint).
|
|
|
|
|
|
The autodoc documentation is good enough already, so we do not repeat it here now.
|
|
|
|
## How to
|
|
|
|
- just ad this package to your dependencies, it is on crates.io.
|
|
|
|
## Big thanks
|
|
|
|
- to https://github.com/jamesmunns for the brilliant postcard format which was used as a model.
|
|
|
|
# License
|
|
|
|
For compliance with other modules this work is provided under APACHE 2.0 license a copy of which is included in the file `LICENSE`. |