[−][src]Struct bytekey_fix::ser::Serializer
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,
[src]
W: Write,
pub fn new(writer: W) -> Serializer<W>
[src]
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<()>
[src]
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) u64
s 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<()>
[src]
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) i64
s 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> Debug for Serializer<W> where
W: Write,
[src]
W: Write,
impl<'a, W> SerializeMap for &'a mut Serializer<W> where
W: Write,
[src]
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: ?Sized>(&mut self, key: &T) -> Result<()> where
T: Serialize,
[src]
T: Serialize,
fn serialize_value<T: ?Sized>(&mut self, value: &T) -> Result<()> where
T: Serialize,
[src]
T: Serialize,
fn end(self) -> Result<()>
[src]
fn serialize_entry<K, V>(
&mut self,
key: &K,
value: &V
) -> Result<(), Self::Error> where
K: Serialize + ?Sized,
V: Serialize + ?Sized,
[src]
&mut self,
key: &K,
value: &V
) -> Result<(), Self::Error> where
K: Serialize + ?Sized,
V: Serialize + ?Sized,
impl<'a, W> SerializeSeq for &'a mut Serializer<W> where
W: Write,
[src]
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: ?Sized>(&mut self, value: &T) -> Result<()> where
T: Serialize,
[src]
T: Serialize,
fn end(self) -> Result<()>
[src]
impl<'a, W> SerializeStruct for &'a mut Serializer<W> where
W: Write,
[src]
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: ?Sized>(
&mut self,
_key: &'static str,
value: &T
) -> Result<()> where
T: Serialize,
[src]
&mut self,
_key: &'static str,
value: &T
) -> Result<()> where
T: Serialize,
fn end(self) -> Result<()>
[src]
fn skip_field(&mut self, key: &'static str) -> Result<(), Self::Error>
[src]
impl<'a, W> SerializeStructVariant for &'a mut Serializer<W> where
W: Write,
[src]
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: ?Sized>(
&mut self,
_key: &'static str,
value: &T
) -> Result<()> where
T: Serialize,
[src]
&mut self,
_key: &'static str,
value: &T
) -> Result<()> where
T: Serialize,
fn end(self) -> Result<()>
[src]
fn skip_field(&mut self, key: &'static str) -> Result<(), Self::Error>
[src]
impl<'a, W> SerializeTuple for &'a mut Serializer<W> where
W: Write,
[src]
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: ?Sized>(&mut self, value: &T) -> Result<()> where
T: Serialize,
[src]
T: Serialize,
fn end(self) -> Result<()>
[src]
impl<'a, W> SerializeTupleStruct for &'a mut Serializer<W> where
W: Write,
[src]
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: ?Sized>(&mut self, value: &T) -> Result<()> where
T: Serialize,
[src]
T: Serialize,
fn end(self) -> Result<()>
[src]
impl<'a, W> SerializeTupleVariant for &'a mut Serializer<W> where
W: Write,
[src]
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: ?Sized>(&mut self, value: &T) -> Result<()> where
T: Serialize,
[src]
T: Serialize,
fn end(self) -> Result<()>
[src]
impl<'a, W> Serializer for &'a mut Serializer<W> where
W: Write,
[src]
W: Write,
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. Read more
type Error = Error
The error type when some error occurs during serialization.
type SerializeSeq = Self
Type returned from serialize_seq
for serializing the content of the
sequence. Read more
type SerializeTuple = Self
Type returned from serialize_tuple
for serializing the content of
the tuple. Read more
type SerializeTupleStruct = Self
Type returned from serialize_tuple_struct
for serializing the
content of the tuple struct. Read more
type SerializeTupleVariant = Self
Type returned from serialize_tuple_variant
for serializing the
content of the tuple variant. Read more
type SerializeMap = Self
Type returned from serialize_map
for serializing the content of the
map. Read more
type SerializeStruct = Self
Type returned from serialize_struct
for serializing the content of
the struct. Read more
type SerializeStructVariant = Self
Type returned from serialize_struct_variant
for serializing the
content of the struct variant. Read more
fn serialize_bool(self, v: bool) -> Result<()>
[src]
fn serialize_i8(self, v: i8) -> Result<()>
[src]
fn serialize_i16(self, v: i16) -> Result<()>
[src]
fn serialize_i32(self, v: i32) -> Result<()>
[src]
fn serialize_i64(self, v: i64) -> Result<()>
[src]
fn serialize_u8(self, v: u8) -> Result<()>
[src]
fn serialize_u16(self, v: u16) -> Result<()>
[src]
fn serialize_u32(self, v: u32) -> Result<()>
[src]
fn serialize_u64(self, v: u64) -> Result<()>
[src]
fn serialize_f32(self, v: f32) -> Result<()>
[src]
Encode an f32
into sortable bytes.
NaN
s 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<()>
[src]
Encode an f64
into sortable bytes.
NaN
s 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_char(self, v: char) -> Result<()>
[src]
fn serialize_str(self, v: &str) -> Result<()>
[src]
fn serialize_bytes(self, v: &[u8]) -> Result<()>
[src]
fn serialize_none(self) -> Result<()>
[src]
fn serialize_some<T: ?Sized>(self, v: &T) -> Result<()> where
T: Serialize,
[src]
T: Serialize,
fn serialize_unit(self) -> Result<()>
[src]
fn serialize_unit_struct(self, _name: &'static str) -> Result<()>
[src]
fn serialize_unit_variant(
self,
_name: &'static str,
variant_index: u32,
_variant: &'static str
) -> Result<()>
[src]
self,
_name: &'static str,
variant_index: u32,
_variant: &'static str
) -> Result<()>
fn serialize_newtype_struct<T: ?Sized>(
self,
_name: &'static str,
value: &T
) -> Result<()> where
T: Serialize,
[src]
self,
_name: &'static str,
value: &T
) -> Result<()> where
T: Serialize,
fn serialize_newtype_variant<T: ?Sized>(
self,
_name: &'static str,
variant_index: u32,
_variant: &'static str,
value: &T
) -> Result<()> where
T: Serialize,
[src]
self,
_name: &'static str,
variant_index: u32,
_variant: &'static str,
value: &T
) -> Result<()> where
T: Serialize,
fn serialize_seq(self, _len: Option<usize>) -> Result<Self::SerializeSeq>
[src]
fn serialize_tuple(self, _len: usize) -> Result<Self::SerializeTuple>
[src]
fn serialize_tuple_struct(
self,
_name: &'static str,
_len: usize
) -> Result<Self::SerializeTupleStruct>
[src]
self,
_name: &'static str,
_len: usize
) -> Result<Self::SerializeTupleStruct>
fn serialize_tuple_variant(
self,
_name: &'static str,
variant_index: u32,
_variant: &'static str,
_len: usize
) -> Result<Self::SerializeTupleVariant>
[src]
self,
_name: &'static str,
variant_index: u32,
_variant: &'static str,
_len: usize
) -> Result<Self::SerializeTupleVariant>
fn serialize_map(self, _len: Option<usize>) -> Result<Self::SerializeStruct>
[src]
fn serialize_struct(
self,
_name: &'static str,
_len: usize
) -> Result<Self::SerializeStruct>
[src]
self,
_name: &'static str,
_len: usize
) -> Result<Self::SerializeStruct>
fn serialize_struct_variant(
self,
_name: &'static str,
variant_index: u32,
_variant: &'static str,
_len: usize
) -> Result<Self::SerializeStructVariant>
[src]
self,
_name: &'static str,
variant_index: u32,
_variant: &'static str,
_len: usize
) -> Result<Self::SerializeStructVariant>
fn serialize_i128(self, v: i128) -> Result<Self::Ok, Self::Error>
[src]
fn serialize_u128(self, v: u128) -> Result<Self::Ok, Self::Error>
[src]
fn collect_seq<I>(self, iter: I) -> Result<Self::Ok, Self::Error> where
I: IntoIterator,
<I as IntoIterator>::Item: Serialize,
[src]
I: IntoIterator,
<I as IntoIterator>::Item: Serialize,
fn collect_map<K, V, I>(self, iter: I) -> Result<Self::Ok, Self::Error> where
I: IntoIterator<Item = (K, V)>,
K: Serialize,
V: Serialize,
[src]
I: IntoIterator<Item = (K, V)>,
K: Serialize,
V: Serialize,
fn collect_str<T>(self, value: &T) -> Result<Self::Ok, Self::Error> where
T: Display + ?Sized,
[src]
T: Display + ?Sized,
fn is_human_readable(&self) -> bool
[src]
Auto Trait Implementations
impl<W> RefUnwindSafe for Serializer<W> where
W: RefUnwindSafe,
W: RefUnwindSafe,
impl<W> Send for Serializer<W> where
W: Send,
W: Send,
impl<W> Sync for Serializer<W> where
W: Sync,
W: Sync,
impl<W> Unpin for Serializer<W> where
W: Unpin,
W: Unpin,
impl<W> UnwindSafe for Serializer<W> where
W: UnwindSafe,
W: UnwindSafe,
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,