library/std/src/io/cursor.rs

   1 #[cfg(test)]
   2 mod tests;
   3
   4 use crate::io::prelude::*;
   5
   6 use crate::cmp;
   7 use crate::io::{self, Error, ErrorKind, Initializer, IoSlice, IoSliceMut, SeekFrom};
   8
   9 use core::convert::TryInto;
  10
  11 /// A `Cursor` wraps an in-memory buffer and provides it with a
  12 /// [`Seek`] implementation.
  13 ///
  14 /// `Cursor`s are used with in-memory buffers, anything implementing
  15 /// [`AsRef`]`<[u8]>`, to allow them to implement [`Read`] and/or [`Write`],
  16 /// allowing these buffers to be used anywhere you might use a reader or writer
  17 /// that does actual I/O.
  18 ///
  19 /// The standard library implements some I/O traits on various types which
  20 /// are commonly used as a buffer, like `Cursor<`[`Vec`]`<u8>>` and
  21 /// `Cursor<`[`&[u8]`][bytes]`>`.
  22 ///
  23 /// # Examples
  24 ///
  25 /// We may want to write bytes to a [`File`] in our production
  26 /// code, but use an in-memory buffer in our tests. We can do this with
  27 /// `Cursor`:
  28 ///
  29 /// [bytes]: crate::slice
  30 /// [`File`]: crate::fs::File
  31 ///
  32 /// ```no_run
  33 /// use std::io::prelude::*;
  34 /// use std::io::{self, SeekFrom};
  35 /// use std::fs::File;
  36 ///
  37 /// // a library function we've written
  38 /// fn write_ten_bytes_at_end<W: Write + Seek>(writer: &mut W) -> io::Result<()> {
  39 ///     writer.seek(SeekFrom::End(-10))?;
  40 ///
  41 ///     for i in 0..10 {
  42 ///         writer.write(&[i])?;
  43 ///     }
  44 ///
  45 ///     // all went well
  46 ///     Ok(())
  47 /// }
  48 ///
  49 /// # fn foo() -> io::Result<()> {
  50 /// // Here's some code that uses this library function.
  51 /// //
  52 /// // We might want to use a BufReader here for efficiency, but let's
  53 /// // keep this example focused.
  54 /// let mut file = File::create("foo.txt")?;
  55 ///
  56 /// write_ten_bytes_at_end(&mut file)?;
  57 /// # Ok(())
  58 /// # }
  59 ///
  60 /// // now let's write a test
  61 /// #[test]
  62 /// fn test_writes_bytes() {
  63 ///     // setting up a real File is much slower than an in-memory buffer,
  64 ///     // let's use a cursor instead
  65 ///     use std::io::Cursor;
  66 ///     let mut buff = Cursor::new(vec![0; 15]);
  67 ///
  68 ///     write_ten_bytes_at_end(&mut buff).unwrap();
  69 ///
  70 ///     assert_eq!(&buff.get_ref()[5..15], &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
  71 /// }
  72 /// ```
  73 #[stable(feature = "rust1", since = "1.0.0")]
  74 #[derive(Clone, Debug, Default, Eq, PartialEq)]
  75 pub struct Cursor<T> {
  76     inner: T,
  77     pos: u64,
  78 }
  79
  80 impl<T> Cursor<T> {
  81     /// Creates a new cursor wrapping the provided underlying in-memory buffer.
  82     ///
  83     /// Cursor initial position is `0` even if underlying buffer (e.g., [`Vec`])
  84     /// is not empty. So writing to cursor starts with overwriting [`Vec`]
  85     /// content, not with appending to it.
  86     ///
  87     /// # Examples
  88     ///
  89     /// ```
  90     /// use std::io::Cursor;
  91     ///
  92     /// let buff = Cursor::new(Vec::new());
  93     /// # fn force_inference(_: &Cursor<Vec<u8>>) {}
  94     /// # force_inference(&buff);
  95     /// ```
  96     #[stable(feature = "rust1", since = "1.0.0")]
  97     #[rustc_const_unstable(feature = "const_io_structs", issue = "78812")]
  98     pub const fn new(inner: T) -> Cursor<T> {
  99         Cursor { pos: 0, inner }
 100     }
 101
 102     /// Consumes this cursor, returning the underlying value.
 103     ///
 104     /// # Examples
 105     ///
 106     /// ```
 107     /// use std::io::Cursor;
 108     ///
 109     /// let buff = Cursor::new(Vec::new());
 110     /// # fn force_inference(_: &Cursor<Vec<u8>>) {}
 111     /// # force_inference(&buff);
 112     ///
 113     /// let vec = buff.into_inner();
 114     /// ```
 115     #[stable(feature = "rust1", since = "1.0.0")]
 116     pub fn into_inner(self) -> T {
 117         self.inner
 118     }
 119
 120     /// Gets a reference to the underlying value in this cursor.
 121     ///
 122     /// # Examples
 123     ///
 124     /// ```
 125     /// use std::io::Cursor;
 126     ///
 127     /// let buff = Cursor::new(Vec::new());
 128     /// # fn force_inference(_: &Cursor<Vec<u8>>) {}
 129     /// # force_inference(&buff);
 130     ///
 131     /// let reference = buff.get_ref();
 132     /// ```
 133     #[stable(feature = "rust1", since = "1.0.0")]
 134     #[rustc_const_unstable(feature = "const_io_structs", issue = "78812")]
 135     pub const fn get_ref(&self) -> &T {
 136         &self.inner
 137     }
 138
 139     /// Gets a mutable reference to the underlying value in this cursor.
 140     ///
 141     /// Care should be taken to avoid modifying the internal I/O state of the
 142     /// underlying value as it may corrupt this cursor's position.
 143     ///
 144     /// # Examples
 145     ///
 146     /// ```
 147     /// use std::io::Cursor;
 148     ///
 149     /// let mut buff = Cursor::new(Vec::new());
 150     /// # fn force_inference(_: &Cursor<Vec<u8>>) {}
 151     /// # force_inference(&buff);
 152     ///
 153     /// let reference = buff.get_mut();
 154     /// ```
 155     #[stable(feature = "rust1", since = "1.0.0")]
 156     pub fn get_mut(&mut self) -> &mut T {
 157         &mut self.inner
 158     }
 159
 160     /// Returns the current position of this cursor.
 161     ///
 162     /// # Examples
 163     ///
 164     /// ```
 165     /// use std::io::Cursor;
 166     /// use std::io::prelude::*;
 167     /// use std::io::SeekFrom;
 168     ///
 169     /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]);
 170     ///
 171     /// assert_eq!(buff.position(), 0);
 172     ///
 173     /// buff.seek(SeekFrom::Current(2)).unwrap();
 174     /// assert_eq!(buff.position(), 2);
 175     ///
 176     /// buff.seek(SeekFrom::Current(-1)).unwrap();
 177     /// assert_eq!(buff.position(), 1);
 178     /// ```
 179     #[stable(feature = "rust1", since = "1.0.0")]
 180     #[rustc_const_unstable(feature = "const_io_structs", issue = "78812")]
 181     pub const fn position(&self) -> u64 {
 182         self.pos
 183     }
 184
 185     /// Sets the position of this cursor.
 186     ///
 187     /// # Examples
 188     ///
 189     /// ```
 190     /// use std::io::Cursor;
 191     ///
 192     /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]);
 193     ///
 194     /// assert_eq!(buff.position(), 0);
 195     ///
 196     /// buff.set_position(2);
 197     /// assert_eq!(buff.position(), 2);
 198     ///
 199     /// buff.set_position(4);
 200     /// assert_eq!(buff.position(), 4);
 201     /// ```
 202     #[stable(feature = "rust1", since = "1.0.0")]
 203     pub fn set_position(&mut self, pos: u64) {
 204         self.pos = pos;
 205     }
 206 }
 207
 208 #[stable(feature = "rust1", since = "1.0.0")]
 209 impl<T> io::Seek for Cursor<T>
 210 where
 211     T: AsRef<[u8]>,
 212 {
 213     fn seek(&mut self, style: SeekFrom) -> io::Result<u64> {
 214         let (base_pos, offset) = match style {
 215             SeekFrom::Start(n) => {
 216                 self.pos = n;
 217                 return Ok(n);
 218             }
 219             SeekFrom::End(n) => (self.inner.as_ref().len() as u64, n),
 220             SeekFrom::Current(n) => (self.pos, n),
 221         };
 222         let new_pos = if offset >= 0 {
 223             base_pos.checked_add(offset as u64)
 224         } else {
 225             base_pos.checked_sub((offset.wrapping_neg()) as u64)
 226         };
 227         match new_pos {
 228             Some(n) => {
 229                 self.pos = n;
 230                 Ok(self.pos)
 231             }
 232             None => Err(Error::new_const(
 233                 ErrorKind::InvalidInput,
 234                 &"invalid seek to a negative or overflowing position",
 235             )),
 236         }
 237     }
 238
 239     fn stream_len(&mut self) -> io::Result<u64> {
 240         Ok(self.inner.as_ref().len() as u64)
 241     }
 242
 243     fn stream_position(&mut self) -> io::Result<u64> {
 244         Ok(self.pos)
 245     }
 246 }
 247
 248 #[stable(feature = "rust1", since = "1.0.0")]
 249 impl<T> Read for Cursor<T>
 250 where
 251     T: AsRef<[u8]>,
 252 {
 253     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 254         let n = Read::read(&mut self.fill_buf()?, buf)?;
 255         self.pos += n as u64;
 256         Ok(n)
 257     }
 258
 259     fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
 260         let mut nread = 0;
 261         for buf in bufs {
 262             let n = self.read(buf)?;
 263             nread += n;
 264             if n < buf.len() {
 265                 break;
 266             }
 267         }
 268         Ok(nread)
 269     }
 270
 271     fn is_read_vectored(&self) -> bool {
 272         true
 273     }
 274
 275     fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
 276         let n = buf.len();
 277         Read::read_exact(&mut self.fill_buf()?, buf)?;
 278         self.pos += n as u64;
 279         Ok(())
 280     }
 281
 282     #[inline]
 283     unsafe fn initializer(&self) -> Initializer {
 284         Initializer::nop()
 285     }
 286 }
 287
 288 #[stable(feature = "rust1", since = "1.0.0")]
 289 impl<T> BufRead for Cursor<T>
 290 where
 291     T: AsRef<[u8]>,
 292 {
 293     fn fill_buf(&mut self) -> io::Result<&[u8]> {
 294         let amt = cmp::min(self.pos, self.inner.as_ref().len() as u64);
 295         Ok(&self.inner.as_ref()[(amt as usize)..])
 296     }
 297     fn consume(&mut self, amt: usize) {
 298         self.pos += amt as u64;
 299     }
 300 }
 301
 302 // Non-resizing write implementation
 303 #[inline]
 304 fn slice_write(pos_mut: &mut u64, slice: &mut [u8], buf: &[u8]) -> io::Result<usize> {
 305     let pos = cmp::min(*pos_mut, slice.len() as u64);
 306     let amt = (&mut slice[(pos as usize)..]).write(buf)?;
 307     *pos_mut += amt as u64;
 308     Ok(amt)
 309 }
 310
 311 #[inline]
 312 fn slice_write_vectored(
 313     pos_mut: &mut u64,
 314     slice: &mut [u8],
 315     bufs: &[IoSlice<'_>],
 316 ) -> io::Result<usize> {
 317     let mut nwritten = 0;
 318     for buf in bufs {
 319         let n = slice_write(pos_mut, slice, buf)?;
 320         nwritten += n;
 321         if n < buf.len() {
 322             break;
 323         }
 324     }
 325     Ok(nwritten)
 326 }
 327
 328 // Resizing write implementation
 329 fn vec_write(pos_mut: &mut u64, vec: &mut Vec<u8>, buf: &[u8]) -> io::Result<usize> {
 330     let pos: usize = (*pos_mut).try_into().map_err(|_| {
 331         Error::new_const(
 332             ErrorKind::InvalidInput,
 333             &"cursor position exceeds maximum possible vector length",
 334         )
 335     })?;
 336     // Make sure the internal buffer is as least as big as where we
 337     // currently are
 338     let len = vec.len();
 339     if len < pos {
 340         // use `resize` so that the zero filling is as efficient as possible
 341         vec.resize(pos, 0);
 342     }
 343     // Figure out what bytes will be used to overwrite what's currently
 344     // there (left), and what will be appended on the end (right)
 345     {
 346         let space = vec.len() - pos;
 347         let (left, right) = buf.split_at(cmp::min(space, buf.len()));
 348         vec[pos..pos + left.len()].copy_from_slice(left);
 349         vec.extend_from_slice(right);
 350     }
 351
 352     // Bump us forward
 353     *pos_mut = (pos + buf.len()) as u64;
 354     Ok(buf.len())
 355 }
 356
 357 fn vec_write_vectored(
 358     pos_mut: &mut u64,
 359     vec: &mut Vec<u8>,
 360     bufs: &[IoSlice<'_>],
 361 ) -> io::Result<usize> {
 362     let mut nwritten = 0;
 363     for buf in bufs {
 364         nwritten += vec_write(pos_mut, vec, buf)?;
 365     }
 366     Ok(nwritten)
 367 }
 368
 369 #[stable(feature = "rust1", since = "1.0.0")]
 370 impl Write for Cursor<&mut [u8]> {
 371     #[inline]
 372     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 373         slice_write(&mut self.pos, self.inner, buf)
 374     }
 375
 376     #[inline]
 377     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 378         slice_write_vectored(&mut self.pos, self.inner, bufs)
 379     }
 380
 381     #[inline]
 382     fn is_write_vectored(&self) -> bool {
 383         true
 384     }
 385
 386     #[inline]
 387     fn flush(&mut self) -> io::Result<()> {
 388         Ok(())
 389     }
 390 }
 391
 392 #[stable(feature = "cursor_mut_vec", since = "1.25.0")]
 393 impl Write for Cursor<&mut Vec<u8>> {
 394     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 395         vec_write(&mut self.pos, self.inner, buf)
 396     }
 397
 398     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 399         vec_write_vectored(&mut self.pos, self.inner, bufs)
 400     }
 401
 402     #[inline]
 403     fn is_write_vectored(&self) -> bool {
 404         true
 405     }
 406
 407     #[inline]
 408     fn flush(&mut self) -> io::Result<()> {
 409         Ok(())
 410     }
 411 }
 412
 413 #[stable(feature = "rust1", since = "1.0.0")]
 414 impl Write for Cursor<Vec<u8>> {
 415     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 416         vec_write(&mut self.pos, &mut self.inner, buf)
 417     }
 418
 419     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 420         vec_write_vectored(&mut self.pos, &mut self.inner, bufs)
 421     }
 422
 423     #[inline]
 424     fn is_write_vectored(&self) -> bool {
 425         true
 426     }
 427
 428     #[inline]
 429     fn flush(&mut self) -> io::Result<()> {
 430         Ok(())
 431     }
 432 }
 433
 434 #[stable(feature = "cursor_box_slice", since = "1.5.0")]
 435 impl Write for Cursor<Box<[u8]>> {
 436     #[inline]
 437     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 438         slice_write(&mut self.pos, &mut self.inner, buf)
 439     }
 440
 441     #[inline]
 442     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 443         slice_write_vectored(&mut self.pos, &mut self.inner, bufs)
 444     }
 445
 446     #[inline]
 447     fn is_write_vectored(&self) -> bool {
 448         true
 449     }
 450
 451     #[inline]
 452     fn flush(&mut self) -> io::Result<()> {
 453         Ok(())
 454     }
 455 }