# transient-0

transient-0 is a binary encoding of hobgoblin data is for transient data where
forwards and backwards compatibility is not required, such as IPC between
different instances of the same program.

The encoder and decoder must use the same version of hobgoblin and the same data
definitions for decoding to succeed.

transient-0 does not support:
* Compatibility between different versions of hobgoblin. The exact encoding is
  an implementation detail that may change between any two versions of
  hobgoblin.
* Compatibility between different data definitions. For instance, if a field is
  added to a struct, there is no guarantee that data encoded before the field
  was added can be decoded using the new data definition.

## Encoding

This describes the current encoding of transient-0.

* `Bool`: a one-byte integer where true and false are represented by
  1 and 0 respectively.

* `Int32`: a four-byte little endian integer.

* `Int64`: an eight-byte little endian integer.

* `String`: the length of the UTF-8 encoding of the string written as per
  `Int64`, followed by that UTF-8 encoding.

* `Option[T]`: if `none`, encoded as per `false`, otherwise encoded as per
  `true` followed by the encoding of the value as per `T`.

* `List[T]`: the number of elements in the list encoded as per `Int64`, followed
  by each of the elements in the list encoded as per `T`.

* `Shared[T]`: the first time a value is encountered, encoded as a unique ID as
  per `Int64` followed by the encoding of the value itself as per `T`.

  Any subsequent times that value is encountered, encoded as the unique ID as
  per `Int64`.

  Shared values should be assigned incremental IDs starting at zero. That is,
  the first shared value should have an ID of 0, the second shared value should
  have an ID of 1, and so on.

* A struct is encoded by encoding each of its fields in definition order.

* An enum is encoded by the index of the variant as per `Int32`.

* A sum is encoded by the index of the variant as per `Int32` followed by the
  encoding as per the type of the variant.