# Entropic

---

## Entropic - Easily Convert Rust Structures To/From Unstructured Bytes

The `Entropic` trait enables the conversion of raw bytes into Rust data structures and back.

## Mapping to/from unstructured bytes

`entropic` srives to provide a few guarantees about the way it maps data:

**1. Every data structure value will be mapped to by one or more unstructured byte sequences.**

In mathematical terms, this means that the function from unstructured bytes to data structures is _surjective_.
It's not uncommon for multiple different unstructured byte sequences to map to the same data structure value, so it should not be assumed that a different byte input will lead to different output. 

Some data structure values may have a slightly greater chance of being chosen than others due to this surjective mapping.
Certain schemes provide guaranteed bounds on the probability delta between different values, and the `PureRandomScheme` aims to provide cryptographically-secure guarantees on each resulting output value having identical odds of occuring given an input; however, these guarantees come at the cost of consuming much more entropy input bytes on average than other schemes. 

**2. Data structures will map to unstructured bytes that always map back to that same data structure.**

In mathematical terms, suppose `U` is the set of all possible unstructured byte sequences and `S` is the set of all possible data structure values.
`entropic` provides two functions (`from_entropy_source` and `to_entropy_sink`) that can respectively be represented by `f: U -> S` and `g: S -> U`.
For every value `s` in `S`, entropic aims to guarantee that `f(g(s)) == s`.
_However_, it is _not_ the case that `g(f(u)) == u` for all `u` in `U`--several byte sequences may map to the same data structure value, but that value can only map back to one of those sequences.

This property is particularly useful when using `entropic` for fuzzing data structures.
Fuzzing has been shown to be much more effective across domains when provided with semantically-valid starting seeds that explore interesting paths.
As such, `entropic` allows one to define an expected data structure and convert it to a byte sequence that will subsequently map to that same structure during fuzzing.

## Improvements over other libraries

- Allows converting back into unstructured bytes in a (semi-)bijective manner
- Guarantees formation of data structure so long as sufficient data is available, regardless of bytes. Other crates (such as `arbitrary`) require certain structure within raw input (such as syntactically valid UTF-8 for strings) to succeed
- Modular entropy conversion scheme--if you would rather have data map in a different way, you can choose what entropy scheme maps data into structures, or even implement your own mapping!