Corncobs

https://docs.rs/corncobs
Admin
A Rust crate providing Consistent Overhead Byte Stuffing (COBS) encoding/decoding for embedded...
Tokens:13,327
Snippets:146
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Default Implementation for DState

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Implements the Default trait for the DState enum, setting the initial state to Start.

```rust
impl Default for DState {
    fn default() -> Self {
        Self::Start
    }
}
```

--------------------------------

### encode_buf

Source: https://docs.rs/corncobs/0.1.4/corncobs/fn.encode_buf.html

Encodes the message `bytes` into the buffer `output`. Returns the number of bytes used in `output`, which also happens to be the index of the first zero byte. Bytes in `output` after the part that gets used are left unchanged. `output` must be large enough to receive the encoded form, which is `max_encoded_len(bytes.len())` worst-case.

```APIDOC
## Function encode_buf

### Description
Encodes the message `bytes` into the buffer `output`. Returns the number of bytes used in `output`, which also happens to be the index of the first zero byte. Bytes in `output` after the part that gets used are left unchanged. `output` must be large enough to receive the encoded form, which is `max_encoded_len(bytes.len())` worst-case.

### Signature
```rust
pub fn encode_buf(bytes: &[u8], output: &mut [u8]) -> usize
```

### Panics
If `output` is too small to contain the encoded form of `input`.
```

--------------------------------

### Encode Bytes into Buffer

Source: https://docs.rs/corncobs/0.1.4/corncobs/fn.encode_buf.html

Encodes the message `bytes` into the buffer `output`. Returns the number of bytes used in `output`, which also happens to be the index of the first zero byte. Bytes in `output` after the part that gets used are left unchanged. `output` must be large enough to receive the encoded form, which is `max_encoded_len(bytes.len())` worst-case.

```rust
pub fn encode_buf(bytes: &[u8], output: &mut [u8]) -> usize
```

--------------------------------

### COBS Decoder State Enum

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Defines the possible states for the COBS decoding state machine, including Start, Tween, Literal, and Done.

```rust
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum DState {
    Start,
    Tween(bool),
    Literal(u8, bool),
    Done,
}
```

--------------------------------

### GetTypeId Method

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Gets the `TypeId` of the current type. This is part of the `Any` trait implementation and is useful for dynamic type checking.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### CloneToUninit Method (Nightly)

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Performs copy-assignment from self to an uninitialized destination. This is an experimental nightly-only API for efficient copying.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### Default Implementation for Decoder

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Provides a default value for the Decoder, creating a new decoder instance ready for use. This is the standard way to initialize the decoder.

```rust
fn default() -> Decoder
```

--------------------------------

### Decoder Methods

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Provides documentation for the core methods of the Decoder struct, allowing users to advance the decoding process and check its completion status.

```APIDOC
## Decoder

### `advance(&mut self, byte: u8) -> Result<DecodeStatus, CobsError>`

**Description**: Advances the COBS decoding process with the next byte.

**Method**: `advance`

**Parameters**:
* `byte` (u8) - The next byte to process.

**Returns**: A `Result` containing `DecodeStatus` on success or `CobsError` on failure.

### `is_done(&self) -> bool`

**Description**: Checks if the COBS decoding process is complete.

**Method**: `is_done`

**Returns**: `true` if decoding is complete, `false` otherwise.
```

--------------------------------

### Using max_encoded_len to size an array

Source: https://docs.rs/corncobs/0.1.4/corncobs/fn.max_encoded_len.html

Demonstrates how to use `max_encoded_len` to pre-allocate a buffer for encoded data. This is useful when the exact encoded size is not known at compile time but an upper bound is sufficient.

```rust
const MSG_SIZE: usize = 254;
// Worst-case input message: no zeroes to exploit.
let mut msg = [0xFF; MSG_SIZE];
// This will still be enough space!
let mut encoded = [0; corncobs::max_encoded_len(MSG_SIZE)];

let len = corncobs::encode_buf(&msg, &mut encoded);
assert_eq!(len, encoded.len());
```

--------------------------------

### Clone Decoder Implementation

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Provides a way to create a duplicate of the Decoder instance. This is useful for scenarios where the decoding state needs to be preserved or branched.

```rust
fn clone(&self) -> Decoder
```

--------------------------------

### COBS take_run Function - Empty Input

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Tests the take_run function with an empty byte slice, expecting an empty slice and no run.

```rust
    #[test]
    fn take_run_empty() {
        assert_eq!(take_run(&[]), (&[][..], None));
    }
```

