Metadata-Version: 2.4
Name: blitzbuffers
Version: 0.3.0
Summary: Code-generation library and tool for the BlitzBuffers serialization format
Project-URL: Homepage, https://github.com/InoUno/blitzbuffers
Project-URL: Issues, https://github.com/InoUno/blitzbuffers/issues
Author-email: InoUno <inoiown@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: lark
Description-Content-Type: text/markdown

# ⚡BlitzBuffers

[![CI](https://github.com/InoUno/blitzbuffers/actions/workflows/build.yml/badge.svg)](https://github.com/InoUno/blitzbuffers/actions/workflows/build.yml)
[![PyPI version](https://badge.fury.io/py/blitzbuffers.svg)](https://badge.fury.io/py/blitzbuffers)

BlitzBuffers is a serialization format and code generator designed for **_lightning-fast_** conversion of data to and from byte buffers by utilizing direct serialization and deserialization.

## Pros

- **_Very fast_** serialization and deserialization of data (see [benchmarks](#benchmarks)).
- **Cross-language support** via code generation based on a given schema file.
- **Simple, but powerful schema syntax** featuring structs, enums, tagged unions, vectors, and strings.
- **Zero-copy** serialization and deserialization - directly reads from and writes to the buffer.
- **Easy-to-use API** via the generated code.
- **Code generation via Python**, which makes it simple to integrate into your workflow, instead of having to deal with executables or build steps of other projects.

## Cons

- Unset fields take up space in the buffer.
- No easy schema versioning.
- Not many languages supported (yet).
- No endianness checks in C++ (yet) - only use it on little-endian machines.

# Schema

The schema syntax and capabilities take inspiration from the [Rust language](https://www.rust-lang.org/).

<details>
<summary>Expand to see an example using the various constructs.</summary>

```bzb
namespace game

enum EntityType {
    Player
    Neutral
    Enemy
}

struct Position {
    x: f32
    y: f32
    z: f32
}

struct Entity {
    type: EntityType
    name: string
    hitpoints: u64
    position: Position
    traits: Trait[]
}

enum Trait {
    Height(u16, u16),

    Color {
        red: u8
        green: u8
        blue: u8
        alpha: u8
    }

}
```
</details>

# Installation

The code-generation tool can be installed via [pip](https://pypi.org/project/pip/):

```
pip3 install blitzbuffers
```

# Code generation

Code for the desired languages can be generated by calling the module directly.
You can specify one or more languages in a single command-line:

```
python3 -m blitzbuffers <schema-path> [-l <language> <output-file-path>]
```

Available languages are currently: `cpp`, `rust`

# Benchmarks

A few benchmarks showing the difference between blitzbuffers and other tools/libraries with similar functionality.

## C++

Deserialization/usage is the same for blitzbuffers no matter the setup.

| Setup                     | Serialization  | Deserialization/Usage (checked) | Roundtrip |
|-|-|-|-|
| Blitzbuffers (fixed)      | 34.8 ns   | 74.7 ns               | 125 ns    |
| Blitzbuffers (expanding)  | 105 ns    | 74.8 ns               | 187 ns    |
| Flatbuffers               | 433 ns    | 176 ns                | 620 ns    |
| alpaca                    | 218 ns    | 479 ns                | 717 ns    |

## Rust

Deserialization/usage is the same for blitzbuffers no matter the setup. Checked vs. unchecked, is whether the data buffer is verified before the data in it is used.

| Setup                     | Serialization | Deserialization/Usage (checked) | Deserialization/Usage (unchecked) |
|-|-|-|-|
| Blitzbuffers (fixed)        | 77.3 ns     | 181.4 ns  | 116.8 ns
| Blitzbuffers (expanding)    | 141.1 ns    | -         | -
| Blitzbuffers (raw first)    | 593.8 ns    | -         | -
| Blitzbuffers (raw storage)  | 107.1 ns    | -         | -
| Flatbuffers                 | 410.8 ns    | 595.9 ns  | 129.9 ns

