util.rs - source
Description: Source of the Rust file `library/std/src/io/util.rs`.

#
std/io/
util.rs

    1#![allow(missing_copy_implementations)]
    2
    3#[cfg(test)]
    4mod tests;
    5
    6use crate::fmt;
    7use crate::io::{
    8    self, BorrowedCursor, BufRead, IoSlice, IoSliceMut, Read, Seek, SeekFrom, SizeHint, Write,
    9};
    10
    11/// `Empty` ignores any data written via [`Write`], and will always be empty
    12/// (returning zero bytes) when read via [`Read`].
    13///
    14/// This struct is generally created by calling [`empty()`]. Please
    15/// see the documentation of [`empty()`] for more details.
    16#[stable(feature = "rust1", since = "1.0.0")]
    17#[non_exhaustive]
    18#[derive(Copy, Clone, Debug, Default)]
    19pub struct Empty;
    20
    21/// Creates a value that is always at EOF for reads, and ignores all data written.
    22///
    23/// All calls to [`write`] on the returned instance will return [`Ok(buf.len())`]
    24/// and the contents of the buffer will not be inspected.
    25///
    26/// All calls to [`read`] from the returned reader will return [`Ok(0)`].
    27///
    28/// [`Ok(buf.len())`]: Ok
    29/// [`Ok(0)`]: Ok
    30///
    31/// [`write`]: Write::write
    32/// [`read`]: Read::read
    33///
    34/// # Examples
    35///
    36/// ```rust
    37/// use std::io::{self, Write};
    38///
    39/// let buffer = vec![1, 2, 3, 5, 8];
    40/// let num_bytes = io::empty().write(&buffer).unwrap();
    41/// assert_eq!(num_bytes, 5);
    42/// ```
    43///
    44///
    45/// ```rust
    46/// use std::io::{self, Read};
    47///
    48/// let mut buffer = String::new();
    49/// io::empty().read_to_string(&mut buffer).unwrap();
    50/// assert!(buffer.is_empty());
    51/// ```
    52#[must_use]
    53#[stable(feature = "rust1", since = "1.0.0")]
    54#[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")]
    55pub const fn empty() -> Empty {
    56    Empty
    57}
    58
    59#[stable(feature = "rust1", since = "1.0.0")]
    60impl Read for Empty {
    61    #[inline]
    62    fn read(&mut self, _buf: &mut [u8]) -> io::Result<usize> {
    63        Ok(0)
    64    }
    65
    66    #[inline]
    67    fn read_buf(&mut self, _cursor: BorrowedCursor<'_>) -> io::Result<()> {
    68        Ok(())
    69    }
    70
    71    #[inline]
    72    fn read_vectored(&mut self, _bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
    73        Ok(0)
    74    }
    75
    76    #[inline]
    77    fn is_read_vectored(&self) -> bool {
    78        // Do not force `Chain<Empty, T>` or `Chain<T, Empty>` to use vectored
    79        // reads, unless the other reader is vectored.
    80        false
    81    }
    82
    83    #[inline]
    84    fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
    85        if !buf.is_empty() { Err(io::Error::READ_EXACT_EOF) } else { Ok(()) }
    86    }
    87
    88    #[inline]
    89    fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> {
    90        if cursor.capacity() != 0 { Err(io::Error::READ_EXACT_EOF) } else { Ok(()) }
    91    }
    92
    93    #[inline]
    94    fn read_to_end(&mut self, _buf: &mut Vec<u8>) -> io::Result<usize> {
    95        Ok(0)
    96    }
    97
    98    #[inline]
    99    fn read_to_string(&mut self, _buf: &mut String) -> io::Result<usize> {
    100        Ok(0)
    101    }
    102}
    103#[stable(feature = "rust1", since = "1.0.0")]
    104impl BufRead for Empty {
    105    #[inline]
    106    fn fill_buf(&mut self) -> io::Result<&[u8]> {
    107        Ok(&[])
    108    }
    109
    110    #[inline]
    111    fn consume(&mut self, _n: usize) {}
    112
    113    #[inline]
    114    fn has_data_left(&mut self) -> io::Result<bool> {
    115        Ok(false)
    116    }
    117
    118    #[inline]
    119    fn read_until(&mut self, _byte: u8, _buf: &mut Vec<u8>) -> io::Result<usize> {
    120        Ok(0)
    121    }
    122
    123    #[inline]
    124    fn skip_until(&mut self, _byte: u8) -> io::Result<usize> {
    125        Ok(0)
    126    }
    127
    128    #[inline]
    129    fn read_line(&mut self, _buf: &mut String) -> io::Result<usize> {
    130        Ok(0)
    131    }
    132}
    133
    134#[stable(feature = "empty_seek", since = "1.51.0")]
    135impl Seek for Empty {
    136    #[inline]
    137    fn seek(&mut self, _pos: SeekFrom) -> io::Result<u64> {
    138        Ok(0)
    139    }
    140
    141    #[inline]
    142    fn stream_len(&mut self) -> io::Result<u64> {
    143        Ok(0)
    144    }
    145
    146    #[inline]
    147    fn stream_position(&mut self) -> io::Result<u64> {
    148        Ok(0)
    149    }
    150}
    151
    152impl SizeHint for Empty {
    153    #[inline]
    154    fn upper_bound(&self) -> Option<usize> {
    155        Some(0)
    156    }
    157}
    158
    159#[stable(feature = "empty_write", since = "1.73.0")]
    160impl Write for Empty {
    161    #[inline]
    162    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
    163        Ok(buf.len())
    164    }
    165
    166    #[inline]
    167    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
    168        let total_len = bufs.iter().map(|b| b.len()).sum();
    169        Ok(total_len)
    170    }
    171
    172    #[inline]
    173    fn is_write_vectored(&self) -> bool {
    174        true
    175    }
    176
    177    #[inline]
    178    fn write_all(&mut self, _buf: &[u8]) -> io::Result<()> {
    179        Ok(())
    180    }
    181
    182    #[inline]
    183    fn write_all_vectored(&mut self, _bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
    184        Ok(())
    185    }
    186
    187    #[inline]
    188    fn write_fmt(&mut self, _args: fmt::Arguments<'_>) -> io::Result<()> {
    189        Ok(())
    190    }
    191
    192    #[inline]
    193    fn flush(&mut self) -> io::Result<()> {
    194        Ok(())
    195    }
    196}
    197
    198#[stable(feature = "empty_write", since = "1.73.0")]
    199impl Write for &Empty {
    200    #[inline]
    201    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
    202        Ok(buf.len())
    203    }
    204
    205    #[inline]
    206    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
    207        let total_len = bufs.iter().map(|b| b.len()).sum();
    208        Ok(total_len)
    209    }
    210
    211    #[inline]
    212    fn is_write_vectored(&self) -> bool {
    213        true
    214    }
    215
    216    #[inline]
    217    fn write_all(&mut self, _buf: &[u8]) -> io::Result<()> {
    218        Ok(())
    219    }
    220
    221    #[inline]
    222    fn write_all_vectored(&mut self, _bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
    223        Ok(())
    224    }
    225
    226    #[inline]
    227    fn write_fmt(&mut self, _args: fmt::Arguments<'_>) -> io::Result<()> {
    228        Ok(())
    229    }
    230
    231    #[inline]
    232    fn flush(&mut self) -> io::Result<()> {
    233        Ok(())
    234    }
    235}
    236
    237/// A reader which yields one byte over and over and over and over and over and...
    238///
    239/// This struct is generally created by calling [`repeat()`]. Please
    240/// see the documentation of [`repeat()`] for more details.
    241#[stable(feature = "rust1", since = "1.0.0")]
    242pub struct Repeat {
    243    byte: u8,
    244}
    245
    246/// Creates an instance of a reader that infinitely repeats one byte.
    247///
    248/// All reads from this reader will succeed by filling the specified buffer with
    249/// the given byte.
    250///
    251/// # Examples
    252///
    253/// ```
    254/// use std::io::{self, Read};
    255///
    256/// let mut buffer = [0; 3];
    257/// io::repeat(0b101).read_exact(&mut buffer).unwrap();
    258/// assert_eq!(buffer, [0b101, 0b101, 0b101]);
    259/// ```
    260#[must_use]
    261#[stable(feature = "rust1", since = "1.0.0")]
    262#[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")]
    263pub const fn repeat(byte: u8) -> Repeat {
    264    Repeat { byte }
    265}
    266
    267#[stable(feature = "rust1", since = "1.0.0")]
    268impl Read for Repeat {
    269    #[inline]
    270    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
    271        buf.fill(self.byte);
    272        Ok(buf.len())
    273    }
    274
    275    #[inline]
    276    fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
    277        buf.fill(self.byte);
    278        Ok(())
    279    }
    280
    281    #[inline]
    282    fn read_buf(&mut self, mut buf: BorrowedCursor<'_>) -> io::Result<()> {
    283        // SAFETY: No uninit bytes are being written.
    284        unsafe { buf.as_mut() }.write_filled(self.byte);
    285        // SAFETY: the entire unfilled portion of buf has been initialized.
    286        unsafe { buf.advance_unchecked(buf.capacity()) };
    287        Ok(())
    288    }
    289
    290    #[inline]
    291    fn read_buf_exact(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> {
    292        self.read_buf(buf)
    293    }
    294
    295    /// This function is not supported by `io::Repeat`, because there's no end of its data
    296    fn read_to_end(&mut self, _: &mut Vec<u8>) -> io::Result<usize> {
    297        Err(io::Error::from(io::ErrorKind::OutOfMemory))
    298    }
    299
    300    /// This function is not supported by `io::Repeat`, because there's no end of its data
    301    fn read_to_string(&mut self, _: &mut String) -> io::Result<usize> {
    302        Err(io::Error::from(io::ErrorKind::OutOfMemory))
    303    }
    304
    305    #[inline]
    306    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
    307        let mut nwritten = 0;
    308        for buf in bufs {
    309            nwritten += self.read(buf)?;
    310        }
    311        Ok(nwritten)
    312    }
    313
    314    #[inline]
    315    fn is_read_vectored(&self) -> bool {
    316        true
    317    }
    318}
    319
    320impl SizeHint for Repeat {
    321    #[inline]
    322    fn lower_bound(&self) -> usize {
    323        usize::MAX
    324    }
    325
    326    #[inline]
    327    fn upper_bound(&self) -> Option<usize> {
    328        None
    329    }
    330}
    331
    332#[stable(feature = "std_debug", since = "1.16.0")]
    333impl fmt::Debug for Repeat {
    334    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    335        f.debug_struct("Repeat").finish_non_exhaustive()
    336    }
    337}
    338
    339/// A writer which will move data into the void.
    340///
    341/// This struct is generally created by calling [`sink()`]. Please
    342/// see the documentation of [`sink()`] for more details.
    343#[stable(feature = "rust1", since = "1.0.0")]
    344#[non_exhaustive]
    345#[derive(Copy, Clone, Debug, Default)]
    346pub struct Sink;
    347
    348/// Creates an instance of a writer which will successfully consume all data.
    349///
    350/// All calls to [`write`] on the returned instance will return [`Ok(buf.len())`]
    351/// and the contents of the buffer will not be inspected.
    352///
    353/// [`write`]: Write::write
    354/// [`Ok(buf.len())`]: Ok
    355///
    356/// # Examples
    357///
    358/// ```rust
    359/// use std::io::{self, Write};
    360///
    361/// let buffer = vec![1, 2, 3, 5, 8];
    362/// let num_bytes = io::sink().write(&buffer).unwrap();
    363/// assert_eq!(num_bytes, 5);
    364/// ```
    365#[must_use]
    366#[stable(feature = "rust1", since = "1.0.0")]
    367#[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")]
    368pub const fn sink() -> Sink {
    369    Sink
    370}
    371
    372#[stable(feature = "rust1", since = "1.0.0")]
    373impl Write for Sink {
    374    #[inline]
    375    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
    376        Ok(buf.len())
    377    }
    378
    379    #[inline]
    380    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
    381        let total_len = bufs.iter().map(|b| b.len()).sum();
    382        Ok(total_len)
    383    }
    384
    385    #[inline]
    386    fn is_write_vectored(&self) -> bool {
    387        true
    388    }
    389
    390    #[inline]
    391    fn write_all(&mut self, _buf: &[u8]) -> io::Result<()> {
    392        Ok(())
    393    }
    394
    395    #[inline]
    396    fn write_all_vectored(&mut self, _bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
    397        Ok(())
    398    }
    399
    400    #[inline]
    401    fn write_fmt(&mut self, _args: fmt::Arguments<'_>) -> io::Result<()> {
    402        Ok(())
    403    }
    404
    405    #[inline]
    406    fn flush(&mut self) -> io::Result<()> {
    407        Ok(())
    408    }
    409}
    410
    411#[stable(feature = "write_mt", since = "1.48.0")]
    412impl Write for &Sink {
    413    #[inline]
    414    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
    415        Ok(buf.len())
    416    }
    417
    418    #[inline]
    419    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
    420        let total_len = bufs.iter().map(|b| b.len()).sum();
    421        Ok(total_len)
    422    }
    423
    424    #[inline]
    425    fn is_write_vectored(&self) -> bool {
    426        true
    427    }
    428
    429    #[inline]
    430    fn write_all(&mut self, _buf: &[u8]) -> io::Result<()> {
    431        Ok(())
    432    }
    433
    434    #[inline]
    435    fn write_all_vectored(&mut self, _bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
    436        Ok(())
    437    }
    438
    439    #[inline]
    440    fn write_fmt(&mut self, _args: fmt::Arguments<'_>) -> io::Result<()> {
    441        Ok(())
    442    }
    443
    444    #[inline]
    445    fn flush(&mut self) -> io::Result<()> {
    446        Ok(())
    447    }
    448}