--------------------------------

### PartialEq Implementation for Decoder

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Tests for equality between two Decoder instances. This is used by the `==` operator to compare decoder states.

```rust
fn eq(&self, other: &Decoder) -> bool
```

--------------------------------

### COBS take_run Function - Zero Byte Input

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Tests the take_run function with a single zero byte, expecting no leading slice and a zero run.

```rust
    #[test]
    fn take_run_zero() {
        assert_eq!(take_run(&[0]), (&[][..], Some(&[][..])));
    }
```

--------------------------------

### Clone From Decoder Implementation

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Performs copy-assignment from a source Decoder to the current one. This is an efficient way to update the decoder's state.

```rust
fn clone_from(&mut self, source: &Self)
```

--------------------------------

### Debug Implementation for Decoder

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Formats the Decoder for debugging purposes using the provided formatter. This allows inspecting the decoder's state during development.

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

--------------------------------

### Into Implementation

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Calls `U::from(self)` to perform a conversion. This is part of the `Into` trait, which is often used in conjunction with `From`.

```rust
fn into(self) -> U
```

--------------------------------

### From Implementation

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Returns the argument unchanged. This is a generic implementation of the `From` trait.

```rust
fn from(t: T) -> T
```

--------------------------------

### COBS take_run Function - Single Byte Input

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Tests the take_run function with a single non-zero byte, expecting that byte as the leading slice and no run.

```rust
    #[test]
    fn take_run_one() {
        assert_eq!(take_run(&[1]), (&[1][..], None));
    }
```

--------------------------------

### EncodeState next method for COBS encoding

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

The `next` method transitions the `EncodeState` to the next state, emitting a byte and potentially returning a new state. It handles initial states, subsequent runs, and the final end state.

```rust
impl<'a> EncodeState<'a> {
    pub fn next(self) -> (u8, Option<Self>) {
        match self {
            Self::Begin(bytes) => {
                let (run, rest) = take_run(bytes);
                let b = encode_len(run.len());
                (b, Some(Self::next_run_state(run, rest)))
            }
            Self::Run(b, run, rest) => {
                (b, Some(Self::next_run_state(run, rest)))
            }
            Self::End => (0, None),
        }
    }

    fn next_run_state(run: &'a [u8], rest: Option<&'a [u8]>) -> Self {
        if let Some((&b, run)) = run.split_first() {
            // There's data in the run, we must drain it before starting
            // a new one.
            Self::Run(b, run, rest)
        } else {
            Self::new_run_state(rest)
        }
    }

    fn new_run_state(rest: Option<&'a [u8]>) -> Self {
        if let Some(rest) = rest {
            Self::Begin(rest)
        } else {
            Self::End
        }
    }
}
```

--------------------------------

### Decoder Trait Implementations

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Details the implementations of standard Rust traits for the Decoder struct, such as Clone, Debug, Default, and PartialEq.

```APIDOC
## Decoder Trait Implementations

### `impl Clone for Decoder`

#### `clone(&self) -> Decoder`

**Description**: Returns a duplicate of the `Decoder` value.

### `impl Debug for Decoder`

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

**Description**: Formats the `Decoder` value using the given formatter.

### `impl Default for Decoder`

#### `default() -> Decoder`

**Description**: Returns the default value for the `Decoder` type.

### `impl PartialEq for Decoder`

#### `eq(&self, other: &Decoder) -> bool`

**Description**: Tests if `self` and `other` `Decoder` values are equal.

#### `ne(&self, other: &Rhs) -> bool`

**Description**: Tests if `self` and `other` `Decoder` values are not equal.
```

--------------------------------

### Ne Implementation for Decoder

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Tests for inequality between two Decoder instances. This is used by the `!=` operator.

```rust
fn ne(&self, other: &Rhs) -> bool
```

--------------------------------

### encode_buf

Source: https://docs.rs/corncobs

Encodes the message `bytes` into the buffer `output`. Returns the number of bytes used in `output`, which also happens to be the index of the first zero byte.

```APIDOC
## encode_buf

### Description
Encodes the message `bytes` into the buffer `output`. Returns the number of bytes used in `output`, which also happens to be the index of the first zero byte.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **bytes_used** (usize) - The number of bytes used in `output`, which is also the index of the first zero byte.

### Response Example
None
```

--------------------------------

### Stateful COBS Decoding with Decoder

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Manages the state of a COBS decoding process byte by byte. Handles transitions between literal and tween states.

