This crate provides generic data encoding functions.
Encoding and decoding functions with and without allocation are
provided for common bases. Those functions are instantiated from
generic functions using a base interface described in module
base. The generic encoding and decoding
functions are defined in the
decode modules respectively.
use data_encoding::hex; use data_encoding::base64; assert_eq!(hex::encode(b"some raw data"), "736F6D65207261772064617461"); assert_eq!(base64::decode(b"c29tZSByYXcgZGF0YQ==").unwrap(), b"some raw data");
A more involved example is available in the
It is similar to the
base64 GNU program, but it works for all
common bases and also for custom bases defined at runtime.
This crate is meant to provide strong properties. The encoding and decoding functions satisfy the following properties:
- They are deterministic: their output only depends on their input.
- They have no side-effects: they do not modify a hidden mutable state.
- They never panic, although the decoding function may return a decoding error on invalid input.
- They are inverse of each other:
- For all
data: Vec<u8>, we have
decode(encode(&data).as_bytes()) == Ok(data).
- For all
repr: String, if there is
data: Vec<u8>such that
decode(repr.as_bytes()) == Ok(data), then
encode(&data) == repr.
- For all
This last property, that
decode are inverse of each
other, is usually not satisfied by common
implementations, like the
rustc-serialize crate or the
GNU program. This is a matter of choice, and this crate has made
the choice to guarantee canonical encoding as described by
section 3.5 of
Since the RFC specifies
encode on all inputs and
decode on all
encode outputs, the differences between implementations
come from the
decode function which may be more or less
permissive. In this crate, the
decode function rejects all
inputs that are not a possible output of the
encode function. A
pre-treatment of the input has to be done to be more permissive
(see the example of the
examples directory). Here are some
concrete examples of decoding differences between this crate, the
rustc-serialize crate, and the
base64 GNU program:
We can summarize these discrepancies as follows:
|Non-significant bits before padding may be non-null||No||Yes||Yes|
|Non-alphabet ignored characters||None||
|Non-alphabet translated characters||None||
|Padding is optional||No||Yes||No|
This crate may provide wrappers to accept these discrepancies in a generic way at some point in the future.
This crate is meant to be efficient. It has comparable performance
rustc-serialize crate and the
base64 GNU program.