waalge/aiken
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: start decoding docs and fix wording for encode docs

Browse Source
This commit is contained in:
Kasey White
2022-06-29 16:28:50 -04:00
committed by Kasey White
parent 3aaec0936d
commit ac3ab5b47a
3 changed files with 81 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
crates/flat/src/encode/encoder.rs
View File

@@ -31,7 +31,8 @@ impl Encoder {
Ok(self)
}
/// Encode one unsined byte.
/// Encode 1 unsigned byte.
/// Uses the next 8 bits in the buffer, can be byte aligned or byte unaligned
pub fn u8(&mut self, x: u8) -> Result<&mut Self, Error> {
if self.used_bits == 0 {
@@ -44,8 +45,9 @@ impl Encoder {
Ok(self)
}
/// Encode a `bool` value.
/// Uses the next bit in the buffer to encode this information.
/// Encode a `bool` value. This is byte alignment agnostic.
/// Uses the next unused bit in the current byte to encode this information.
/// One for true and Zero for false
pub fn bool(&mut self, x: bool) -> &mut Self {
if x {
self.one();
@@ -55,10 +57,12 @@ impl Encoder {
self
}
/// Encode a byte array.
/// Uses filler to byte align the buffer, then writes byte array length up to 255.
/// Following that it writes the next 255 bytes from the array.
/// After reaching the end of the buffer we write a 0 byte. Only write 0 byte if the byte array is empty.
/// We repeat writing length up to 255 and the next 255 bytes until we reach the end of the byte array.
/// After reaching the end of the byte array we write a 0 byte. Only write 0 byte if the byte array is empty.
pub fn bytes(&mut self, x: &[u8]) -> Result<&mut Self, Error> {
// use filler to write current buffer so bits used gets reset
self.filler();
@@ -66,9 +70,10 @@ impl Encoder {
self.byte_array(x)
}
/// Encode a byte array in a byte aligned buffer. Throws exception if any bits for the current buffer byte were used.
/// writes byte array length up to 255
/// following that it writes the next 255 bytes from the array.
/// Encode a byte array in a byte aligned buffer. Throws exception if any bits for the current byte were used.
/// Writes byte array length up to 255
/// Following that it writes the next 255 bytes from the array.
/// We repeat writing length up to 255 and the next 255 bytes until we reach the end of the byte array.
/// After reaching the end of the buffer we write a 0 byte. Only write 0 if the byte array is empty.
pub fn byte_array(&mut self, arr: &[u8]) -> Result<&mut Self, Error> {
if self.used_bits != 0 {
@@ -80,10 +85,11 @@ impl Encoder {
Ok(self)
}
/// Encode a integer of any size.
/// First we use zigzag to double the number and encode the negative sign as the least significant bit.
/// Encode an integer of any size.
/// This is byte alignment agnostic.
/// First we use zigzag once to double the number and encode the negative sign as the least significant bit.
/// Next we encode the 7 least significant bits of the unsigned integer. If the number is greater than
/// 127 we encode a leading one followed by repeating the above for the next 7 bits and so on.
/// 127 we encode a leading 1 followed by repeating the encoding above for the next 7 bits and so on.
pub fn integer(&mut self, i: isize) -> &mut Self {
let i = zigzag::to_usize(i);
@@ -93,8 +99,9 @@ impl Encoder {
}
/// Encode a char of 32 bits.
/// This is byte alignment agnostic.
/// We encode the 7 least significant bits of the unsigned byte. If the char value is greater than
/// 127 we encode a leading one followed by repeating the above for the next 7 bits and so on.
/// 127 we encode a leading 1 followed by repeating the above for the next 7 bits and so on.
pub fn char(&mut self, c: char) -> &mut Self {
self.word(c as usize);
@@ -112,8 +119,9 @@ impl Encoder {
self
}
/// Encode a string.
/// Convert to byte array and then use byte array coding.
/// Convert to byte array and then use byte array encoding.
/// Uses filler to byte align the buffer, then writes byte array length up to 255.
/// Following that it writes the next 255 bytes from the array.
/// After reaching the end of the buffer we write a 0 byte. Only write 0 byte if the byte array is empty.
@@ -121,9 +129,10 @@ impl Encoder {
self.bytes(s.as_bytes())
}
/// Encode a unsigned integer of any size
/// Encode a unsigned integer of any size.
/// This is byte alignment agnostic.
/// We encode the 7 least significant bits of the unsigned byte. If the char value is greater than
/// 127 we encode a leading one followed by repeating the above for the next 7 bits and so on.
/// 127 we encode a leading 1 followed by repeating the above for the next 7 bits and so on.
pub fn word(&mut self, c: usize) -> &mut Self {
let mut d = c;
loop {
@@ -144,8 +153,9 @@ impl Encoder {
}
/// Encode a list of bytes with a function
/// If there are bytes in a list then write one bit followed by the functions encoding.
/// After the last item write a zero bit. If the list is empty only encode a zero bit.
/// This is byte alignment agnostic.
/// If there are bytes in a list then write 1 bit followed by the functions encoding.
/// After the last item write a 0 bit. If the list is empty only encode a 0 bit.
pub fn encode_list_with(
&mut self,
list: Vec<u8>,
@@ -161,6 +171,11 @@ impl Encoder {
Ok(self)
}
/// Encodes up to 8 bits of information and is byte alignment agnostic.
/// Uses unused bits in the current byte to write out the passed in byte value.
/// Overflows to the most significant digits of the next byte if number of bits to use is greater than unused bits.
/// Expects that number of bits to use is greater than or equal to required bits by the value.
/// The param num_bits is i64 to match unused_bits type.
pub fn bits(&mut self, num_bits: i64, val: u8) -> &mut Self {
match (num_bits, val) {
(1, 0) => self.zero(),
@@ -206,7 +221,7 @@ impl Encoder {
self
}
/// A filler amount of end 0s followed by a 1 at the end of a byte.
/// A filler amount of end 0's followed by a 1 at the end of a byte.
/// Used to byte align the buffer by padding out the rest of the byte.
pub(crate) fn filler(&mut self) -> &mut Self {
self.current_byte |= 1;
@@ -215,8 +230,8 @@ impl Encoder {
self
}
/// Write a zero bit into the buffer.
/// Write out buffer if last used bit in a byte.
/// Write a 0 bit into the current byte.
/// Write out to buffer if last used bit in the current byte.
fn zero(&mut self) {
if self.used_bits == 7 {
self.next_word();
@@ -225,8 +240,8 @@ impl Encoder {
}
}
/// Write a one bit into the buffer.
/// If last used bit in a byte then make last bit one and write out buffer.
/// Write a 1 bit into the current byte.
/// Write out to buffer if last used bit in the current byte.
fn one(&mut self) {
if self.used_bits == 7 {
self.current_byte |= 1;
@@ -237,7 +252,7 @@ impl Encoder {
}
}
/// Write out byte regardless of current buffer alignment.
/// Write most signifcant bits in remaining unused bits for current byte,
/// Write most signifcant bits in remaining unused bits for the current byte,
/// then write out the remaining bits at the beginning of the next byte.
fn byte_unaligned(&mut self, x: u8) {
let x_shift = self.current_byte | (x >> self.used_bits);
@@ -258,6 +273,7 @@ impl Encoder {
/// Writes byte array length up to 255
/// Following that it writes the next 255 bytes from the array.
/// After reaching the end of the buffer we write a 0 byte. Only write 0 if the byte array is empty.
/// This is byte alignment agnostic.
fn write_blk(&mut self, arr: &[u8], src_ptr: &mut usize) {
let src_len = arr.len() - *src_ptr;
let blk_len = src_len.min(255);