```rust
#[derive(Clone, Debug, PartialEq, Eq, Default)]
pub struct Decoder {
    state: DState,
}

impl Decoder {
    pub fn advance(&mut self, byte: u8) -> Result<DecodeStatus, CobsError> {
        match self.state {
            DState::Start | DState::Tween(true) => {
                if let Some(count) = byte.checked_sub(1) {
                    if let Some(count2) = count.checked_sub(1) {
                        self.state = DState::Literal(count2, byte == 0xFF);
                    } else {
                        self.state = DState::Tween(false);
                    }
                    Ok(DecodeStatus::Pending)
                } else {
                    self.state = DState::Done;
                    Ok(DecodeStatus::Done)
                }
            }
            DState::Tween(false) => {
                if let Some(count) = byte.checked_sub(1) {
                    if let Some(count2) = count.checked_sub(1) {
                        self.state = DState::Literal(count2, byte == 0xFF);
                    } else {
                        self.state = DState::Tween(false);
                    }
                    Ok(DecodeStatus::Append(ZERO))
                } else {
                    self.state = DState::Done;
                    Ok(DecodeStatus::Done)
                }
            }
            DState::Literal(mut count, mut is_ff) => {
                if count > 0 {
                    count -= 1;
                    self.state = DState::Literal(count, is_ff || byte == 0xFF);
                    Ok(DecodeStatus::Append(byte))
                } else {
                    self.state = DState::Tween(byte == 0xFF);
                    Ok(DecodeStatus::Append(ZERO))
                }
            }
            DState::Done => Ok(DecodeStatus::Done),
        }
    }
}
```

--------------------------------

### take_run function for COBS encoding

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

This function extracts a run of bytes from the input slice, respecting `MAX_RUN` and stopping at the first zero byte. It returns the run and the rest of the slice, handling potential trailing zeros.

```rust
fn take_run(bytes: &[u8]) -> (&[u8], Option<&[u8]>) {
    // The run will be no longer than
    // - All the bytes, or
    // - The fixed MAX_RUN constant.
    let max_len = usize::min(bytes.len(), MAX_RUN);
    // It may be shorter than that if there's a zero. Scan the prefix for a zero
    // and truncate if found.
    let run_len = bytes.iter()
        .take(max_len)
        .position(|&b| b == ZERO)
        .unwrap_or(max_len);

    let (run, rest) = bytes.split_at(run_len);
    let rest = if rest.is_empty() {
        None
    } else if run_len == MAX_RUN {
        // Run does not imply a zero, don't omit one from the output if present.
        Some(rest)
    } else {
        debug_assert_eq!(rest[0], 0);
        // Drop the zero.
        Some(&rest[1..])
    };
    (run, rest)
}
```

--------------------------------

### TryInto Implementation

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Performs a fallible conversion from type `T` to type `U`. This is part of the `TryInto` trait, the reciprocal of `TryFrom`.

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### TryFrom Implementation

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Performs a fallible conversion from type `U` to type `T`. This is part of the `TryFrom` trait, used when conversion might fail.

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

--------------------------------

### decode_buf

Source: https://docs.rs/corncobs/0.1.4/corncobs/index.html

Decodes input data from a byte slice into an output buffer. It returns the number of bytes that were written into the output buffer.

```APIDOC
## decode_buf

### Description
Decodes input from `bytes` into `output` starting at index 0. Returns the number of bytes used in `output`.

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **bytes_used** (usize) - The number of bytes used in the output buffer.

#### Response Example
None
```

--------------------------------

### decode_buf

Source: https://docs.rs/corncobs/0.1.4/index.html

Decodes input data from a byte slice into an output buffer. It returns the number of bytes successfully written into the output buffer.

```APIDOC
## decode_buf

### Description
Decodes input from `bytes` into `output` starting at index 0. Returns the number of bytes used in `output`.

### Function Signature
`fn decode_buf(bytes: &[u8], output: &mut [u8]) -> usize`

### Parameters
- `bytes` (&[u8]): The input byte slice containing the COBS encoded data.
- `output` (&mut [u8]): The mutable byte slice where the decoded data will be written.

### Returns
`usize`: The number of bytes written into the `output` buffer.
```

--------------------------------

### COBS Encoding Loop

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Processes a byte slice, splitting it by zero bytes and encoding runs up to MAX_RUN. Handles the logic for previous maximal runs and splits input into manageable chunks for COBS encoding.

