Struct Serializer 

pub struct Serializer<W>
where
    W: Write,
{ /* private fields */ }

A serializer for a byte format that preserves lexicographic sort order.

The byte format is designed with a few goals:

• Order must be preserved
• Serialized representations should be as compact as possible
• Type information is not serialized with values

Supported Data Types

Unsigned Integers

u8, u16, u32, and u64 are serialized into 1, 2, 4, and 8 bytes of output, respectively. Order is preserved by encoding the bytes in big-endian (most-significant bytes first) format. usize is always serialized as if it were u64.

The Serializer also supports variable-length serialization of unsigned integers via the serialize_var_u64 method. Smaller magnitude values (closer to 0) will encode into fewer bytes.

Signed Integers

i8, i16, i32, and i64 are encoded into 1, 2, 4, and 8 bytes of output, respectively. Order is preserved by taking the bitwise complement of the value, and encoding the resulting bytes in big-endian format. isize is always serialized as if it were i64.

The Serializer also supports variable-length serialization of signed integers via the serialize_var_i64 method. Smaller magnitude values (closer to 0) will encode into fewer bytes.

Floating Point Numbers

f32 and f64 are serialized into 4 and 8 bytes of output, respectively. Order is preserved by encoding the value, or the bitwise complement of the value if negative, into bytes in big-endian format. NAN values will sort after all other values. In general, it is unwise to use IEEE 754 floating point values in keys, because rounding errors are pervasive. It is typically hard or impossible to use an approximate ‘epsilon’ approach when using keys for lookup.

Characters

Characters are serialized into between 1 and 4 bytes of output. The resulting length is equivalent to the result of char::len_utf8.

Booleans

Booleans are serialized into a single byte of output. false values will sort before true values.

Options

An optional wrapper type adds a 1 byte overhead to the wrapped data type. None values will sort before Some values.

Structs, Tuples and Fixed-Size Arrays

Structs and tuples are serialized by serializing their consituent fields in order with no prefix, suffix, or padding bytes.

Enums

Enums are encoded with a u32 variant index tag, plus the consituent fields in the case of an enum-struct.

Sequences, Strings and Maps

Sequences are ordered from the most significant to the least. Strings are serialized into their natural UTF8 representation.

The ordering of sequential elements follows the Ord implementation of slice, that is, from left to write when viewing a Vec printed via the {:?} formatter.

The caveat with these types is that their length must be known before deserialization. This is because the length is not serialized prior to the elements in order to preserve ordering and there is no trivial way to tokenise between sequential elements that 1. does not corrupt ordering and 2. may not confuse tokenisation with following elements of a different type during tuple or struct deserialization. Thus, when deserializing sequences, strings and maps, the process will only be considered complete once the inner reader produces an EOF character.

Implementations

impl<W> Serializer<W>

where W: Write,

pub fn new(writer: W) -> Serializer<W>

Creates a new ordered bytes encoder whose output will be written to the provided writer.

pub fn serialize_var_u64(&mut self, val: u64) -> Result<()>

Encode a u64 into a variable number of bytes.

The variable-length encoding scheme uses between 1 and 9 bytes depending on the value. Smaller magnitude (closer to 0) u64s will encode to fewer bytes.

Encoding

The encoding uses the first 4 bits to store the number of trailing bytes, between 0 and 8. Subsequent bits are the input value in big-endian format with leading 0 bytes removed.

Encoded Size

range	size (bytes)
[0, 24)	1
[24, 212)	2
[212, 220)	3
[220, 228)	4
[228, 236)	5
[236, 244)	6
[244, 252)	7
[252, 260)	8
[260, 264)	9

pub fn serialize_var_i64(&mut self, v: i64) -> Result<()>

Encode an i64 into a variable number of bytes.

The variable-length encoding scheme uses between 1 and 9 bytes depending on the value. Smaller magnitude (closer to 0) i64s will encode to fewer bytes.

Encoding

The encoding uses the first bit to encode the sign: 0 for negative values and 1 for positive values. The following 4 bits store the number of trailing bytes, between 0 and 8. Subsequent bits are the absolute value of the input value in big-endian format with leading 0 bytes removed. If the original value was negative, than 1 is subtracted from the absolute value before encoding. Finally, if the value is negative, all bits except the sign bit are flipped (1s become 0s and 0s become 1s).

Encoded Size

negative range	positive range	size (bytes)
[-23, 0)	[0, 23)	1
[-211, -23)	[23, 211)	2
[-219, -211)	[211, 219)	3
[-227, -219)	[219, 227)	4
[-235, -227)	[227, 235)	5
[-243, -235)	[235, 243)	6
[-251, -243)	[243, 251)	7
[-259, -251)	[251, 259)	8
[-263, -259)	[259, 263)	9

Trait Implementations

impl<W> Debug for Serializer<W>

where W: Write + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, W> SerializeMap for &'a mut Serializer<W>

where W: Write,

type Ok = ()

Must match the Ok type of our Serializer.

type Error = Error

