library/std/src/io/cursor.rs

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