```rust
for mut run in bytes.split(|&b| b == ZERO) {
    // If the last run we encoded was maximal length, we need to encode an
    // explicit zero between it and our current `run`.
    if prev_run_was_maximal {
        let (chunk, new_output) = output.split_at_mut(1);
        chunk[0] = encode_len(0);
        output = new_output;
    }

    // We can only encode a run of up to `MAX_RUN` bytes in COBS. This may
    // require us to split `run` into multiple output chunks -- in the
    // extreme case, if the input contains no zeroes, we'll process all of
    // it here.
    loop {
        let chunk_len = usize::min(run.len(), MAX_RUN);
        let (chunk, new_output) = output.split_at_mut(chunk_len + 1);
        let (run_prefix, new_run) = run.split_at(chunk_len);
        chunk[1..].copy_from_slice(run_prefix);
        chunk[0] = encode_len(chunk_len);

        output = new_output;
        run = new_run;
        prev_run_was_maximal = chunk_len == MAX_RUN;

        // We test this condition here, rather than as a `while` loop,
        // because we want to process empty runs once.
        if run.is_empty() {
            break;
        }
    }
}
// We've been shortening the output as we go by lopping off prefixes, so our
// terminating byte goes at the new start:
output[0] = 0;
orig_size - (output.len() - 1)
}
```

--------------------------------

### decode_buf Function Signature

Source: https://docs.rs/corncobs/0.1.4/corncobs/fn.decode_buf.html

This is the function signature for decode_buf. It takes a byte slice as input and a mutable byte slice for output, returning a Result indicating success with the number of bytes written or a CobsError.

```rust
pub fn decode_buf(bytes: &[u8], output: &mut [u8]) -> Result<usize, CobsError>
```

--------------------------------

### ZERO Constant

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

The termination byte used by `corncobs`. This constant is used for clarity in the implementation and its value (0) is assumed by the encoding/decoding logic.

```APIDOC
## ZERO Constant

### Description
The termination byte used by `corncobs`. Yes, it's a bit silly to have this as a constant -- but the implementation is careful to use this named constant whenever it is talking about the termination byte, for clarity.

The value of this (`0`) is assumed by the implementation and can't easily be changed.

### Type
u8

### Value
`0`
```

--------------------------------

### COBS Decoder State Machine Logic

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Handles the logic for processing bytes within the COBS decoding state machine. It transitions between states like Literal, Tween, and Done based on input bytes and remaining counts.

```rust
            DState::Literal(n, omit_zero) => {
                if byte == ZERO {
                    Err(CobsError::Corrupt)
                } else {
                    if let Some(next_n) = n.checked_sub(1) {
                        self.state = DState::Literal(next_n, omit_zero);
                    } else {
                        self.state = DState::Tween(omit_zero);
                    }

                    Ok(DecodeStatus::Append(byte))
                }
            }
            DState::Done => panic!(),
```

--------------------------------

### ZERO Constant Definition

Source: https://docs.rs/corncobs/0.1.4/corncobs/constant.ZERO.html

Defines the public constant ZERO as a u8 with a value of 0. This constant is used as the termination byte in the corncobs implementation.

```rust
pub const ZERO: u8 = 0;
```

--------------------------------

### encode_iter Function Signature

Source: https://docs.rs/corncobs/0.1.4/corncobs/fn.encode_iter.html

This is the function signature for `encode_iter`. It takes a byte slice and returns an iterator that yields encoded bytes.

```rust
pub fn encode_iter(bytes: &[u8]) -> impl Iterator<Item = u8> + '_

```

--------------------------------

### Borrow Method

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Immutably borrows the value. This is part of the `Borrow` trait implementation, allowing access to the underlying data without taking ownership.

```rust
fn borrow(&self) -> &T
```

--------------------------------

### Check if COBS Decoder is Done

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Provides a method to check if the COBS decoding process has reached its final state.

```rust
    pub fn is_done(&self) -> bool {
        self.state == DState::Done
    }
}
```

--------------------------------

### decode_in_place Function Signature

Source: https://docs.rs/corncobs/0.1.4/corncobs/fn.decode_in_place.html

This is the function signature for decode_in_place. It takes a mutable byte slice and returns a Result indicating the number of decoded bytes or a CobsError.

```rust
pub fn decode_in_place(bytes: &mut [u8]) -> Result<usize, CobsError>
```

--------------------------------

### encode

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Encodes a byte slice into a mutable vector. This function is a convenience wrapper for cases where the `std` library is available, handling buffer resizing and calling the core encoding logic.

