alloc/io/buf_read.rs
1use core::slice::memchr;
2
3use crate::io::{ErrorKind, Lines, Read, Result, Split, append_to_string, lines, split};
4use crate::string::String;
5use crate::vec::Vec;
6
7/// A `BufRead` is a type of [`Read`]er which has an internal buffer, allowing it
8/// to perform extra ways of reading.
9///
10/// For example, reading line-by-line is inefficient without using a buffer, so
11/// if you want to read by line, you'll need `BufRead`, which includes a
12/// [`read_line`] method as well as a [`lines`] iterator.
13///
14/// # Examples
15///
16/// A locked standard input implements `BufRead`:
17///
18/// ```no_run
19/// use std::io;
20/// use std::io::prelude::*;
21///
22/// let stdin = io::stdin();
23/// for line in stdin.lock().lines() {
24/// println!("{}", line?);
25/// }
26/// # std::io::Result::Ok(())
27/// ```
28///
29/// If you have something that implements [`Read`], you can use the `BufReader`
30/// type to turn it into a `BufRead`.
31///
32/// For example, `File` implements [`Read`], but not `BufRead`.
33/// `BufReader` to the rescue!
34///
35/// [`read_line`]: BufRead::read_line
36/// [`lines`]: BufRead::lines
37///
38/// ```no_run
39/// use std::io::{self, BufReader};
40/// use std::io::prelude::*;
41/// use std::fs::File;
42///
43/// fn main() -> io::Result<()> {
44/// let f = File::open("foo.txt")?;
45/// let f = BufReader::new(f);
46///
47/// for line in f.lines() {
48/// let line = line?;
49/// println!("{line}");
50/// }
51///
52/// Ok(())
53/// }
54/// ```
55#[stable(feature = "rust1", since = "1.0.0")]
56#[cfg_attr(not(test), rustc_diagnostic_item = "IoBufRead")]
57pub trait BufRead: Read {
58 /// Returns the contents of the internal buffer, filling it with more data, via [`Read`] methods, if empty.
59 ///
60 /// This is a lower-level method and is meant to be used together with [`consume`],
61 /// which can be used to mark bytes that should not be returned by subsequent calls to `read`.
62 ///
63 /// [`consume`]: BufRead::consume
64 ///
65 /// Returns an empty buffer when the stream has reached EOF.
66 ///
67 /// # Errors
68 ///
69 /// This function will return an I/O error if a [`Read`] method was called, but returned an error.
70 ///
71 /// # Examples
72 ///
73 /// A locked standard input implements `BufRead`:
74 ///
75 /// ```no_run
76 /// use std::io;
77 /// use std::io::prelude::*;
78 ///
79 /// let stdin = io::stdin();
80 /// let mut stdin = stdin.lock();
81 ///
82 /// let buffer = stdin.fill_buf()?;
83 ///
84 /// // work with buffer
85 /// println!("{buffer:?}");
86 ///
87 /// // mark the bytes we worked with as read
88 /// let length = buffer.len();
89 /// stdin.consume(length);
90 /// # std::io::Result::Ok(())
91 /// ```
92 #[stable(feature = "rust1", since = "1.0.0")]
93 fn fill_buf(&mut self) -> Result<&[u8]>;
94
95 /// Marks the given `amount` of additional bytes from the internal buffer as having been read.
96 /// Subsequent calls to `read` only return bytes that have not been marked as read.
97 ///
98 /// This is a lower-level method and is meant to be used together with [`fill_buf`],
99 /// which can be used to fill the internal buffer via [`Read`] methods.
100 ///
101 /// It is a logic error if `amount` exceeds the number of unread bytes in the internal buffer, which is returned by [`fill_buf`].
102 ///
103 /// # Examples
104 ///
105 /// Since `consume()` is meant to be used with [`fill_buf`],
106 /// that method's example includes an example of `consume()`.
107 ///
108 /// [`fill_buf`]: BufRead::fill_buf
109 #[stable(feature = "rust1", since = "1.0.0")]
110 fn consume(&mut self, amount: usize);
111
112 /// Checks if there is any data left to be `read`.
113 ///
114 /// This function may fill the buffer to check for data,
115 /// so this function returns `Result<bool>`, not `bool`.
116 ///
117 /// The default implementation calls `fill_buf` and checks that the
118 /// returned slice is empty (which means that there is no data left,
119 /// since EOF is reached).
120 ///
121 /// # Errors
122 ///
123 /// This function will return an I/O error if a [`Read`] method was called, but returned an error.
124 ///
125 /// Examples
126 ///
127 /// ```
128 /// #![feature(buf_read_has_data_left)]
129 /// use std::io;
130 /// use std::io::prelude::*;
131 ///
132 /// let stdin = io::stdin();
133 /// let mut stdin = stdin.lock();
134 ///
135 /// while stdin.has_data_left()? {
136 /// let mut line = String::new();
137 /// stdin.read_line(&mut line)?;
138 /// // work with line
139 /// println!("{line:?}");
140 /// }
141 /// # std::io::Result::Ok(())
142 /// ```
143 #[unstable(feature = "buf_read_has_data_left", issue = "86423")]
144 fn has_data_left(&mut self) -> Result<bool> {
145 self.fill_buf().map(|b| !b.is_empty())
146 }
147
148 /// Reads all bytes into `buf` until the delimiter `byte` or EOF is reached.
149 ///
150 /// This function will read bytes from the underlying stream until the
151 /// delimiter or EOF is found. Once found, all bytes up to, and including,
152 /// the delimiter (if found) will be appended to `buf`.
153 ///
154 /// If successful, this function will return the total number of bytes read.
155 ///
156 /// This function is blocking and should be used carefully: it is possible for
157 /// an attacker to continuously send bytes without ever sending the delimiter
158 /// or EOF.
159 ///
160 /// # Errors
161 ///
162 /// This function will ignore all instances of [`ErrorKind::Interrupted`] and
163 /// will otherwise return any errors returned by [`fill_buf`].
164 ///
165 /// If an I/O error is encountered then all bytes read so far will be
166 /// present in `buf` and its length will have been adjusted appropriately.
167 ///
168 /// [`fill_buf`]: BufRead::fill_buf
169 ///
170 /// # Examples
171 ///
172 /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In
173 /// this example, we use [`Cursor`] to read all the bytes in a byte slice
174 /// in hyphen delimited segments:
175 ///
176 /// [`Cursor`]: crate::io::Cursor
177 ///
178 /// ```
179 /// use std::io::{self, BufRead};
180 ///
181 /// let mut cursor = io::Cursor::new(b"lorem-ipsum");
182 /// let mut buf = vec![];
183 ///
184 /// // cursor is at 'l'
185 /// let num_bytes = cursor.read_until(b'-', &mut buf)
186 /// .expect("reading from cursor won't fail");
187 /// assert_eq!(num_bytes, 6);
188 /// assert_eq!(buf, b"lorem-");
189 /// buf.clear();
190 ///
191 /// // cursor is at 'i'
192 /// let num_bytes = cursor.read_until(b'-', &mut buf)
193 /// .expect("reading from cursor won't fail");
194 /// assert_eq!(num_bytes, 5);
195 /// assert_eq!(buf, b"ipsum");
196 /// buf.clear();
197 ///
198 /// // cursor is at EOF
199 /// let num_bytes = cursor.read_until(b'-', &mut buf)
200 /// .expect("reading from cursor won't fail");
201 /// assert_eq!(num_bytes, 0);
202 /// assert_eq!(buf, b"");
203 /// ```
204 #[stable(feature = "rust1", since = "1.0.0")]
205 fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize> {
206 default_read_until(self, byte, buf)
207 }
208
209 /// Skips all bytes until the delimiter `byte` or EOF is reached.
210 ///
211 /// This function will read (and discard) bytes from the underlying stream until the
212 /// delimiter or EOF is found.
213 ///
214 /// If successful, this function will return the total number of bytes read,
215 /// including the delimiter byte if found.
216 ///
217 /// This is useful for efficiently skipping data such as NUL-terminated strings
218 /// in binary file formats without buffering.
219 ///
220 /// This function is blocking and should be used carefully: it is possible for
221 /// an attacker to continuously send bytes without ever sending the delimiter
222 /// or EOF.
223 ///
224 /// # Errors
225 ///
226 /// This function will ignore all instances of [`ErrorKind::Interrupted`] and
227 /// will otherwise return any errors returned by [`fill_buf`].
228 ///
229 /// If an I/O error is encountered then all bytes read so far will be
230 /// present in `buf` and its length will have been adjusted appropriately.
231 ///
232 /// [`fill_buf`]: BufRead::fill_buf
233 ///
234 /// # Examples
235 ///
236 /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In
237 /// this example, we use [`Cursor`] to read some NUL-terminated information
238 /// about Ferris from a binary string, skipping the fun fact:
239 ///
240 /// [`Cursor`]: crate::io::Cursor
241 ///
242 /// ```
243 /// use std::io::{self, BufRead};
244 ///
245 /// let mut cursor = io::Cursor::new(b"Ferris\0Likes long walks on the beach\0Crustacean\0!");
246 ///
247 /// // read name
248 /// let mut name = Vec::new();
249 /// let num_bytes = cursor.read_until(b'\0', &mut name)
250 /// .expect("reading from cursor won't fail");
251 /// assert_eq!(num_bytes, 7);
252 /// assert_eq!(name, b"Ferris\0");
253 ///
254 /// // skip fun fact
255 /// let num_bytes = cursor.skip_until(b'\0')
256 /// .expect("reading from cursor won't fail");
257 /// assert_eq!(num_bytes, 30);
258 ///
259 /// // read animal type
260 /// let mut animal = Vec::new();
261 /// let num_bytes = cursor.read_until(b'\0', &mut animal)
262 /// .expect("reading from cursor won't fail");
263 /// assert_eq!(num_bytes, 11);
264 /// assert_eq!(animal, b"Crustacean\0");
265 ///
266 /// // reach EOF
267 /// let num_bytes = cursor.skip_until(b'\0')
268 /// .expect("reading from cursor won't fail");
269 /// assert_eq!(num_bytes, 1);
270 /// ```
271 #[stable(feature = "bufread_skip_until", since = "1.83.0")]
272 fn skip_until(&mut self, byte: u8) -> Result<usize> {
273 default_skip_until(self, byte)
274 }
275
276 /// Reads all bytes until a newline (the `0xA` byte) is reached, and append
277 /// them to the provided [`String`] buffer.
278 ///
279 /// Previous content of the buffer will be preserved. To avoid appending to
280 /// the buffer, you need to [`clear`] it first.
281 ///
282 /// This function will read bytes from the underlying stream until the
283 /// newline delimiter (the `0xA` byte) or EOF is found. Once found, all bytes
284 /// up to, and including, the delimiter (if found) will be appended to
285 /// `buf`.
286 ///
287 /// If successful, this function will return the total number of bytes read.
288 ///
289 /// If this function returns [`Ok(0)`], the stream has reached EOF.
290 ///
291 /// This function is blocking and should be used carefully: it is possible for
292 /// an attacker to continuously send bytes without ever sending a newline
293 /// or EOF. You can use [`take`] to limit the maximum number of bytes read.
294 ///
295 /// [`Ok(0)`]: Ok
296 /// [`clear`]: String::clear
297 /// [`take`]: crate::io::Read::take
298 ///
299 /// # Errors
300 ///
301 /// This function has the same error semantics as [`read_until`] and will
302 /// also return an error if the read bytes are not valid UTF-8. If an I/O
303 /// error is encountered then `buf` may contain some bytes already read in
304 /// the event that all data read so far was valid UTF-8.
305 ///
306 /// [`read_until`]: BufRead::read_until
307 ///
308 /// # Examples
309 ///
310 /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In
311 /// this example, we use [`Cursor`] to read all the lines in a byte slice:
312 ///
313 /// [`Cursor`]: crate::io::Cursor
314 ///
315 /// ```
316 /// use std::io::{self, BufRead};
317 ///
318 /// let mut cursor = io::Cursor::new(b"foo\nbar");
319 /// let mut buf = String::new();
320 ///
321 /// // cursor is at 'f'
322 /// let num_bytes = cursor.read_line(&mut buf)
323 /// .expect("reading from cursor won't fail");
324 /// assert_eq!(num_bytes, 4);
325 /// assert_eq!(buf, "foo\n");
326 /// buf.clear();
327 ///
328 /// // cursor is at 'b'
329 /// let num_bytes = cursor.read_line(&mut buf)
330 /// .expect("reading from cursor won't fail");
331 /// assert_eq!(num_bytes, 3);
332 /// assert_eq!(buf, "bar");
333 /// buf.clear();
334 ///
335 /// // cursor is at EOF
336 /// let num_bytes = cursor.read_line(&mut buf)
337 /// .expect("reading from cursor won't fail");
338 /// assert_eq!(num_bytes, 0);
339 /// assert_eq!(buf, "");
340 /// ```
341 #[stable(feature = "rust1", since = "1.0.0")]
342 fn read_line(&mut self, buf: &mut String) -> Result<usize> {
343 // Note that we are not calling the `.read_until` method here, but
344 // rather our hardcoded implementation. For more details as to why, see
345 // the comments in `default_read_to_string`.
346 // ignore-tidy-undocumented-unsafe
347 unsafe { append_to_string(buf, |b| default_read_until(self, b'\n', b)) }
348 }
349
350 /// Returns an iterator over the contents of this reader split on the byte
351 /// `byte`.
352 ///
353 /// The iterator returned from this function will return instances of
354 /// <code>[io::Result]<[Vec]\<u8>></code>. Each vector returned will *not* have
355 /// the delimiter byte at the end.
356 ///
357 /// This function will yield errors whenever [`read_until`] would have
358 /// also yielded an error.
359 ///
360 /// [io::Result]: self::Result "io::Result"
361 /// [`read_until`]: BufRead::read_until
362 ///
363 /// # Examples
364 ///
365 /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In
366 /// this example, we use [`Cursor`] to iterate over all hyphen delimited
367 /// segments in a byte slice
368 ///
369 /// [`Cursor`]: crate::io::Cursor
370 ///
371 /// ```
372 /// use std::io::{self, BufRead};
373 ///
374 /// let cursor = io::Cursor::new(b"lorem-ipsum-dolor");
375 ///
376 /// let mut split_iter = cursor.split(b'-').map(|l| l.unwrap());
377 /// assert_eq!(split_iter.next(), Some(b"lorem".to_vec()));
378 /// assert_eq!(split_iter.next(), Some(b"ipsum".to_vec()));
379 /// assert_eq!(split_iter.next(), Some(b"dolor".to_vec()));
380 /// assert_eq!(split_iter.next(), None);
381 /// ```
382 #[stable(feature = "rust1", since = "1.0.0")]
383 fn split(self, byte: u8) -> Split<Self>
384 where
385 Self: Sized,
386 {
387 split(self, byte)
388 }
389
390 /// Returns an iterator over the lines of this reader.
391 ///
392 /// The iterator returned from this function will yield instances of
393 /// <code>[io::Result]<[String]></code>. Each string returned will *not* have a newline
394 /// byte (the `0xA` byte) or `CRLF` (`0xD`, `0xA` bytes) at the end.
395 ///
396 /// [io::Result]: crate::io::Result "io::Result"
397 ///
398 /// # Examples
399 ///
400 /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In
401 /// this example, we use [`Cursor`] to iterate over all the lines in a byte
402 /// slice.
403 ///
404 /// [`Cursor`]: crate::io::Cursor
405 ///
406 /// ```
407 /// use std::io::{self, BufRead};
408 ///
409 /// let cursor = io::Cursor::new(b"lorem\nipsum\r\ndolor");
410 ///
411 /// let mut lines_iter = cursor.lines().map(|l| l.unwrap());
412 /// assert_eq!(lines_iter.next(), Some(String::from("lorem")));
413 /// assert_eq!(lines_iter.next(), Some(String::from("ipsum")));
414 /// assert_eq!(lines_iter.next(), Some(String::from("dolor")));
415 /// assert_eq!(lines_iter.next(), None);
416 /// ```
417 ///
418 /// # Errors
419 ///
420 /// Each line of the iterator has the same error semantics as [`BufRead::read_line`].
421 #[stable(feature = "rust1", since = "1.0.0")]
422 fn lines(self) -> Lines<Self>
423 where
424 Self: Sized,
425 {
426 lines(self)
427 }
428}
429
430fn default_read_until<R: BufRead + ?Sized>(
431 r: &mut R,
432 delim: u8,
433 buf: &mut Vec<u8>,
434) -> Result<usize> {
435 let mut read = 0;
436 loop {
437 let (done, used) = {
438 let available = match r.fill_buf() {
439 Ok(n) => n,
440 Err(ref e) if e.is_interrupted() => continue,
441 Err(e) => return Err(e),
442 };
443 let (done, available) = match memchr::memchr(delim, available) {
444 Some(i) => (true, &available[..=i]),
445 None => (false, available),
446 };
447
448 cfg_select! {
449 no_global_oom_handling => {
450 let count = available.len();
451 buf.try_reserve(count)?;
452
453 // SAFETY:
454 // * self and buf are non-overlapping
455 // * buf[..len] is already initialized
456 // * buf[len..len + count] is initialized by copy_nonoverlapping
457 // * len + count is within the capacity of buf based on the reservation completed above
458 unsafe {
459 let len = buf.len();
460 let src = available.as_ptr();
461 let dst = buf.as_mut_ptr().add(len);
462 core::ptr::copy_nonoverlapping(src, dst, count);
463 buf.set_len(len + count);
464 }
465 }
466 _ => {
467 buf.extend_from_slice(available);
468 }
469 }
470
471 (done, available.len())
472 };
473 r.consume(used);
474 read += used;
475 if done || used == 0 {
476 return Ok(read);
477 }
478 }
479}
480
481fn default_skip_until<R: BufRead + ?Sized>(r: &mut R, delim: u8) -> Result<usize> {
482 let mut read = 0;
483 loop {
484 let (done, used) = {
485 let available = match r.fill_buf() {
486 Ok(n) => n,
487 Err(ref e) if e.kind() == ErrorKind::Interrupted => continue,
488 Err(e) => return Err(e),
489 };
490 match memchr::memchr(delim, available) {
491 Some(i) => (true, i + 1),
492 None => (false, available.len()),
493 }
494 };
495 r.consume(used);
496 read += used;
497 if done || used == 0 {
498 return Ok(read);
499 }
500 }
501}