A better Rust ATProto crate
1//! A modified version of the Rust standard library's `std::io` module, suitable
2//! for use in Mycelium and other kernels.
3//!
4//! The traits and functions here are mostly identical to (and copied from!) the
5//! standard library's `std::io` module, with the following differences:
6//!
7//! - `Read::read_to_end` and `Read::read_to_string` require the "alloc" feature
8//! flag on `mycelium_util` (which is enabled by default). Bootloaders & other
9//! code which cannot allocate may disable this feature flag.
10//! - `Read::read_vectored` and `Write::write_vectored` do not exist.
11//! - Most of the `BufRead` utility functions (`lines`, `split`, `read_until`)
12//! require the "alloc" feature
13//! - `BufReader` and `BufWriter` require the "alloc" feature (and are not yet implemented).
14//! - The `io::Error` type takes an `ErrorKind` and an optional `&'static str`,
15//! and does not wrap another error. This is because we need to be able to
16//! construct I/O errors even when we cannot allocate.
17#[cfg(feature = "alloc")]
18mod bufreader;
19#[cfg(feature = "alloc")]
20mod bufwriter;
21mod cursor;
22mod embedded;
23mod error;
24mod impls;
25mod initializer;
26pub mod prelude;
27mod util;
28pub use self::cursor::Cursor;
29pub use self::error::{Error, ErrorKind, Result};
30pub use self::initializer::Initializer;
31pub use self::util::{Empty, Repeat, Sink, copy, empty, repeat, sink};
32#[cfg(feature = "alloc")]
33pub use bufreader::BufReader;
34#[cfg(feature = "alloc")]
35pub use bufwriter::BufWriter;
36use core::{cmp, fmt, slice, str};
37pub use embedded::FromEmbed;
38
39#[cfg(feature = "std")]
40mod std_io;
41#[cfg(feature = "std")]
42pub use std_io::ToStd;
43
44#[cfg(feature = "alloc")]
45use crate::alloc::{string::String, vec::Vec};
46#[cfg(feature = "alloc")]
47use crate::io::bufreader::BorrowedCursor;
48const DEFAULT_BUF_SIZE: usize = 256;
49
50/// The `Read` trait allows for reading bytes from a source.
51///
52/// Implementors of the `Read` trait are called 'readers'.
53///
54/// Readers are defined by one required method, [`read()`]. Each call to [`read()`]
55/// will attempt to pull bytes from this source into a provided buffer. A
56/// number of other methods are implemented in terms of [`read()`], giving
57/// implementors a number of ways to read bytes while only needing to implement
58/// a single method.
59///
60/// This is essentially a vendored version of the [`std::io::Read`] trait from
61/// the Rust standard library, modified to work without `std`. See the
62/// module-level docs for [`mycelium_util::io`] for more information on how
63/// `mycelium_util`'s `io` module differs from `std`'s.
64///
65/// [`read()`]: Self::read
66/// [`mycelium_util::io`]: crate::io
67pub trait Read {
68 /// Pull some bytes from this source into the specified buffer, returning
69 /// how many bytes were read.
70 ///
71 /// This function does not provide any guarantees about whether it blocks
72 /// waiting for data, but if an object needs to block for a read but cannot
73 /// it will typically signal this via an [`Err`] return value.
74 ///
75 /// If the return value of this method is [`Ok(n)`], then it must be
76 /// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates
77 /// that the buffer `buf` has been filled in with `n` bytes of data from this
78 /// source. If `n` is `0`, then it can indicate one of two scenarios:
79 ///
80 /// 1. This reader has reached its "end of file" and will likely no longer
81 /// be able to produce bytes. Note that this does not mean that the
82 /// reader will *always* no longer be able to produce bytes.
83 /// 2. The buffer specified was 0 bytes in length.
84 ///
85 /// No guarantees are provided about the contents of `buf` when this
86 /// function is called, implementations cannot rely on any property of the
87 /// contents of `buf` being true. It is recommended that *implementations*
88 /// only write data to `buf` instead of reading its contents.
89 ///
90 /// Correspondingly, however, *callers* of this method may not assume any guarantees
91 /// about how the implementation uses `buf`. The trait is safe to implement,
92 /// so it is possible that the code that's supposed to write to the buffer might also read
93 /// from it. It is your responsibility to make sure that `buf` is initialized
94 /// before calling `read`. Calling `read` with an uninitialized `buf` (of the kind one
95 /// obtains via [`MaybeUninit<T>`]) is not safe, and can lead to undefined behavior.
96 ///
97 /// [`MaybeUninit<T>`]: ../mem/union.MaybeUninit.html
98 ///
99 /// # Errors
100 ///
101 /// If this function encounters any form of I/O or other error, an error
102 /// variant will be returned. If an error is returned then it must be
103 /// guaranteed that no bytes were read.
104 ///
105 /// An error of the [`ErrorKind::Interrupted`] kind is non-fatal and the read
106 /// operation should be retried if there is nothing else to do.
107 fn read(&mut self, buf: &mut [u8]) -> Result<usize>;
108
109 /// Determines if this `Read`er can work with buffers of uninitialized
110 /// memory.
111 ///
112 /// The default implementation returns an initializer which will zero
113 /// buffers.
114 ///
115 /// If a `Read`er guarantees that it can work properly with uninitialized
116 /// memory, it should call [`Initializer::nop()`]. See the documentation for
117 /// [`Initializer`] for details.
118 ///
119 /// The behavior of this method must be independent of the state of the
120 /// `Read`er - the method only takes `&self` so that it can be used through
121 /// trait objects.
122 ///
123 /// # Safety
124 ///
125 /// This method is unsafe because a `Read`er could otherwise return a
126 /// non-zeroing `Initializer` from another `Read` type without an `unsafe`
127 /// block.
128 ///
129 /// [`Initializer::nop()`]: struct.Initializer.html#method.nop
130 /// [`Initializer`]: struct.Initializer.html
131 #[inline]
132 unsafe fn initializer(&self) -> Initializer {
133 Initializer::zeroing()
134 }
135
136 /// Read all bytes until EOF in this source, placing them into `buf`.
137 ///
138 /// All bytes read from this source will be appended to the specified buffer
139 /// `buf`. This function will continuously call [`read()`] to append more data to
140 /// `buf` until [`read()`] returns either \[`Ok(0)`\] or an error of
141 /// non-[`ErrorKind::Interrupted`] kind.
142 ///
143 /// If successful, this function will return the total number of bytes read.
144 ///
145 /// # Errors
146 ///
147 /// If this function encounters an error of the kind
148 /// [`ErrorKind::Interrupted`] then the error is ignored and the operation
149 /// will continue.
150 ///
151 /// If any other read error is encountered then this function immediately
152 /// returns. Any bytes which have already been read will be appended to
153 /// `buf`.
154 ///
155 /// [`read()`]: trait.Read.html#tymethod.read
156 /// [`ErrorKind::Interrupted`]: enum.ErrorKind.html#variant.Interrupted
157 #[cfg(feature = "alloc")]
158 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> {
159 read_to_end(self, buf)
160 }
161
162 #[cfg(feature = "alloc")]
163 fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<()> {
164 default_read_buf(|b| self.read(b), buf)
165 }
166
167 #[cfg(feature = "alloc")]
168 fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<()> {
169 default_read_buf_exact(self, cursor)
170 }
171
172 /// Read all bytes until EOF in this source, appending them to `buf`.
173 ///
174 /// If successful, this function returns the number of bytes which were read
175 /// and appended to `buf`.
176 ///
177 /// # Errors
178 ///
179 /// If the data in this stream is *not* valid UTF-8 then an error is
180 /// returned and `buf` is unchanged.
181 ///
182 /// See [`read_to_end`][readtoend] for other error semantics.
183 ///
184 /// [readtoend]: #method.read_to_end
185 #[cfg(feature = "alloc")]
186 fn read_to_string(&mut self, buf: &mut String) -> Result<usize> {
187 // Note that we do *not* call `.read_to_end()` here. We are passing
188 // `&mut Vec<u8>` (the raw contents of `buf`) into the `read_to_end`
189 // method to fill it up. An arbitrary implementation could overwrite the
190 // entire contents of the vector, not just append to it (which is what
191 // we are expecting).
192 //
193 // To prevent extraneously checking the UTF-8-ness of the entire buffer
194 // we pass it to our hardcoded `read_to_end` implementation which we
195 // know is guaranteed to only read data into the end of the buffer.
196 append_to_string(buf, |b| read_to_end(self, b))
197 }
198
199 /// Read the exact number of bytes required to fill `buf`.
200 ///
201 /// This function reads as many bytes as necessary to completely fill the
202 /// specified buffer `buf`.
203 ///
204 /// No guarantees are provided about the contents of `buf` when this
205 /// function is called, implementations cannot rely on any property of the
206 /// contents of `buf` being true. It is recommended that implementations
207 /// only write data to `buf` instead of reading its contents.
208 ///
209 /// # Errors
210 ///
211 /// If this function encounters an error of the kind
212 /// [`ErrorKind::Interrupted`] then the error is ignored and the operation
213 /// will continue.
214 ///
215 /// If this function encounters an "end of file" before completely filling
216 /// the buffer, it returns an error of the kind [`ErrorKind::UnexpectedEof`].
217 /// The contents of `buf` are unspecified in this case.
218 ///
219 /// If any other read error is encountered then this function immediately
220 /// returns. The contents of `buf` are unspecified in this case.
221 ///
222 /// If this function returns an error, it is unspecified how many bytes it
223 /// has read, but it will never read more than would be necessary to
224 /// completely fill the buffer.
225 ///
226 /// [`ErrorKind::Interrupted`]: enum.ErrorKind.html#variant.Interrupted
227 /// [`ErrorKind::UnexpectedEof`]: enum.ErrorKind.html#variant.UnexpectedEof
228 fn read_exact(&mut self, mut buf: &mut [u8]) -> Result<()> {
229 while !buf.is_empty() {
230 match self.read(buf) {
231 Ok(0) => break,
232 Ok(n) => {
233 let tmp = buf;
234 buf = &mut tmp[n..];
235 }
236 Err(ref e) if e.kind() == ErrorKind::Interrupted => {}
237 Err(e) => return Err(e),
238 }
239 }
240 if !buf.is_empty() {
241 Err(Error::new(
242 ErrorKind::UnexpectedEof,
243 "failed to fill whole buffer".into(),
244 ))
245 } else {
246 Ok(())
247 }
248 }
249
250 /// Creates a "by reference" adaptor for this instance of `Read`.
251 ///
252 /// The returned adaptor also implements `Read` and will simply borrow this
253 /// current reader.
254 fn by_ref(&mut self) -> &mut Self
255 where
256 Self: Sized,
257 {
258 self
259 }
260
261 /// Transforms this `Read` instance to an `Iterator` over its bytes.
262 ///
263 /// The returned type implements [`Iterator`] where the `Item` is
264 /// [`Result`]`<`[`u8`]`, `[`io::Error`]`>`.
265 /// The yielded item is [`Ok`] if a byte was successfully read and [`Err`]
266 /// otherwise. EOF is mapped to returning [`None`] from this iterator.
267 ///
268 /// [`Iterator`]: ../../std/iter/trait.Iterator.html
269 /// [`Result`]: ../../std/result/enum.Result.html
270 /// [`io::Error`]: ../../std/io/struct.Error.html
271 /// [`u8`]: ../../std/primitive.u8.html
272 /// [`Ok`]: ../../std/result/enum.Result.html#variant.Ok
273 /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
274 /// [`None`]: ../../std/option/enum.Option.html#variant.None
275 fn bytes(self) -> Bytes<Self>
276 where
277 Self: Sized,
278 {
279 Bytes { inner: self }
280 }
281
282 /// Creates an adaptor which will chain this stream with another.
283 ///
284 /// The returned `Read` instance will first read all bytes from this object
285 /// until EOF is encountered. Afterwards the output is equivalent to the
286 /// output of `next`.
287 ///
288 /// # Examples
289 ///
290 /// [`File`][file]s implement `Read`:
291 ///
292 /// [file]: ../fs/struct.File.html
293 ///
294 /// ```no_run
295 /// use std::io;
296 /// use std::io::prelude::*;
297 /// use std::fs::File;
298 ///
299 /// fn main() -> io::Result<()> {
300 /// let mut f1 = File::open("foo.txt")?;
301 /// let mut f2 = File::open("bar.txt")?;
302 ///
303 /// let mut handle = f1.chain(f2);
304 /// let mut buffer = String::new();
305 ///
306 /// // read the value into a String. We could use any Read method here,
307 /// // this is just one example.
308 /// handle.read_to_string(&mut buffer)?;
309 /// Ok(())
310 /// }
311 /// ```
312 fn chain<R: Read>(self, next: R) -> Chain<Self, R>
313 where
314 Self: Sized,
315 {
316 Chain {
317 first: self,
318 second: next,
319 done_first: false,
320 }
321 }
322
323 /// Creates an adaptor which will read at most `limit` bytes from it.
324 ///
325 /// This function returns a new instance of `Read` which will read at most
326 /// `limit` bytes, after which it will always return EOF (\[`Ok(0)`\]). Any
327 /// read errors will not count towards the number of bytes read and future
328 /// calls to [`read()`](Self::read) may succeed.
329 fn take(self, limit: u64) -> Take<Self>
330 where
331 Self: Sized,
332 {
333 Take { inner: self, limit }
334 }
335}
336
337pub(crate) fn default_read_buf<F>(read: F, mut cursor: BorrowedCursor<'_>) -> Result<()>
338where
339 F: FnOnce(&mut [u8]) -> Result<usize>,
340{
341 let n = read(cursor.ensure_init().init_mut())?;
342 cursor.advance(n);
343 Ok(())
344}
345
346pub(crate) fn default_read_buf_exact<R: Read + ?Sized>(
347 this: &mut R,
348 mut cursor: BorrowedCursor<'_>,
349) -> Result<()> {
350 while cursor.capacity() > 0 {
351 let prev_written = cursor.written();
352 match this.read_buf(cursor.reborrow()) {
353 Ok(()) => {}
354 Err(e) if e.kind() == ErrorKind::Interrupted => continue,
355 Err(e) => return Err(e),
356 }
357
358 if cursor.written() == prev_written {
359 return Err(Error::new(
360 ErrorKind::UnexpectedEof,
361 "failed to fill whole buffer".into(),
362 ));
363 }
364 }
365
366 Ok(())
367}
368
369/// A trait for objects which are byte-oriented sinks.
370///
371/// Implementors of the `Write` trait are sometimes called 'writers'.
372///
373/// Writers are defined by two required methods, [`write`] and [`flush`]:
374///
375/// * The [`write`] method will attempt to write some data into the object,
376/// returning how many bytes were successfully written.
377///
378/// * The [`flush`] method is useful for adapters and explicit buffers
379/// themselves for ensuring that all buffered data has been pushed out to the
380/// 'true sink'.
381///
382/// This is essentially a vendored version of the [`std::io::Write`] trait from
383/// the Rust standard library, modified to work without `std`. See the
384/// module-level docs for [`mycelium_util::io`] for more information on how
385/// `mycelium_util`'s `io` module differs from `std`'s.
386///
387/// [`write`]: Write::write
388/// [`flush`]: Write::flush
389/// [`mycelium_util::io`]: crate::io
390pub trait Write {
391 /// Write a buffer into this writer, returning how many bytes were written.
392 ///
393 /// This function will attempt to write the entire contents of `buf`, but
394 /// the entire write may not succeed, or the write may also generate an
395 /// error. A call to `write` represents *at most one* attempt to write to
396 /// any wrapped object.
397 ///
398 /// Calls to `write` are not guaranteed to block waiting for data to be
399 /// written, and a write which would otherwise block can be indicated through
400 /// an [`Err`] variant.
401 ///
402 /// If the return value is [`Ok(n)`] then it must be guaranteed that
403 /// `n <= buf.len()`. A return value of `0` typically means that the
404 /// underlying object is no longer able to accept bytes and will likely not
405 /// be able to in the future as well, or that the buffer provided is empty.
406 ///
407 /// # Errors
408 ///
409 /// Each call to `write` may generate an I/O error indicating that the
410 /// operation could not be completed. If an error is returned then no bytes
411 /// in the buffer were written to this writer.
412 ///
413 /// It is **not** considered an error if the entire buffer could not be
414 /// written to this writer.
415 ///
416 /// An error of the [`ErrorKind::Interrupted`] kind is non-fatal and the
417 /// write operation should be retried if there is nothing else to do.
418 ///
419 /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
420 /// [`Ok(n)`]: ../../std/result/enum.Result.html#variant.Ok
421 fn write(&mut self, buf: &[u8]) -> Result<usize>;
422
423 /// Flush this output stream, ensuring that all intermediately buffered
424 /// contents reach their destination.
425 fn flush(&mut self) -> Result<()>;
426
427 /// Attempts to write an entire buffer into this writer.
428 ///
429 /// This method will continuously call [`write`] until there is no more data
430 /// to be written or an error of non-[`ErrorKind::Interrupted`] kind is
431 /// returned. This method will not return until the entire buffer has been
432 /// successfully written or such an error occurs. The first error that is
433 /// not of [`ErrorKind::Interrupted`] kind generated from this method will be
434 /// returned.
435 ///
436 /// # Errors
437 ///
438 /// This function will return the first error of
439 /// non-[`ErrorKind::Interrupted`] kind that [`write`] returns.
440 ///
441 /// [`write`]: #tymethod.write
442 fn write_all(&mut self, mut buf: &[u8]) -> Result<()> {
443 while !buf.is_empty() {
444 match self.write(buf) {
445 Ok(0) => {
446 return Err(Error::new(
447 ErrorKind::WriteZero,
448 "failed to write whole buffer".into(),
449 ));
450 }
451 Ok(n) => buf = &buf[n..],
452 Err(ref e) if e.kind() == ErrorKind::Interrupted => {}
453 Err(e) => return Err(e),
454 }
455 }
456 Ok(())
457 }
458
459 /// Writes a formatted string into this writer, returning any error
460 /// encountered.
461 ///
462 /// This method is primarily used to interface with the
463 /// [`format_args!`][formatargs] macro, but it is rare that this should
464 /// explicitly be called. The [`write!`][write] macro should be favored to
465 /// invoke this method instead.
466 ///
467 /// [formatargs]: ../macro.format_args.html
468 /// [write]: ../macro.write.html
469 ///
470 /// This function internally uses the [`write_all`][writeall] method on
471 /// this trait and hence will continuously write data so long as no errors
472 /// are received. This also means that partial writes are not indicated in
473 /// this signature.
474 ///
475 /// [writeall]: #method.write_all
476 ///
477 /// # Errors
478 ///
479 /// This function will return any I/O error reported while formatting.
480 fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> Result<()> {
481 let mut output = WriteFmtAdaptor::new(self);
482 match fmt::write(&mut output, fmt) {
483 Ok(()) => Ok(()),
484 Err(..) => {
485 // check if the error came from the underlying `Write` or not
486 if output.error.is_err() {
487 output.error
488 } else {
489 Err(Error::new(ErrorKind::Other, "formatter error".into()))
490 }
491 }
492 }
493 }
494
495 /// Creates a "by reference" adaptor for this instance of `Write`.
496 ///
497 /// The returned adaptor also implements `Write` and will simply borrow this
498 /// current writer.
499 fn by_ref(&mut self) -> &mut Self
500 where
501 Self: Sized,
502 {
503 self
504 }
505}
506
507/// The `Seek` trait provides a cursor which can be moved within a stream of
508/// bytes.
509///
510/// The stream typically has a fixed size, allowing seeking relative to either
511/// end or the current offset.
512pub trait Seek {
513 /// Seek to an offset, in bytes, in a stream.
514 ///
515 /// A seek beyond the end of a stream is allowed, but behavior is defined
516 /// by the implementation.
517 ///
518 /// If the seek operation completed successfully,
519 /// this method returns the new position from the start of the stream.
520 /// That position can be used later with [`SeekFrom::Start`].
521 ///
522 /// # Errors
523 ///
524 /// Seeking to a negative offset is considered an error.
525 ///
526 /// [`SeekFrom::Start`]: enum.SeekFrom.html#variant.Start
527 fn seek(&mut self, pos: SeekFrom) -> Result<u64>;
528
529 /// Returns the length of this stream (in bytes).
530 ///
531 /// This method is implemented using up to three seek operations. If this
532 /// method returns successfully, the seek position is unchanged (i.e. the
533 /// position before calling this method is the same as afterwards).
534 /// However, if this method returns an error, the seek position is
535 /// unspecified.
536 ///
537 /// If you need to obtain the length of *many* streams and you don't care
538 /// about the seek position afterwards, you can reduce the number of seek
539 /// operations by simply calling `seek(SeekFrom::End(0))` and using its
540 /// return value (it is also the stream length).
541 ///
542 /// Note that length of a stream can change over time (for example, when
543 /// data is appended to a file). So calling this method multiple times does
544 /// not necessarily return the same length each time.
545 fn stream_len(&mut self) -> Result<u64> {
546 let old_pos = self.stream_position()?;
547 let len = self.seek(SeekFrom::End(0))?;
548
549 // Avoid seeking a third time when we were already at the end of the
550 // stream. The branch is usually way cheaper than a seek operation.
551 if old_pos != len {
552 self.seek(SeekFrom::Start(old_pos))?;
553 }
554
555 Ok(len)
556 }
557
558 /// Returns the current seek position from the start of the stream.
559 ///
560 /// This is equivalent to `self.seek(SeekFrom::Current(0))`.
561 fn stream_position(&mut self) -> Result<u64> {
562 self.seek(SeekFrom::Current(0))
563 }
564}
565
566/// A `BufRead` is a type of `Read`er which has an internal buffer, allowing it
567/// to perform extra ways of reading.
568///
569/// For example, reading line-by-line is inefficient without using a buffer, so
570/// if you want to read by line, you'll need `BufRead`, which includes a
571/// [`read_line`] method as well as a [`lines`] iterator.
572///
573/// [`BufReader`]: struct.BufReader.html
574/// [`read_line`]: #method.read_line
575/// [`lines`]: #method.lines
576/// [`Read`]: trait.Read.html
577pub trait BufRead: Read {
578 /// Returns the contents of the internal buffer, filling it with more data
579 /// from the inner reader if it is empty.
580 ///
581 /// This function is a lower-level call. It needs to be paired with the
582 /// [`consume`] method to function properly. When calling this
583 /// method, none of the contents will be "read" in the sense that later
584 /// calling `read` may return the same contents. As such, [`consume`] must
585 /// be called with the number of bytes that are consumed from this buffer to
586 /// ensure that the bytes are never returned twice.
587 ///
588 /// [`consume`]: Self::consume
589 ///
590 /// An empty buffer returned indicates that the stream has reached EOF.
591 ///
592 /// # Errors
593 ///
594 /// This function will return an I/O error if the underlying reader was
595 /// read, but returned an error.
596 fn fill_buf(&mut self) -> Result<&[u8]>;
597
598 /// Tells this buffer that `amt` bytes have been consumed from the buffer,
599 /// so they should no longer be returned in calls to `read`.
600 ///
601 /// This function is a lower-level call. It needs to be paired with the
602 /// [`fill_buf`] method to function properly. This function does
603 /// not perform any I/O, it simply informs this object that some amount of
604 /// its buffer, returned from [`fill_buf`], has been consumed and should
605 /// no longer be returned. As such, this function may do odd things if
606 /// [`fill_buf`] isn't called before calling it.
607 ///
608 /// The `amt` must be `<=` the number of bytes in the buffer returned by
609 /// [`fill_buf`].
610 ///
611 /// [`fill_buf`]: Self::fill_buf
612 fn consume(&mut self, amt: usize);
613
614 /// Read all bytes into `buf` until the delimiter `byte` or EOF is reached.
615 ///
616 /// This function will read bytes from the underlying stream until the
617 /// delimiter or EOF is found. Once found, all bytes up to, and including,
618 /// the delimiter (if found) will be appended to `buf`.
619 ///
620 /// If successful, this function will return the total number of bytes read.
621 ///
622 /// # Errors
623 ///
624 /// This function will ignore all instances of [`ErrorKind::Interrupted`] and
625 /// will otherwise return any errors returned by [`fill_buf`].
626 ///
627 /// If an I/O error is encountered then all bytes read so far will be
628 /// present in `buf` and its length will have been adjusted appropriately.
629 ///
630 /// [`fill_buf`]: Self::fill_buf
631 #[cfg(feature = "alloc")]
632 fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize> {
633 read_until(self, byte, buf)
634 }
635
636 /// Read all bytes until a newline (the 0xA byte) is reached, and append
637 /// them to the provided buffer.
638 ///
639 /// This function will read bytes from the underlying stream until the
640 /// newline delimiter (the 0xA byte) or EOF is found. Once found, all bytes
641 /// up to, and including, the delimiter (if found) will be appended to
642 /// `buf`.
643 ///
644 /// If successful, this function will return the total number of bytes read.
645 ///
646 /// If this function returns `Ok(0)`, the stream has reached EOF.
647 ///
648 /// # Errors
649 ///
650 /// This function has the same error semantics as [`read_until`] and will
651 /// also return an error if the read bytes are not valid UTF-8. If an I/O
652 /// error is encountered then `buf` may contain some bytes already read in
653 /// the event that all data read so far was valid UTF-8.
654 ///
655 /// [`read_until`]: Self::read_until
656 #[cfg(feature = "alloc")]
657 fn read_line(&mut self, buf: &mut String) -> Result<usize> {
658 // Note that we are not calling the `.read_until` method here, but
659 // rather our hardcoded implementation. For more details as to why, see
660 // the comments in `read_to_end`.
661 append_to_string(buf, |b| read_until(self, b'\n', b))
662 }
663
664 /// Returns an iterator over the contents of this reader split on the byte
665 /// `byte`.
666 ///
667 /// The iterator returned from this function will return instances of
668 /// [`io::Result`]`<`[`Vec<u8>`]`>`. Each vector returned will *not* have
669 /// the delimiter byte at the end.
670 ///
671 /// This function will yield errors whenever [`read_until`] would have
672 /// also yielded an error.
673 ///
674 /// [`io::Result`]: type.Result.html
675 /// [`Vec<u8>`]: ...alloc/vec/struct.Vec.html
676 /// [`read_until`]: #method.read_until
677 #[cfg(feature = "alloc")]
678 fn split(self, byte: u8) -> Split<Self>
679 where
680 Self: Sized,
681 {
682 Split {
683 buf: self,
684 delim: byte,
685 }
686 }
687
688 /// Returns an iterator over the lines of this reader.
689 ///
690 /// The iterator returned from this function will yield instances of
691 /// [`io::Result`]`<`[`String`]`>`. Each string returned will *not* have a newline
692 /// byte (the 0xA byte) or CRLF (0xD, 0xA bytes) at the end.
693 ///
694 /// [`io::Result`]: type.Result.html
695 /// [`String`]: ../string/struct.String.html
696 ///
697 /// # Errors
698 ///
699 /// Each line of the iterator has the same error semantics as [`BufRead::read_line`].
700 ///
701 /// [`BufRead::read_line`]: trait.BufRead.html#method.read_line
702 #[cfg(feature = "alloc")]
703 fn lines(self) -> Lines<Self>
704 where
705 Self: Sized,
706 {
707 Lines { buf: self }
708 }
709}
710
711/// Enumeration of possible methods to seek within an I/O object.
712///
713/// It is used by the [`Seek`] trait.
714///
715/// [`Seek`]: trait.Seek.html
716#[derive(Copy, PartialEq, Eq, Clone, Debug)]
717pub enum SeekFrom {
718 /// Sets the offset to the provided number of bytes.
719 Start(u64),
720
721 /// Sets the offset to the size of this object plus the specified number of
722 /// bytes.
723 ///
724 /// It is possible to seek beyond the end of an object, but it's an error to
725 /// seek before byte 0.
726 End(i64),
727
728 /// Sets the offset to the current position plus the specified number of
729 /// bytes.
730 ///
731 /// It is possible to seek beyond the end of an object, but it's an error to
732 /// seek before byte 0.
733 Current(i64),
734}
735
736/// Adaptor to chain together two readers.
737///
738/// This struct is generally created by calling [`chain`] on a reader.
739/// Please see the documentation of [`chain`] for more details.
740///
741/// [`chain`]: trait.Read.html#method.chain
742pub struct Chain<T, U> {
743 first: T,
744 second: U,
745 done_first: bool,
746}
747
748impl<T, U> Chain<T, U> {
749 /// Consumes the `Chain`, returning the wrapped readers.
750 pub fn into_inner(self) -> (T, U) {
751 (self.first, self.second)
752 }
753
754 /// Gets references to the underlying readers in this `Chain`.
755 pub fn get_ref(&self) -> (&T, &U) {
756 (&self.first, &self.second)
757 }
758
759 /// Gets mutable references to the underlying readers in this `Chain`.
760 ///
761 /// Care should be taken to avoid modifying the internal I/O state of the
762 /// underlying readers as doing so may corrupt the internal state of this
763 /// `Chain`.
764 pub fn get_mut(&mut self) -> (&mut T, &mut U) {
765 (&mut self.first, &mut self.second)
766 }
767}
768
769impl<T: fmt::Debug, U: fmt::Debug> fmt::Debug for Chain<T, U> {
770 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
771 f.debug_struct("Chain")
772 .field("t", &self.first)
773 .field("u", &self.second)
774 .finish()
775 }
776}
777
778impl<T: Read, U: Read> Read for Chain<T, U> {
779 fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
780 if !self.done_first {
781 match self.first.read(buf)? {
782 0 if !buf.is_empty() => self.done_first = true,
783 n => return Ok(n),
784 }
785 }
786 self.second.read(buf)
787 }
788}
789
790impl<T: BufRead, U: BufRead> BufRead for Chain<T, U> {
791 fn fill_buf(&mut self) -> Result<&[u8]> {
792 if !self.done_first {
793 match self.first.fill_buf()? {
794 &[] => self.done_first = true,
795 buf => return Ok(buf),
796 }
797 }
798 self.second.fill_buf()
799 }
800
801 fn consume(&mut self, amt: usize) {
802 if !self.done_first {
803 self.first.consume(amt)
804 } else {
805 self.second.consume(amt)
806 }
807 }
808}
809
810/// Reader adaptor which limits the bytes read from an underlying reader.
811///
812/// This struct is generally created by calling [`take`] on a reader.
813/// Please see the documentation of [`take`] for more details.
814///
815/// [`take`]: trait.Read.html#method.take
816#[derive(Debug)]
817pub struct Take<T> {
818 inner: T,
819 limit: u64,
820}
821
822impl<T> Take<T> {
823 /// Returns the number of bytes that can be read before this instance will
824 /// return EOF.
825 ///
826 /// # Note
827 ///
828 /// This instance may reach `EOF` after reading fewer bytes than indicated by
829 /// this method if the underlying [`Read`] instance reaches EOF.
830 ///
831 /// [`Read`]:trait.Read.html
832 pub fn limit(&self) -> u64 {
833 self.limit
834 }
835
836 /// Sets the number of bytes that can be read before this instance will
837 /// return EOF. This is the same as constructing a new `Take` instance, so
838 /// the amount of bytes read and the previous limit value don't matter when
839 /// calling this method.
840 pub fn set_limit(&mut self, limit: u64) {
841 self.limit = limit;
842 }
843
844 /// Consumes the `Take`, returning the wrapped reader.
845 pub fn into_inner(self) -> T {
846 self.inner
847 }
848
849 /// Gets a reference to the underlying reader.
850 pub fn get_ref(&self) -> &T {
851 &self.inner
852 }
853
854 /// Gets a mutable reference to the underlying reader.
855 ///
856 /// Care should be taken to avoid modifying the internal I/O state of the
857 /// underlying reader as doing so may corrupt the internal limit of this
858 /// `Take`.
859 pub fn get_mut(&mut self) -> &mut T {
860 &mut self.inner
861 }
862}
863
864impl<T: Read> Read for Take<T> {
865 fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
866 // Don't call into inner reader at all at EOF because it may still block
867 if self.limit == 0 {
868 return Ok(0);
869 }
870
871 let max = cmp::min(buf.len() as u64, self.limit) as usize;
872 let n = self.inner.read(&mut buf[..max])?;
873 self.limit -= n as u64;
874 Ok(n)
875 }
876
877 #[cfg(feature = "alloc")]
878 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> {
879 // Pass in a reservation_size closure that respects the current value
880 // of limit for each read. If we hit the read limit, this prevents the
881 // final zero-byte read from allocating again.
882 read_to_end_with_reservation(self, buf, |self_| cmp::min(self_.limit, 32) as usize)
883 }
884}
885
886impl<T: BufRead> BufRead for Take<T> {
887 fn fill_buf(&mut self) -> Result<&[u8]> {
888 // Don't call into inner reader at all at EOF because it may still block
889 if self.limit == 0 {
890 return Ok(&[]);
891 }
892
893 let buf = self.inner.fill_buf()?;
894 let cap = cmp::min(buf.len() as u64, self.limit) as usize;
895 Ok(&buf[..cap])
896 }
897
898 fn consume(&mut self, amt: usize) {
899 // Don't let callers reset the limit by passing an overlarge value
900 let amt = cmp::min(amt as u64, self.limit) as usize;
901 self.limit -= amt as u64;
902 self.inner.consume(amt);
903 }
904}
905
906/// An iterator over `u8` values of a reader.
907///
908/// This struct is generally created by calling [`bytes`] on a reader.
909/// Please see the documentation of [`bytes`] for more details.
910///
911/// [`bytes`]: trait.Read.html#method.bytes
912#[derive(Debug)]
913pub struct Bytes<R> {
914 inner: R,
915}
916
917impl<R: Read> Iterator for Bytes<R> {
918 type Item = Result<u8>;
919
920 fn next(&mut self) -> Option<Result<u8>> {
921 let mut byte = 0;
922 loop {
923 return match self.inner.read(slice::from_mut(&mut byte)) {
924 Ok(0) => None,
925 Ok(..) => Some(Ok(byte)),
926 Err(ref e) if e.kind() == ErrorKind::Interrupted => continue,
927 Err(e) => Some(Err(e)),
928 };
929 }
930 }
931}
932
933/// An iterator over the contents of an instance of `BufRead` split on a
934/// particular byte.
935///
936/// This struct is generally created by calling [`split`] on a `BufRead`.
937/// Please see the documentation of [`split`] for more details.
938///
939/// [`split`]: trait.BufRead.html#method.split
940#[cfg(feature = "alloc")]
941#[derive(Debug)]
942pub struct Split<B> {
943 buf: B,
944 delim: u8,
945}
946
947#[cfg(feature = "alloc")]
948impl<B: BufRead> Iterator for Split<B> {
949 type Item = Result<Vec<u8>>;
950
951 fn next(&mut self) -> Option<Result<Vec<u8>>> {
952 let mut buf = Vec::new();
953 match self.buf.read_until(self.delim, &mut buf) {
954 Ok(0) => None,
955 Ok(_n) => {
956 if buf[buf.len() - 1] == self.delim {
957 buf.pop();
958 }
959 Some(Ok(buf))
960 }
961 Err(e) => Some(Err(e)),
962 }
963 }
964}
965
966/// An iterator over the lines of an instance of `BufRead`.
967///
968/// This struct is generally created by calling [`lines`] on a `BufRead`.
969/// Please see the documentation of [`lines`] for more details.
970///
971/// [`lines`]: trait.BufRead.html#method.lines
972#[cfg(feature = "alloc")]
973#[derive(Debug)]
974pub struct Lines<B> {
975 buf: B,
976}
977
978#[cfg(feature = "alloc")]
979impl<B: BufRead> Iterator for Lines<B> {
980 type Item = Result<String>;
981
982 fn next(&mut self) -> Option<Result<String>> {
983 let mut buf = String::new();
984 match self.buf.read_line(&mut buf) {
985 Ok(0) => None,
986 Ok(_n) => {
987 if buf.ends_with('\n') {
988 buf.pop();
989 if buf.ends_with('\r') {
990 buf.pop();
991 }
992 }
993 Some(Ok(buf))
994 }
995 Err(e) => Some(Err(e)),
996 }
997 }
998}
999
1000// This uses an adaptive system to extend the vector when it fills. We want to
1001// avoid paying to allocate and zero a huge chunk of memory if the reader only
1002// has 4 bytes while still making large reads if the reader does have a ton
1003// of data to return. Simply tacking on an extra DEFAULT_BUF_SIZE space every
1004// time is 4,500 times (!) slower than a default reservation size of 32 if the
1005// reader has a very small amount of data to return.
1006//
1007// Because we're extending the buffer with uninitialized data for trusted
1008// readers, we need to make sure to truncate that if any of this panics.
1009#[cfg(feature = "alloc")]
1010fn read_to_end<R: Read + ?Sized>(r: &mut R, buf: &mut Vec<u8>) -> Result<usize> {
1011 read_to_end_with_reservation(r, buf, |_| 32)
1012}
1013
1014#[cfg(feature = "alloc")]
1015fn read_to_end_with_reservation<R, F>(
1016 r: &mut R,
1017 buf: &mut Vec<u8>,
1018 mut reservation_size: F,
1019) -> Result<usize>
1020where
1021 R: Read + ?Sized,
1022 F: FnMut(&R) -> usize,
1023{
1024 let start_len = buf.len();
1025 let mut g = Guard {
1026 len: buf.len(),
1027 buf,
1028 };
1029 let ret;
1030 loop {
1031 if g.len == g.buf.len() {
1032 unsafe {
1033 // FIXME(danielhenrymantilla): #42788
1034 //
1035 // - This creates a (mut) reference to a slice of
1036 // _uninitialized_ integers, which is **undefined behavior**
1037 //
1038 // - Only the standard library gets to soundly "ignore" this,
1039 // based on its privileged knowledge of unstable rustc
1040 // internals;
1041 g.buf.reserve(reservation_size(r));
1042 let capacity = g.buf.capacity();
1043 g.buf.set_len(capacity);
1044 r.initializer().initialize(&mut g.buf[g.len..]);
1045 }
1046 }
1047
1048 match r.read(&mut g.buf[g.len..]) {
1049 Ok(0) => {
1050 ret = Ok(g.len - start_len);
1051 break;
1052 }
1053 Ok(n) => g.len += n,
1054 Err(ref e) if e.kind() == ErrorKind::Interrupted => {}
1055 Err(e) => {
1056 ret = Err(e);
1057 break;
1058 }
1059 }
1060 }
1061
1062 ret
1063}
1064
1065#[cfg(feature = "alloc")]
1066struct Guard<'a> {
1067 buf: &'a mut Vec<u8>,
1068 len: usize,
1069}
1070
1071#[cfg(feature = "alloc")]
1072impl Drop for Guard<'_> {
1073 fn drop(&mut self) {
1074 unsafe {
1075 self.buf.set_len(self.len);
1076 }
1077 }
1078}
1079
1080// A few methods below (read_to_string, read_line) will append data into a
1081// `String` buffer, but we need to be pretty careful when doing this. The
1082// implementation will just call `.as_mut_vec()` and then delegate to a
1083// byte-oriented reading method, but we must ensure that when returning we never
1084// leave `buf` in a state such that it contains invalid UTF-8 in its bounds.
1085//
1086// To this end, we use an RAII guard (to protect against panics) which updates
1087// the length of the string when it is dropped. This guard initially truncates
1088// the string to the prior length and only after we've validated that the
1089// new contents are valid UTF-8 do we allow it to set a longer length.
1090//
1091// The unsafety in this function is twofold:
1092//
1093// 1. We're looking at the raw bytes of `buf`, so we take on the burden of UTF-8
1094// checks.
1095// 2. We're passing a raw buffer to the function `f`, and it is expected that
1096// the function only *appends* bytes to the buffer. We'll get undefined
1097// behavior if existing bytes are overwritten to have non-UTF-8 data.
1098#[cfg(feature = "alloc")]
1099fn append_to_string<F>(buf: &mut String, f: F) -> Result<usize>
1100where
1101 F: FnOnce(&mut Vec<u8>) -> Result<usize>,
1102{
1103 unsafe {
1104 let mut g = Guard {
1105 len: buf.len(),
1106 buf: buf.as_mut_vec(),
1107 };
1108 let ret = f(g.buf);
1109 if str::from_utf8(&g.buf[g.len..]).is_err() {
1110 ret.and_then(|_| {
1111 Err(Error::new(
1112 ErrorKind::InvalidData,
1113 "stream did not contain valid UTF-8".into(),
1114 ))
1115 })
1116 } else {
1117 g.len = g.buf.len();
1118 ret
1119 }
1120 }
1121}
1122
1123#[cfg(feature = "alloc")]
1124fn read_until<R: BufRead + ?Sized>(r: &mut R, delim: u8, buf: &mut Vec<u8>) -> Result<usize> {
1125 let mut read = 0;
1126 loop {
1127 let (done, used) = {
1128 let available = match r.fill_buf() {
1129 Ok(n) => n,
1130 Err(ref e) if e.kind() == ErrorKind::Interrupted => continue,
1131 Err(e) => return Err(e),
1132 };
1133 // This is intentionally simple. We may improve upon it in the future with a
1134 // proper `memchr` implementation if it proves to be necessary.
1135 match available.iter().position(|&c| c == delim) {
1136 Some(i) => {
1137 buf.extend_from_slice(&available[..=i]);
1138 (true, i + 1)
1139 }
1140 None => {
1141 buf.extend_from_slice(available);
1142 (false, available.len())
1143 }
1144 }
1145 };
1146 r.consume(used);
1147 read += used;
1148 if done || used == 0 {
1149 return Ok(read);
1150 }
1151 }
1152}
1153
1154// Create a shim which translates a Write to a fmt::Write and saves
1155// off I/O errors. instead of discarding them
1156pub(crate) struct WriteFmtAdaptor<'a, T: ?Sized + 'a> {
1157 inner: &'a mut T,
1158 error: Result<()>,
1159}
1160
1161impl<'a, T: ?Sized + 'a> WriteFmtAdaptor<'a, T> {
1162 pub(crate) fn new(inner: &'a mut T) -> Self {
1163 Self {
1164 inner,
1165 error: Ok(()),
1166 }
1167 }
1168}
1169
1170impl<T: Write + ?Sized> fmt::Write for WriteFmtAdaptor<'_, T> {
1171 fn write_str(&mut self, s: &str) -> fmt::Result {
1172 match self.inner.write_all(s.as_bytes()) {
1173 Ok(()) => Ok(()),
1174 Err(e) => {
1175 self.error = Err(e);
1176 Err(fmt::Error)
1177 }
1178 }
1179 }
1180}