```APIDOC
## encode

### Description
Encodes `bytes` into the vector `output`. This is a convenience for cases where you have `std` available.

### Method
`pub fn encode(bytes: &[u8], output: &mut Vec<u8>)`

### Parameters
- `bytes`: A slice of bytes to be encoded.
- `output`: A mutable reference to a `Vec<u8>` where the encoded data will be appended.
```

--------------------------------

### Decoder Struct

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

A stateful decoder for incrementally processing COBS encoded data. The `advance` method processes one byte at a time and returns the decoding status.

```APIDOC
## Decoder Struct

Provides stateful, incremental decoding of COBS encoded data.

### Description

The `Decoder` struct maintains the internal state required to decode a COBS message byte by byte. This is useful for processing streams of data where the entire message may not be available at once. The `advance` method takes a single byte as input and updates the decoder's state, returning a `DecodeStatus` indicating whether more data is needed, the decoding is complete, or a byte should be appended to the output.

### Methods

#### `advance(&mut self, byte: u8) -> Result<DecodeStatus, CobsError>`

Processes a single byte of the COBS encoded input.

- **Parameters**:
  - `byte` (`u8`): The next byte from the COBS encoded input stream.
- **Returns**:
  - `Result<DecodeStatus, CobsError>`: An `Ok` variant containing a `DecodeStatus` indicating the result of processing the byte, or an `Err` variant with a `CobsError` if the input is malformed.
```

--------------------------------

### Advance Byte in Decoder

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Advances the decoder with a single byte of COBS encoded data. It returns the decoding status or an error if the data is malformed.

```rust
pub fn advance(&mut self, byte: u8) -> Result<DecodeStatus, CobsError>
```

--------------------------------

### Calculate Maximum Encoded Length

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Calculates the maximum possible encoded size for a given raw message length. This is useful for pre-allocating buffer space. The function is a `const fn` allowing its use in compile-time array sizing.

```rust
/// Returns the largest possible encoded size for an input message of `raw_len`
/// bytes, considering overhead.
///
/// This is a `const fn` so that you can use it to size arrays:
///
/// ```
/// const MSG_SIZE: usize = 254;
/// // Worst-case input message: no zeroes to exploit.
/// let mut msg = [0xFF; MSG_SIZE];
/// // This will still be enough space!
/// let mut encoded = [0; corncobs::max_encoded_len(MSG_SIZE)];
///
/// let len = corncobs::encode_buf(&msg, &mut encoded);
/// assert_eq!(len, encoded.len());
/// ```
pub const fn max_encoded_len(raw_len: usize) -> usize {
    let overhead = if raw_len == 0 {
        // In the special case of an empty message, we wind up generating one
        // byte of overhead.
        1
    } else {
        (raw_len + 253) / 254
    };
    // +1 for terminator byte.
    raw_len + overhead + 1
}
```

--------------------------------

### COBS Decoding Errors

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Defines the possible errors that can occur during COBS decoding, such as truncated input or corrupt data.

```rust
/// Errors that can occur while decoding.
#[derive(Copy, Clone, Debug)]
pub enum CobsError {
    /// The input ended without completing the last run or without the trailing
    /// zero byte, suggesting that part of it is missing. (This can also occur
    /// spuriously if you pick up in the middle of a stream without finding the
    /// first zero.)
    Truncated,
    /// The input contained an unexpected zero byte. Not all decode methods
    /// promise to detect this case.
    Corrupt,
}

impl core::fmt::Display for CobsError {
    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
        match self {
            Self::Truncated => f.write_str("input truncated"),
            Self::Corrupt => f.write_str("input corrupt"),
        }
    }
}

#[cfg(feature = "std")]
impl std::error::Error for CobsError {}
```

--------------------------------

### Decode Length Byte

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Helper function to decode a length-or-terminator byte. Returns None for ZERO, otherwise the run length.

```rust
/// Decodes a length-or-terminator byte. If the byte is `ZERO`, returns `None`.
/// Otherwise returns the length of the run encoded by the byte.
#[inline(always)]
fn decode_len(code: u8) -> Option<usize> {
    usize::from(code).checked_sub(1)
}
```

--------------------------------

### encode_iter

Source: https://docs.rs/corncobs/0.1.4/corncobs/fn.encode_iter.html

Encodes a byte slice into COBS format and returns an iterator that yields the encoded bytes one by one. This method is optimized for scenarios where memory allocation is limited or data is processed serially, though it may be slower than buffer-based encoding for large amounts of data.

```APIDOC
## encode_iter

