Repository: tokio-rs/tokio
File: tokio-util/src/codec/mod.rs (Rust)

Code before:
//!
//!     assert_eq!(buffer.as_slice(), "Hello\nWorld\n".as_bytes());
//! }
//!```
//!
//! # Example decoding using `LinesCodec`
//! The following example demonstrates how to use a codec such as [`LinesCodec`] to
//! read a stream of framed data. [`FramedRead`] can be used to achieve this. [`FramedRead`]
//! will keep reading from an [`AsyncRead`] implementor until a whole frame, according to a codec,
//! can be parsed.
//!```
//! use tokio_stream::StreamExt;
//! use tokio_util::codec::LinesCodec;
//! use tokio_util::codec::FramedRead;
//!
//! #[tokio::main]
//! async fn main() {
//!     let message = "Hello\nWorld".as_bytes();
//!     let decoder = LinesCodec::new();
//!
//!     // FramedRead can be used to read a stream of values that are framed according to
//!     // a codec. FramedRead will read from its input (here `buffer`) until a whole frame
//!     // can be parsed.
//!     let mut reader = FramedRead::new(message, decoder);
//!
//!     // To be able to read values from a FramedRead, you need to bring the
//!     // `StreamExt` trait into scope.
//!     let frame1 = reader.next().await.unwrap().unwrap();
//!     let frame2 = reader.next().await.unwrap().unwrap();
//!
//!     assert!(reader.next().await.is_none());
//!     assert_eq!(frame1, "Hello");
//!     assert_eq!(frame2, "World");
//! }
//! ```
//!
//! # The Decoder trait
//!
//! A [`Decoder`] is used together with [`FramedRead`] or [`Framed`] to turn an
//! [`AsyncRead`] into a [`Stream`]. The job of the decoder trait is to specify
//! how sequences of bytes are turned into a sequence of frames, and to
//! determine where the boundaries between frames are.  The job of the
//! `FramedRead` is to repeatedly switch between reading more data from the IO
//! resource, and asking the decoder whether we have received enough data to
//! decode another frame of data.
//!
//! The main method on the `Decoder` trait is the [`decode`] method. This method
//! takes as argument the data that has been read so far, and when it is called,
//! it will be in one of the following situations:
//!
//!  1. The buffer contains less than a full frame.

Review comment (suggestion):
```suggestion
//!     // To read values from a FramedRead, you need to bring the
```

Code after:
//!     let buffer = writer.get_ref();
//!
//!     assert_eq!(buffer.as_slice(), "Hello\nWorld\n".as_bytes());
//! }
//!```
//!
//! # Example decoding using `LinesCodec`
//! The following example demonstrates how to use a codec such as [`LinesCodec`] to
//! read a stream of framed data. [`FramedRead`] can be used to achieve this. [`FramedRead`]
//! will keep reading from an [`AsyncRead`] implementor until a whole frame, according to a codec,
//! can be parsed.
//!
//!```
//! use tokio_stream::StreamExt;
//! use tokio_util::codec::LinesCodec;
//! use tokio_util::codec::FramedRead;
//!
//! #[tokio::main]
//! async fn main() {
//!     let message = "Hello\nWorld".as_bytes();
//!     let decoder = LinesCodec::new();
//!
//!     // FramedRead can be used to read a stream of values that are framed according to
//!     // a codec. FramedRead will read from its input (here `buffer`) until a whole frame
//!     // can be parsed.
//!     let mut reader = FramedRead::new(message, decoder);
//!
//!     // To read values from a FramedRead, you need to bring the
//!     // `StreamExt` trait into scope.
//!     let frame1 = reader.next().await.unwrap().unwrap();
//!     let frame2 = reader.next().await.unwrap().unwrap();
//!
//!     assert!(reader.next().await.is_none());
//!     assert_eq!(frame1, "Hello");
//!     assert_eq!(frame2, "World");
//! }
//! ```
//!
//! # The Decoder trait
//!
//! A [`Decoder`] is used together with [`FramedRead`] or [`Framed`] to turn an
//! [`AsyncRead`] into a [`Stream`]. The job of the decoder trait is to specify
//! how sequences of bytes are turned into a sequence of frames, and to
//! determine where the boundaries between frames are.  The job of the
//! `FramedRead` is to repeatedly switch between reading more data from the IO
//! resource, and asking the decoder whether we have received enough data to
//! decode another frame of data.
//!
//! The main method on the `Decoder` trait is the [`decode`] method. This method
//! takes as argument the data that has been read so far, and when it is called,
//! it will be in one of the following situations: