Question: is the serialization format stable?

[stusmall]

I know the library itself isn't 1.0 but is the underlying format stable? If I design an API today that accepts bincode do I know that the format itself won't change?

[stusmall]

Also is there a document that describes the format itself? I'd like the understand how the encoding works. I looked around in the code and in the docs but didn't see anything.

[stusmall]

Someone in IRC helped me find the answer to this question. It isn't yet

#215

[TyOverby]

Yeah, I was going to chat with some people already using bincode and see if making this one last breaking change before 1.0 would be too much to deal with.

I haven't found anyone that would be seriously hurt by this, so I'll probably make the change.

[stusmall]

For the second question, is there a spec or design notes or any other kind of design document I can look at to understand the format? I generally try to understand the underlying format when using binary encoders because it helps guide my structure design.

[TyOverby]

Yeah, I should really write this up at some point and put it in the official docs.

Here's a first draft.

Primitives

• integers: Written to the disk in whichever endian option is chosen at serialization time
• usize/isize: Always written as though they were u64/i64
• str: Writes the length of the string (usize) and then the utf8 content as bytes
• tuples: Writes each field out.

Structs:

The value of each field is written out in order packed down to the nearest byte

Enums

The tag of the enum is written (as a u32), and then the values of each field are written in order.

Common Types

Vec: Writes the length of the vec (usize) and then writes each element
HashMap: Writes the length of the hashmap (usize) and then writes out each tuple (key, value) pair according to the tuple rules.

Summary

Bincode writes the values out in a way that is very close to how the structures are laid out in memory. (the main difference is that bincode packs fields and structs much more aggressively because we don't need to worry about alignment issues).

Because there is no structure information encoded in the payload, bincode requires that both the reader and writer of the data have the exact same struct/enum/etc definitions, so that Serde can generate serialization and deserialization methods that are exactly symmetrical.

What this means for you:

• You can't add/remove/reorder fields in any struct or enum and expect it to work with data generated prior to the change.
• If you choose different encoding options from decoding options, you'll decode garbage.

[stusmall]

Thank you