### Description
Encodes `bytes` into COBS form, yielding individual encoded bytes through an iterator. This method is suitable for streaming scenarios where memory allocation is constrained, such as encoding data for serial peripherals.

### Signature
```rust
pub fn encode_iter(bytes: &[u8]) -> impl Iterator<Item = u8> + '_ 
```

### Parameters
* `bytes` - A slice of bytes to be encoded.

### Returns
An iterator that yields the COBS-encoded bytes.
```

--------------------------------

### decode_buf

Source: https://docs.rs/corncobs/0.1.4/corncobs/fn.decode_buf.html

Decodes COBS-encoded data from a byte slice into a mutable output slice. It returns the number of bytes written to the output buffer. The caller must ensure the output buffer is large enough to hold the decoded data, which can be at least `max_encoded_len(bytes.len())`.

```APIDOC
## decode_buf

### Description
Decodes input from `bytes` into `output` starting at index 0. Returns the number of bytes used in `output`.

### Signature
```rust
pub fn decode_buf(bytes: &[u8], output: &mut [u8]) -> Result<usize, CobsError>
```

### Panics
If `output` is not long enough to receive the decoded output. To be safe, `output` must be at least `max_encoded_len(bytes.len())`.
```

--------------------------------

### Decoder Struct Definition

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Defines the Decoder struct, which is used for decoding COBS encoded data. It has private fields and is intended for internal use.

```rust
pub struct Decoder { /* private fields */ }
```

--------------------------------

### decode_buf function for COBS decoding

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Decodes COBS-encoded input bytes into a mutable slice. It returns the number of bytes written to the output slice and handles message termination and run lengths. Panics if the output slice is not long enough.

```rust
pub fn decode_buf(mut bytes: &[u8], mut output: &mut [u8]) -> Result<usize, CobsError> {
    let orig_len = output.len();

    let mut trailing_zero = false;
    // This while-loop is equivalent to `for b in bytes` except that it lets us
    // _also_ consume bytes inside the body, which we totally do.
    while let Some((&head, rest)) = bytes.split_first() {
        bytes = rest;
        // Detect message terminator.
        let n = if let Some(n) = decode_len(head) {
            n
        } else {
            let decoded_len = orig_len - output.len();
            return Ok(decoded_len);
        };
        // If we're not at the end of the message, and our last run was less
        // than MAX_RUN bytes, we need to insert a zero.
        if trailing_zero {
            let (z, new_output) = output.split_at_mut(1);
            z[0] = ZERO;
            output = new_output;
        }

        // Skip a bunch of work if our run length is zero. This cuts the
        // worst-case time in benchmarks (on Intel) by about 50% while only
        // slightly impacting the less pathological cases.
        if n != 0 {
            // Refuse to proceed if the run claims to contain more bytes than
            // the slice does. (This check prevents a panic in decoding
            // truncated data.)
            if bytes.len() < n {
                break;
            }
            
```

--------------------------------

### decode_in_place

Source: https://docs.rs/corncobs/0.1.4/corncobs/fn.decode_in_place.html

Decodes a COBS encoded message in-place. This function is memory-efficient as it modifies the input byte slice directly. The decoded message is placed at the beginning of the slice, and the function returns the number of decoded bytes. It's suitable when memory is constrained, though `decode_buf` might be faster if memory is not an issue.

```APIDOC
## decode_in_place

### Description
Decodes an encoded message, in-place. This is useful when you’re short on memory. Since the decoded form of a COBS frame is always shorter than the encoded form, `bytes` is guaranteed to be long enough.
The decoded message is deposited into `bytes` starting at index 0, and `decode_in_place` returns the number of decoded bytes.

### Signature
```rust
pub fn decode_in_place(bytes: &mut [u8]) -> Result<usize, CobsError>
```

### Parameters
#### Path Parameters
- **bytes** (`&mut [u8]`) - Required - A mutable byte slice containing the COBS encoded message. The decoded message will overwrite the beginning of this slice.

### Returns
- **Result<usize, CobsError>** - On success, returns `Ok(usize)` where `usize` is the number of bytes successfully decoded. On failure, returns `Err(CobsError)` indicating the decoding error.

### Notes
- This function is generally slower than `decode_buf` (1x to 3x the time in benchmarks).
- Use this function when memory is a constraint or when overwriting the input data is acceptable.
```

--------------------------------

### BorrowMut Method

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Mutably borrows the value. This is part of the `BorrowMut` trait implementation, allowing modification of the underlying data.

```rust
fn borrow_mut(&mut self) -> &mut T
```

--------------------------------

### COBS Decode Status Enum

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Defines the possible outcomes of a COBS decoding step: Pending, Append a byte, or Done.

```rust
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum DecodeStatus {
    Pending,
    Append(u8),
    Done,
}
```

--------------------------------

### Encode Length Byte

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Encodes a run length (0 to MAX_RUN) into a single byte, ensuring the result is not zero. This is a private helper function used internally for COBS encoding.

```rust
/// Encoding a len (between `0` and `MAX_RUN` inclusive) into a byte such that
/// we avoid `ZERO`.
#[inline(always)]
fn encode_len(len: usize) -> u8 {
    // This assert is intended to catch mistakes while hacking on the internals
    // of corncobs.
    debug_assert!(len <= MAX_RUN);
    // This function is private and all paths through the code are reasonably
    // well tested, so we're pretty sure the assert above holds even in release
    // builds. As a result, explicitly opt out of overflow checks on this
    // addition.
    //
    // We're doing the addition on `usize` to ensure we don't generate
    // additional zero extend instructions.
    len.wrapping_add(1) as u8
}
```

--------------------------------

### MAX_RUN Constant

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

The longest run of unchanged bytes that can be encoded using COBS. Changing this constant will decrease encoding efficiency and break compatibility with other COBS implementations.

```APIDOC
## MAX_RUN Constant

### Description
Longest run of unchanged bytes that can be encoded using COBS.

Changing this will decrease encoding efficiency and break compatibility with other COBS implementations, so, don't do that.

### Type
usize

### Value
`254`
```

--------------------------------

### Encode Byte Slice

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Encodes a byte slice into COBS format into a mutable buffer. This function is suitable for environments with `std` available, as it manages buffer resizing.

```rust
pub fn encode(bytes: &[u8], output: &mut Vec<u8>) {
    // Big computers with `std` have effectively unlimited memory, so, go ahead
    // and resize that vector to the maximum we might need:
    let offset = output.len();
    output.resize(offset + max_encoded_len(bytes.len()), 0);
    // Now just treat it as a slice.
    let actual_len = encode_buf(bytes, &mut output[offset..]);
    output.truncate(offset + actual_len);
}
```

--------------------------------

### max_encoded_len

Source: https://docs.rs/corncobs

Returns the largest possible encoded size for an input message of `raw_len` bytes, considering overhead.

```APIDOC
## max_encoded_len

### Description
Returns the largest possible encoded size for an input message of `raw_len` bytes, considering overhead.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **max_len** (usize) - The maximum possible encoded size.

### Response Example
None
```

--------------------------------

### Encode Iterator

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Encodes a byte slice into COBS form, yielding individual encoded bytes through an iterator. This is useful for streaming or when memory is constrained, though it is slower than buffer-based encoding.

```rust
/// Encodes `bytes` into COBS form, yielding individual encoded bytes through an
/// iterator.
///
/// This is quite a bit slower than memory-to-memory encoding (e.g. 
/// `encode_buf`) because it can't move whole blocks of non-zero bytes at a
/// time -- about 35-40x slower in benchmarks. However, if your throughput is
/// restricted by the speed of a link that gets fed one byte a time, such as a
/// serial peripheral, this can encode messages with no additional memory.
pub fn encode_iter(bytes: &[u8]) -> impl Iterator<Item = u8> + '_ {
    let mut state = Some(EncodeState::Begin(bytes));
    core::iter::from_fn(move || {
        let s = state?;
        let (b, s2) = s.next();
        state = s2;
        Some(b)
    })
}
```

--------------------------------

### decode function for COBS decoding with std feature

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

A convenience function for decoding COBS bytes into a `Vec<u8>` when the `std` feature is enabled. It resizes the output vector and calls `decode_buf`.

```rust
#[cfg(feature = "std")]
pub fn decode(bytes: &[u8], output: &mut Vec<u8>) -> Result<(), CobsError> {
    let offset = output.len();
    output.resize(offset + bytes.len(), 0);
    let actual_len = decode_buf(bytes, &mut output[offset..])?;
    output.truncate(offset + actual_len);
    Ok(())
}
```

--------------------------------

### Check if Decoder is Done

Source: https://docs.rs/corncobs/0.1.4/corncobs/struct.Decoder.html

Checks if the COBS decoding process is complete. This method should be called after processing all input bytes.

```rust
pub fn is_done(&self) -> bool
```

--------------------------------

### max_encoded_len

Source: https://docs.rs/corncobs/0.1.4/corncobs/fn.max_encoded_len.html

Returns the largest possible encoded size for an input message of `raw_len` bytes, considering overhead. This function can be used at compile time to determine buffer sizes.

```APIDOC
## Function max_encoded_len

### Description
Returns the largest possible encoded size for an input message of `raw_len` bytes, considering overhead.

This is a `const fn` so that you can use it to size arrays:

```rust
const MSG_SIZE: usize = 254;
// Worst-case input message: no zeroes to exploit.
let mut msg = [0xFF; MSG_SIZE];
// This will still be enough space!
let mut encoded = [0; corncobs::max_encoded_len(MSG_SIZE)];

let len = corncobs::encode_buf(&msg, &mut encoded);
assert_eq!(len, encoded.len());
```

### Signature
```rust
pub const fn max_encoded_len(raw_len: usize) -> usize
```

### Parameters
#### Path Parameters
- **raw_len** (usize) - The raw length of the input message in bytes.
```

--------------------------------

### DecodeStatus Enum Definition

Source: https://docs.rs/corncobs/0.1.4/corncobs/enum.DecodeStatus.html

Defines the DecodeStatus enum with three variants: Pending, Append(u8), and Done. Use this enum to track the state of a decoding process.

```rust
pub enum DecodeStatus {
    Pending,
    Append(u8),
    Done,
}
```

--------------------------------

### max_encoded_len

Source: https://docs.rs/corncobs/0.1.4/index.html

Calculates the maximum possible size of a COBS encoded message given the length of the raw input message.

```APIDOC
## max_encoded_len

### Description
Returns the largest possible encoded size for an input message of `raw_len` bytes, considering overhead.

### Function Signature
`fn max_encoded_len(raw_len: usize) -> usize`

### Parameters
- `raw_len` (usize): The length of the raw, unencoded message in bytes.

### Returns
`usize`: The maximum number of bytes the COBS encoded message could occupy.
```

--------------------------------

### CobsError Enum

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Defines the possible errors that can occur during COBS decoding. These include `Truncated` input and `Corrupt` input due to unexpected zero bytes.

```APIDOC
## CobsError Enum

Enumerates potential errors during COBS decoding.

### Variants

- **Truncated**: The input ended unexpectedly, either without completing the last run or without the trailing zero byte. This can also occur if processing starts mid-stream without finding the initial zero.
- **Corrupt**: The input contained an unexpected zero byte. Note that not all decoding methods are guaranteed to detect this.
```

--------------------------------

### In-Place COBS Decoding

Source: https://docs.rs/corncobs/0.1.4/src/corncobs/lib.rs.html

Decodes a COBS-encoded message directly within the provided byte slice. Returns the number of decoded bytes or a CobsError.

```rust
/// Decodes an encoded message, in-place. This is useful when you're short on
/// memory. Since the decoded form of a COBS frame is always shorter than the
/// encoded form, `bytes` is guaranteed to be long enough.
///
/// The decoded message is deposited into `bytes` starting at index 0, and
/// `decode_in_place` returns the number of decoded bytes.
///
/// If you've got memory to spare, `decode_buf` is often somewhat faster --
/// `decode_in_place` takes between 1x and 3x the time in benchmarks. You may
/// also prefer to use `decode_buf` if you can't overwrite the incoming data,
/// for whatever reason.
pub fn decode_in_place(bytes: &mut [u8]) -> Result<usize, CobsError> {
    let mut inpos = 0;
    let mut outpos = 0;
    let mut extra_zero = false;
    while inpos < bytes.len() {
        let head = bytes[inpos];
        let n = if let Some(n) = decode_len(head) {
            n
        } else {
            break;
        };
        if bytes.len() < inpos + 1 + n {
            return Err(CobsError::Truncated);
        }
        bytes.copy_within(inpos + 1..inpos + 1 + n, outpos);
        inpos += 1 + n;
        outpos += n;
        extra_zero = n != MAX_RUN;
        if extra_zero {
            bytes[outpos] = 0;
            outpos += 1;
        }
    }
    Ok(if extra_zero {
        outpos - 1
    } else {
        outpos
    })
}
```

--------------------------------

### CobsError Enum Definition

Source: https://docs.rs/corncobs/0.1.4/corncobs/enum.CobsError.html

Defines the possible errors that can occur during COBS decoding. Use this enum to handle decoding failures gracefully.

```rust
pub enum CobsError {
    Truncated,
    Corrupt,
}
```
Tokens:
Raw