|0.4.0||Oct 25, 2020|
|0.4.0-alpha.4||Feb 8, 2020|
|0.4.0-alpha.2||Jul 8, 2019|
|0.4.0-alpha.0||Jun 27, 2019|
|0.1.2||Mar 16, 2018|
#113 in Asynchronous
71 downloads per month
Used in 5 crates (4 directly)
For prior art, see tokio-codec.
This borrows many of the ideas that originated there, though with a simpler
no_std-compatible approach. No allocation is strictly required by
implementers of the [Encode] or [Decode] traits, making them suitable for
Encoders are types that implement the [Encode] trait. Consumers of this
trait will provide an
Item to be encoded, along with a buffer into which
the resulting bytes should be placed. The
Encoder may return one of three
from this operation:
EncodeResult::Ok(n): The item was successfully encodeded into the provided buffer and took
EncodeResult::Err(e): There was an unrecoverable error encoding the item. Subsequent calls with the same item should return the same error.
EncodeResult::Overflow(n): The item could be encoded, but the encoded representation would overflow the buffer. If
n > 0, then a buffer of length
nis required to hold the serialized item.
Overflow result, the caller should allocate a bigger buffer (if
possible), and attempt the operation again.
Encode implementations may
keep a previously encoded
Item in an internal buffer to make re-attempted
encodings cheaper. If this approach is used, the [Encode::reset] method must
also be implemented.
Decoders implement the [Decode] trait. To decode an
Item, callers provide
the decoder with a buffer containing bytes from the stream. The decoder
usize indicating that it consumed some number of bytes from the
buffer, along with one of three results:
itemwas successfully decoded
DecodeResult::Err(e): An error
earose when decoding the item. This does not necessarily invalidate the stream.
DecodeResult::UnexpectedEnd: Not enough data to decode yet, caller should read more and try again with more bytes.
Decoders are free to consume bytes in-line with returning
results and keep a running internal buffer of what's been read so far, or
they may opt for consuming the bytes for an
Item all at once. They should
consume bytes in the error case as well so that the caller doesn't provide
the same bad data twice.
The [Framed] type provides a wrapper for
AsyncRead + AsyncWrite streams
that applies an
Encode + Decode object to create an async
Stream + Sink
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.