Must match the Error type of our Serializer.

fn serialize_key<T>(&mut self, key: &T) -> Result<()>

where T: ?Sized + Serialize,

Serialize a map key.

fn serialize_value<T>(&mut self, value: &T) -> Result<()>

where T: ?Sized + Serialize,

Serialize a map value.

fn end(self) -> Result<()>

Finish serializing a map.

fn serialize_entry<K, V>( &mut self, key: &K, value: &V, ) -> Result<(), Self::Error>

where K: Serialize + ?Sized, V: Serialize + ?Sized,

Serialize a map entry consisting of a key and a value.

impl<'a, W> SerializeSeq for &'a mut Serializer<W>

where W: Write,

type Ok = ()

Must match the Ok type of our Serializer.

type Error = Error

Must match the Error type of our Serializer.

fn serialize_element<T>(&mut self, value: &T) -> Result<()>

where T: ?Sized + Serialize,

Serialize a sequence element.

fn end(self) -> Result<()>

Finish serializing a sequence.

impl<'a, W> SerializeStruct for &'a mut Serializer<W>

where W: Write,

type Ok = ()

Must match the Ok type of our Serializer.

type Error = Error

Must match the Error type of our Serializer.

fn serialize_field<T>(&mut self, _key: &'static str, value: &T) -> Result<()>

where T: ?Sized + Serialize,

Serialize a struct field.

fn end(self) -> Result<()>

Finish serializing a struct.

fn skip_field(&mut self, key: &'static str) -> Result<(), Self::Error>

Indicate that a struct field has been skipped.

impl<'a, W> SerializeStructVariant for &'a mut Serializer<W>

where W: Write,

type Ok = ()

Must match the Ok type of our Serializer.

type Error = Error

Must match the Error type of our Serializer.

fn serialize_field<T>(&mut self, _key: &'static str, value: &T) -> Result<()>

where T: ?Sized + Serialize,

Serialize a struct variant field.

fn end(self) -> Result<()>

Finish serializing a struct variant.

fn skip_field(&mut self, key: &'static str) -> Result<(), Self::Error>

Indicate that a struct variant field has been skipped.

impl<'a, W> SerializeTuple for &'a mut Serializer<W>

where W: Write,

type Ok = ()

Must match the Ok type of our Serializer.

type Error = Error

Must match the Error type of our Serializer.

fn serialize_element<T>(&mut self, value: &T) -> Result<()>

where T: ?Sized + Serialize,

Serialize a tuple element.

fn end(self) -> Result<()>

Finish serializing a tuple.

impl<'a, W> SerializeTupleStruct for &'a mut Serializer<W>

where W: Write,

type Ok = ()

Must match the Ok type of our Serializer.

type Error = Error

Must match the Error type of our Serializer.

fn serialize_field<T>(&mut self, value: &T) -> Result<()>

where T: ?Sized + Serialize,

Serialize a tuple struct field.

fn end(self) -> Result<()>

Finish serializing a tuple struct.

impl<'a, W> SerializeTupleVariant for &'a mut Serializer<W>

where W: Write,

type Ok = ()

Must match the Ok type of our Serializer.

type Error = Error

Must match the Error type of our Serializer.

fn serialize_field<T>(&mut self, value: &T) -> Result<()>

where T: ?Sized + Serialize,

Serialize a tuple variant field.

fn end(self) -> Result<()>

Finish serializing a tuple variant.

impl<'a, W> Serializer for &'a mut Serializer<W>

where W: Write,

fn serialize_f32(self, v: f32) -> Result<()>

Encode an f32 into sortable bytes.

NaNs will sort greater than positive infinity. -0.0 will sort directly before +0.0.

See Hacker’s Delight 2nd Edition Section 17-3.

fn serialize_f64(self, v: f64) -> Result<()>

Encode an f64 into sortable bytes.

NaNs will sort greater than positive infinity. -0.0 will sort directly before +0.0.

See Hacker’s Delight 2nd Edition Section 17-3.

type Ok = ()

The output type produced by this Serializer during successful serialization. Most serializers that produce text or binary output should set Ok = () and serialize into an io::Write or buffer contained within the Serializer instance. Serializers that build in-memory data structures may be simplified by using Ok to propagate the data structure around.

type Error = Error

The error type when some error occurs during serialization.

type SerializeSeq = &'a mut Serializer<W>

Type returned from serialize_seq for serializing the content of the sequence.

type SerializeTuple = &'a mut Serializer<W>

Type returned from serialize_tuple for serializing the content of the tuple.

type SerializeTupleStruct = &'a mut Serializer<W>

Type returned from serialize_tuple_struct for serializing the content of the tuple struct.

type SerializeTupleVariant = &'a mut Serializer<W>

Type returned from serialize_tuple_variant for serializing the content of the tuple variant.

type SerializeMap = &'a mut Serializer<W>

Type returned from serialize_map for serializing the content of the map.

type SerializeStruct = &'a mut Serializer<W>

Type returned from serialize_struct for serializing the content of the struct.

type SerializeStructVariant = &'a mut Serializer<W>

Type returned from serialize_struct_variant for serializing the content of the struct variant.

fn serialize_bool(self, v: bool) -> Result<()>

Serialize a bool value.

fn serialize_i8(self, v: i8) -> Result<()>

Serialize an i8 value.

fn serialize_i16(self, v: i16) -> Result<()>

Serialize an i16 value.

fn serialize_i32(self, v: i32) -> Result<()>

Serialize an i32 value.

fn serialize_i64(self, v: i64) -> Result<()>

Serialize an i64 value.

fn serialize_u8(self, v: u8) -> Result<()>

Serialize a u8 value.

fn serialize_u16(self, v: u16) -> Result<()>

Serialize a u16 value.

fn serialize_u32(self, v: u32) -> Result<()>

Serialize a u32 value.

fn serialize_u64(self, v: u64) -> Result<()>

Serialize a u64 value.

fn serialize_char(self, v: char) -> Result<()>

Serialize a character.

fn serialize_str(self, v: &str) -> Result<()>

Serialize a &str.

fn serialize_bytes(self, v: &[u8]) -> Result<()>

Serialize a chunk of raw byte data.

fn serialize_none(self) -> Result<()>

Serialize a None value.

fn serialize_some<T>(self, v: &T) -> Result<()>

where T: ?Sized + Serialize,

Serialize a Some(T) value.

fn serialize_unit(self) -> Result<()>

Serialize a () value.

fn serialize_unit_struct(self, _name: &'static str) -> Result<()>

Serialize a unit struct like struct Unit or PhantomData<T>.

fn serialize_unit_variant( self, _name: &'static str, variant_index: u32, _variant: &'static str, ) -> Result<()>

Serialize a unit variant like E::A in enum E { A, B }.

fn serialize_newtype_struct<T>( self, _name: &'static str, value: &T, ) -> Result<()>

where T: ?Sized + Serialize,

Serialize a newtype struct like struct Millimeters(u8).

fn serialize_newtype_variant<T>( self, _name: &'static str, variant_index: u32, _variant: &'static str, value: &T, ) -> Result<()>

where T: ?Sized + Serialize,

Serialize a newtype variant like E::N in enum E { N(u8) }.

fn serialize_seq(self, _len: Option<usize>) -> Result<Self::SerializeSeq>

Begin to serialize a variably sized sequence. This call must be followed by zero or more calls to serialize_element, then a call to end.

fn serialize_tuple(self, _len: usize) -> Result<Self::SerializeTuple>

Begin to serialize a statically sized sequence whose length will be known at deserialization time without looking at the serialized data. This call must be followed by zero or more calls to serialize_element, then a call to end.

fn serialize_tuple_struct( self, _name: &'static str, _len: usize, ) -> Result<Self::SerializeTupleStruct>

Begin to serialize a tuple struct like struct Rgb(u8, u8, u8). This call must be followed by zero or more calls to serialize_field, then a call to end.

fn serialize_tuple_variant( self, _name: &'static str, variant_index: u32, _variant: &'static str, _len: usize, ) -> Result<Self::SerializeTupleVariant>

Begin to serialize a tuple variant like E::T in enum E { T(u8, u8) }. This call must be followed by zero or more calls to serialize_field, then a call to end.

fn serialize_map(self, _len: Option<usize>) -> Result<Self::SerializeStruct>

Begin to serialize a map. This call must be followed by zero or more calls to serialize_key and serialize_value, then a call to end.

fn serialize_struct( self, _name: &'static str, _len: usize, ) -> Result<Self::SerializeStruct>

Begin to serialize a struct like struct Rgb { r: u8, g: u8, b: u8 }. This call must be followed by zero or more calls to serialize_field, then a call to end.

fn serialize_struct_variant( self, _name: &'static str, variant_index: u32, _variant: &'static str, _len: usize, ) -> Result<Self::SerializeStructVariant>

Begin to serialize a struct variant like E::S in enum E { S { r: u8, g: u8, b: u8 } }. This call must be followed by zero or more calls to serialize_field, then a call to end.

fn serialize_i128(self, v: i128) -> Result<Self::Ok, Self::Error>

Serialize an i128 value.

fn serialize_u128(self, v: u128) -> Result<Self::Ok, Self::Error>

Serialize a u128 value.

fn collect_seq<I>(self, iter: I) -> Result<Self::Ok, Self::Error>

where I: IntoIterator, <I as IntoIterator>::Item: Serialize,

Collect an iterator as a sequence.

fn collect_map<K, V, I>(self, iter: I) -> Result<Self::Ok, Self::Error>

where K: Serialize, V: Serialize, I: IntoIterator<Item = (K, V)>,

Collect an iterator as a map.

fn collect_str<T>(self, value: &T) -> Result<Self::Ok, Self::Error>

where T: Display + ?Sized,

Serialize a string produced by an implementation of Display.

fn is_human_readable(&self) -> bool

Determine whether Serialize implementations should serialize in human-readable form.