QUOX

Quox is a header-only, C++ template library for encoding and decoding meaningful, structured information from binary data. Her primary use-case is in file-program interaction and packet-program interaction. As a header-only library, She is portable by design and able to be included in any C++ project. She takes inspiration from functional programming and operations attempt to inline all callbacks and store no "state".

This library makes heavy use of the C++ Standard Template Library and so compiled binary outputs can be slightly different between compilers, especially in regards to optimisation, dependent on the relevant compiler's implementation of the C++ STL.

Name

After many iterations on alterations of the name "codecs" and finding them all to be taken by other, existing libraries, "Quox" was eventually settled on. It is known that there is at least one, unassociated, fictional creature by this name. Whilst the codebase is written with English-speakers in mind, if using this name in the context of a language with grammatical gender, this name is gendered as feminine.

Features

This supports encoding to bytes and decoding from bytes for the following data formats:

• Integers

  • Contiguous primitives

  • LEB128 primitives

  • Non-primitive ("big int")

• Floating points

• Booleans

• Strings

  • Pre-sized

  • Null-terminated

• Unions/Variants

• Collections

• Maps

• Tuples

• Ternaries

  • Abstract

  • Conditionals

  • Optionals

• Casting

Usage

All functionality is available to anyone who adds the code of this library to their project and adds the project's "include" directory as an include path.

If your project is source-controlled using git and compiled using g++, one way to achieve this is:

git submodule add <repo URL>

and then

g++ <the rest of your arguments> -Iquox/include

Requirements

This library uses C++26 features with plans to optionally support older versions of C++. Every header is individually includable, though they will include their dependent headers, so it is possible to use parts of this library on unsupported C++ versions by only including compatible headers.

No specific compilers or compiler arguments are supported but, as a template library, this should be supported on all compilers that support templates.

This library depends on no non-standard libraries and so does not require the installation of any such libraries.

Dependencies

As a rule, this header-only library does not add independent, versioned submodules. The reasoning for this is manifold:

1. this can lead to situations where large projects employ the same header-only library more than once but at different versions of it,

2. there is no guarantee that updates required to keep a header-only library functional and/or safe are going to remain header-only, and

3. this library does not define any specifics on how it must be used in a compiled program.

Dependent submodules (i.e. submodules that explicitly exist only to serve Quox) would be allowed but are unexpected to be of use.

Zpauk

Version: v0.0.2

Git SHA: 959ae6f849bc9c66660293274ecf5af8e2b1d294

Available at: git.mnpx.dev

Zpauk's include directory must be in include path.

Goals

By default, as a header-only, template library, Quox is massively optimisable. This feature of the library is the primary, driving goal of the library. She is designed in mind for future compilers that allow her code to be optimised even further at compilation.

The problem of making an optimised, binary-encoding/binary-decoding library is complex and so another goal of this project is to do justice to that complexity by allowing for manifold operation within her. No attempt to "simplify" the flow is warranted by her design.

Testing

Unit test cases are to be written to allow automatic testing of the codebase. No work has yet been done to implement this. Specific libraries and programs to be used to do unit testing are as-of-yet unchosen.

A limitation of test cases for template libraries that are designed like this library is that total code coverage is impossible due to the permutable nature of how individual lines of code can come to behave with significant differences dependent on which template parameters are provided by the end-user. The goal with unit testing for this library is to establish a set of arbitrary, common tests that describe some functionality without wholly encompassing the infinite capacity of each temploid.

Credits

• Primary codebase development, MnPX
• C++ STL design, Alexander Stepanov