tokio/io/util/
lines.rs

1use crate::io::util::read_until::read_until_internal;
2use crate::io::AsyncBufRead;
3
4use pin_project_lite::pin_project;
5use std::io;
6use std::mem;
7use std::pin::Pin;
8use std::task::{ready, Context, Poll};
9
10pin_project! {
11    /// Reads lines from an [`AsyncBufRead`].
12    ///
13    /// A `Lines` can be turned into a `Stream` with [`LinesStream`].
14    ///
15    /// This type is usually created using the [`lines`] method.
16    ///
17    /// [`AsyncBufRead`]: crate::io::AsyncBufRead
18    /// [`LinesStream`]: https://docs.rs/tokio-stream/0.1/tokio_stream/wrappers/struct.LinesStream.html
19    /// [`lines`]: crate::io::AsyncBufReadExt::lines
20    #[derive(Debug)]
21    #[must_use = "streams do nothing unless polled"]
22    #[cfg_attr(docsrs, doc(cfg(feature = "io-util")))]
23    pub struct Lines<R> {
24        #[pin]
25        reader: R,
26        buf: Vec<u8>,
27    }
28}
29
30pub(crate) fn lines<R>(reader: R) -> Lines<R>
31where
32    R: AsyncBufRead,
33{
34    Lines {
35        reader,
36        buf: Vec::new(),
37    }
38}
39
40impl<R> Lines<R>
41where
42    R: AsyncBufRead + Unpin,
43{
44    /// Returns the next line in the stream.
45    ///
46    /// # Cancel safety
47    ///
48    /// This method is cancel safe.
49    ///
50    /// # Examples
51    ///
52    /// ```
53    /// # use tokio::io::AsyncBufRead;
54    /// use tokio::io::AsyncBufReadExt;
55    ///
56    /// # async fn dox(my_buf_read: impl AsyncBufRead + Unpin) -> std::io::Result<()> {
57    /// let mut lines = my_buf_read.lines();
58    ///
59    /// while let Some(line) = lines.next_line().await? {
60    ///     println!("length = {}", line.len())
61    /// }
62    /// # Ok(())
63    /// # }
64    /// ```
65    pub async fn next_line(&mut self) -> io::Result<Option<String>> {
66        use std::future::poll_fn;
67
68        poll_fn(|cx| Pin::new(&mut *self).poll_next_line(cx)).await
69    }
70
71    /// Obtains a mutable reference to the underlying reader.
72    pub fn get_mut(&mut self) -> &mut R {
73        &mut self.reader
74    }
75
76    /// Obtains a reference to the underlying reader.
77    pub fn get_ref(&mut self) -> &R {
78        &self.reader
79    }
80
81    /// Unwraps this `Lines<R>`, returning the underlying reader.
82    ///
83    /// Note that any leftover data in the internal buffer is lost.
84    /// Therefore, a following read from the underlying reader may lead to data loss.
85    pub fn into_inner(self) -> R {
86        self.reader
87    }
88}
89
90impl<R> Lines<R>
91where
92    R: AsyncBufRead,
93{
94    /// Polls for the next line in the stream.
95    ///
96    /// This method returns:
97    ///
98    ///  * `Poll::Pending` if the next line is not yet available.
99    ///  * `Poll::Ready(Ok(Some(line)))` if the next line is available.
100    ///  * `Poll::Ready(Ok(None))` if there are no more lines in this stream.
101    ///  * `Poll::Ready(Err(err))` if an IO error occurred while reading the next line,
102    ///    or if the line was not valid UTF-8.
103    ///
104    /// A line that is not valid UTF-8 is returned as the [`FromUtf8Error`]
105    /// inside the error, and the next call reads the following line.
106    ///
107    /// [`FromUtf8Error`]: std::string::FromUtf8Error
108    ///
109    /// When the method returns `Poll::Pending`, the `Waker` in the provided
110    /// `Context` is scheduled to receive a wakeup when more bytes become
111    /// available on the underlying IO resource.  Note that on multiple calls to
112    /// `poll_next_line`, only the `Waker` from the `Context` passed to the most
113    /// recent call is scheduled to receive a wakeup.
114    pub fn poll_next_line(
115        self: Pin<&mut Self>,
116        cx: &mut Context<'_>,
117    ) -> Poll<io::Result<Option<String>>> {
118        let me = self.project();
119
120        let mut read = 0;
121        let n = ready!(read_until_internal(me.reader, cx, b'\n', me.buf, &mut read))?;
122
123        if n == 0 && me.buf.is_empty() {
124            return Poll::Ready(Ok(None));
125        }
126
127        let mut bytes = mem::take(me.buf);
128
129        if bytes.last() == Some(&b'\n') {
130            bytes.pop();
131
132            if bytes.last() == Some(&b'\r') {
133                bytes.pop();
134            }
135        }
136
137        match String::from_utf8(bytes) {
138            Ok(line) => Poll::Ready(Ok(Some(line))),
139            Err(err) => Poll::Ready(Err(io::Error::new(io::ErrorKind::InvalidData, err))),
140        }
141    }
142}
143
144#[cfg(test)]
145mod tests {
146    use super::*;
147
148    #[test]
149    fn assert_unpin() {
150        crate::is_unpin::<Lines<()>>();
151    }
152}
tokio/io/util/lines.rs

tokio/io/util/
lines.rs
