src/libstd/io/cursor.rs

   1 // Copyright 2015 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 use prelude::v1::*;
  12 use io::prelude::*;
  13
  14 use cmp;
  15 use io::{self, SeekFrom, Error, ErrorKind};
  16 use slice;
  17
  18 /// A `Cursor` wraps another type and provides it with a
  19 /// [`Seek`](trait.Seek.html) implementation.
  20 ///
  21 /// Cursors are typically used with in-memory buffers to allow them to
  22 /// implement `Read` and/or `Write`, allowing these buffers to be used
  23 /// anywhere you might use a reader or writer that does actual I/O.
  24 ///
  25 /// The standard library implements some I/O traits on various types which
  26 /// are commonly used as a buffer, like `Cursor<Vec<u8>>` and `Cursor<&[u8]>`.
  27 ///
  28 /// # Examples
  29 ///
  30 /// We may want to write bytes to a [`File`][file] in our production
  31 /// code, but use an in-memory buffer in our tests. We can do this with
  32 /// `Cursor`:
  33 ///
  34 /// [file]: ../fs/struct.File.html
  35 ///
  36 /// ```no_run
  37 /// use std::io::prelude::*;
  38 /// use std::io::{self, SeekFrom};
  39 /// use std::fs::File;
  40 ///
  41 /// // a library function we've written
  42 /// fn write_ten_bytes_at_end<W: Write + Seek>(writer: &mut W) -> io::Result<()> {
  43 ///     try!(writer.seek(SeekFrom::End(-10)));
  44 ///
  45 ///     for i in 0..10 {
  46 ///         try!(writer.write(&[i]));
  47 ///     }
  48 ///
  49 ///     // all went well
  50 ///     Ok(())
  51 /// }
  52 ///
  53 /// # fn foo() -> io::Result<()> {
  54 /// // Here's some code that uses this library function.
  55 /// //
  56 /// // We might want to use a BufReader here for efficiency, but let's
  57 /// // keep this example focused.
  58 /// let mut file = try!(File::create("foo.txt"));
  59 ///
  60 /// try!(write_ten_bytes_at_end(&mut file));
  61 /// # Ok(())
  62 /// # }
  63 ///
  64 /// // now let's write a test
  65 /// #[test]
  66 /// fn test_writes_bytes() {
  67 ///     // setting up a real File is much more slow than an in-memory buffer,
  68 ///     // let's use a cursor instead
  69 ///     use std::io::Cursor;
  70 ///     let mut buff = Cursor::new(vec![0; 15]);
  71 ///
  72 ///     write_ten_bytes(&mut buff).unwrap();
  73 ///
  74 ///     assert_eq!(&buff.get_ref()[5..15], &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
  75 /// }
  76 /// ```
  77 #[stable(feature = "rust1", since = "1.0.0")]
  78 #[derive(Clone, Debug)]
  79 pub struct Cursor<T> {
  80     inner: T,
  81     pos: u64,
  82 }
  83
  84 impl<T> Cursor<T> {
  85     /// Creates a new cursor wrapping the provided underlying I/O object.
  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     pub fn new(inner: T) -> Cursor<T> {
  98         Cursor { pos: 0, inner: inner }
  99     }
 100
 101     /// Consumes this cursor, returning the underlying value.
 102     ///
 103     /// # Examples
 104     ///
 105     /// ```
 106     /// use std::io::Cursor;
 107     ///
 108     /// let buff = Cursor::new(Vec::new());
 109     /// # fn force_inference(_: &Cursor<Vec<u8>>) {}
 110     /// # force_inference(&buff);
 111     ///
 112     /// let vec = buff.into_inner();
 113     /// ```
 114     #[stable(feature = "rust1", since = "1.0.0")]
 115     pub fn into_inner(self) -> T { self.inner }
 116
 117     /// Gets a reference to the underlying value in this cursor.
 118     ///
 119     /// # Examples
 120     ///
 121     /// ```
 122     /// use std::io::Cursor;
 123     ///
 124     /// let buff = Cursor::new(Vec::new());
 125     /// # fn force_inference(_: &Cursor<Vec<u8>>) {}
 126     /// # force_inference(&buff);
 127     ///
 128     /// let reference = buff.get_ref();
 129     /// ```
 130     #[stable(feature = "rust1", since = "1.0.0")]
 131     pub fn get_ref(&self) -> &T { &self.inner }
 132
 133     /// Gets a mutable reference to the underlying value in this cursor.
 134     ///
 135     /// Care should be taken to avoid modifying the internal I/O state of the
 136     /// underlying value as it may corrupt this cursor's position.
 137     ///
 138     /// # Examples
 139     ///
 140     /// ```
 141     /// use std::io::Cursor;
 142     ///
 143     /// let mut buff = Cursor::new(Vec::new());
 144     /// # fn force_inference(_: &Cursor<Vec<u8>>) {}
 145     /// # force_inference(&buff);
 146     ///
 147     /// let reference = buff.get_mut();
 148     /// ```
 149     #[stable(feature = "rust1", since = "1.0.0")]
 150     pub fn get_mut(&mut self) -> &mut T { &mut self.inner }
 151
 152     /// Returns the current position of this cursor.
 153     ///
 154     /// # Examples
 155     ///
 156     /// ```
 157     /// use std::io::Cursor;
 158     /// use std::io::prelude::*;
 159     /// use std::io::SeekFrom;
 160     ///
 161     /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]);
 162     ///
 163     /// assert_eq!(buff.position(), 0);
 164     ///
 165     /// buff.seek(SeekFrom::Current(2)).unwrap();
 166     /// assert_eq!(buff.position(), 2);
 167     ///
 168     /// buff.seek(SeekFrom::Current(-1)).unwrap();
 169     /// assert_eq!(buff.position(), 1);
 170     /// ```
 171     #[stable(feature = "rust1", since = "1.0.0")]
 172     pub fn position(&self) -> u64 { self.pos }
 173
 174     /// Sets the position of this cursor.
 175     ///
 176     /// # Examples
 177     ///
 178     /// ```
 179     /// use std::io::Cursor;
 180     ///
 181     /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]);
 182     ///
 183     /// assert_eq!(buff.position(), 0);
 184     ///
 185     /// buff.set_position(2);
 186     /// assert_eq!(buff.position(), 2);
 187     ///
 188     /// buff.set_position(4);
 189     /// assert_eq!(buff.position(), 4);
 190     /// ```
 191     #[stable(feature = "rust1", since = "1.0.0")]
 192     pub fn set_position(&mut self, pos: u64) { self.pos = pos; }
 193 }
 194
 195 #[stable(feature = "rust1", since = "1.0.0")]
 196 impl<T> io::Seek for Cursor<T> where T: AsRef<[u8]> {
 197     fn seek(&mut self, style: SeekFrom) -> io::Result<u64> {
 198         let pos = match style {
 199             SeekFrom::Start(n) => { self.pos = n; return Ok(n) }
 200             SeekFrom::End(n) => self.inner.as_ref().len() as i64 + n,
 201             SeekFrom::Current(n) => self.pos as i64 + n,
 202         };
 203
 204         if pos < 0 {
 205             Err(Error::new(ErrorKind::InvalidInput,
 206                            "invalid seek to a negative position"))
 207         } else {
 208             self.pos = pos as u64;
 209             Ok(self.pos)
 210         }
 211     }
 212 }
 213
 214 #[stable(feature = "rust1", since = "1.0.0")]
 215 impl<T> Read for Cursor<T> where T: AsRef<[u8]> {
 216     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 217         let n = try!(Read::read(&mut try!(self.fill_buf()), buf));
 218         self.pos += n as u64;
 219         Ok(n)
 220     }
 221 }
 222
 223 #[stable(feature = "rust1", since = "1.0.0")]
 224 impl<T> BufRead for Cursor<T> where T: AsRef<[u8]> {
 225     fn fill_buf(&mut self) -> io::Result<&[u8]> {
 226         let amt = cmp::min(self.pos, self.inner.as_ref().len() as u64);
 227         Ok(&self.inner.as_ref()[(amt as usize)..])
 228     }
 229     fn consume(&mut self, amt: usize) { self.pos += amt as u64; }
 230 }
 231
 232 #[stable(feature = "rust1", since = "1.0.0")]
 233 impl<'a> Write for Cursor<&'a mut [u8]> {
 234     fn write(&mut self, data: &[u8]) -> io::Result<usize> {
 235         let pos = cmp::min(self.pos, self.inner.len() as u64);
 236         let amt = try!((&mut self.inner[(pos as usize)..]).write(data));
 237         self.pos += amt as u64;
 238         Ok(amt)
 239     }
 240     fn flush(&mut self) -> io::Result<()> { Ok(()) }
 241 }
 242
 243 #[stable(feature = "rust1", since = "1.0.0")]
 244 impl Write for Cursor<Vec<u8>> {
 245     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 246         // Make sure the internal buffer is as least as big as where we
 247         // currently are
 248         let pos = self.position();
 249         let amt = pos.saturating_sub(self.inner.len() as u64);
 250         // use `resize` so that the zero filling is as efficient as possible
 251         let len = self.inner.len();
 252         self.inner.resize(len + amt as usize, 0);
 253
 254         // Figure out what bytes will be used to overwrite what's currently
 255         // there (left), and what will be appended on the end (right)
 256         let space = self.inner.len() - pos as usize;
 257         let (left, right) = buf.split_at(cmp::min(space, buf.len()));
 258         slice::bytes::copy_memory(left, &mut self.inner[(pos as usize)..]);
 259         self.inner.push_all(right);
 260
 261         // Bump us forward
 262         self.set_position(pos + buf.len() as u64);
 263         Ok(buf.len())
 264     }
 265     fn flush(&mut self) -> io::Result<()> { Ok(()) }
 266 }
 267
 268
 269 #[cfg(test)]
 270 mod tests {
 271     use io::prelude::*;
 272     use io::{Cursor, SeekFrom};
 273     use vec::Vec;
 274
 275     #[test]
 276     fn test_vec_writer() {
 277         let mut writer = Vec::new();
 278         assert_eq!(writer.write(&[0]).unwrap(), 1);
 279         assert_eq!(writer.write(&[1, 2, 3]).unwrap(), 3);
 280         assert_eq!(writer.write(&[4, 5, 6, 7]).unwrap(), 4);
 281         let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7];
 282         assert_eq!(writer, b);
 283     }
 284
 285     #[test]
 286     fn test_mem_writer() {
 287         let mut writer = Cursor::new(Vec::new());
 288         assert_eq!(writer.write(&[0]).unwrap(), 1);
 289         assert_eq!(writer.write(&[1, 2, 3]).unwrap(), 3);
 290         assert_eq!(writer.write(&[4, 5, 6, 7]).unwrap(), 4);
 291         let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7];
 292         assert_eq!(&writer.get_ref()[..], b);
 293     }
 294
 295     #[test]
 296     fn test_buf_writer() {
 297         let mut buf = [0 as u8; 9];
 298         {
 299             let mut writer = Cursor::new(&mut buf[..]);
 300             assert_eq!(writer.position(), 0);
 301             assert_eq!(writer.write(&[0]).unwrap(), 1);
 302             assert_eq!(writer.position(), 1);
 303             assert_eq!(writer.write(&[1, 2, 3]).unwrap(), 3);
 304             assert_eq!(writer.write(&[4, 5, 6, 7]).unwrap(), 4);
 305             assert_eq!(writer.position(), 8);
 306             assert_eq!(writer.write(&[]).unwrap(), 0);
 307             assert_eq!(writer.position(), 8);
 308
 309             assert_eq!(writer.write(&[8, 9]).unwrap(), 1);
 310             assert_eq!(writer.write(&[10]).unwrap(), 0);
 311         }
 312         let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8];
 313         assert_eq!(buf, b);
 314     }
 315
 316     #[test]
 317     fn test_buf_writer_seek() {
 318         let mut buf = [0 as u8; 8];
 319         {
 320             let mut writer = Cursor::new(&mut buf[..]);
 321             assert_eq!(writer.position(), 0);
 322             assert_eq!(writer.write(&[1]).unwrap(), 1);
 323             assert_eq!(writer.position(), 1);
 324
 325             assert_eq!(writer.seek(SeekFrom::Start(2)).unwrap(), 2);
 326             assert_eq!(writer.position(), 2);
 327             assert_eq!(writer.write(&[2]).unwrap(), 1);
 328             assert_eq!(writer.position(), 3);
 329
 330             assert_eq!(writer.seek(SeekFrom::Current(-2)).unwrap(), 1);
 331             assert_eq!(writer.position(), 1);
 332             assert_eq!(writer.write(&[3]).unwrap(), 1);
 333             assert_eq!(writer.position(), 2);
 334
 335             assert_eq!(writer.seek(SeekFrom::End(-1)).unwrap(), 7);
 336             assert_eq!(writer.position(), 7);
 337             assert_eq!(writer.write(&[4]).unwrap(), 1);
 338             assert_eq!(writer.position(), 8);
 339
 340         }
 341         let b: &[_] = &[1, 3, 2, 0, 0, 0, 0, 4];
 342         assert_eq!(buf, b);
 343     }
 344
 345     #[test]
 346     fn test_buf_writer_error() {
 347         let mut buf = [0 as u8; 2];
 348         let mut writer = Cursor::new(&mut buf[..]);
 349         assert_eq!(writer.write(&[0]).unwrap(), 1);
 350         assert_eq!(writer.write(&[0, 0]).unwrap(), 1);
 351         assert_eq!(writer.write(&[0, 0]).unwrap(), 0);
 352     }
 353
 354     #[test]
 355     fn test_mem_reader() {
 356         let mut reader = Cursor::new(vec!(0, 1, 2, 3, 4, 5, 6, 7));
 357         let mut buf = [];
 358         assert_eq!(reader.read(&mut buf).unwrap(), 0);
 359         assert_eq!(reader.position(), 0);
 360         let mut buf = [0];
 361         assert_eq!(reader.read(&mut buf).unwrap(), 1);
 362         assert_eq!(reader.position(), 1);
 363         let b: &[_] = &[0];
 364         assert_eq!(buf, b);
 365         let mut buf = [0; 4];
 366         assert_eq!(reader.read(&mut buf).unwrap(), 4);
 367         assert_eq!(reader.position(), 5);
 368         let b: &[_] = &[1, 2, 3, 4];
 369         assert_eq!(buf, b);
 370         assert_eq!(reader.read(&mut buf).unwrap(), 3);
 371         let b: &[_] = &[5, 6, 7];
 372         assert_eq!(&buf[..3], b);
 373         assert_eq!(reader.read(&mut buf).unwrap(), 0);
 374     }
 375
 376     #[test]
 377     fn read_to_end() {
 378         let mut reader = Cursor::new(vec!(0, 1, 2, 3, 4, 5, 6, 7));
 379         let mut v = Vec::new();
 380         reader.read_to_end(&mut v).unwrap();
 381         assert_eq!(v, [0, 1, 2, 3, 4, 5, 6, 7]);
 382     }
 383
 384     #[test]
 385     fn test_slice_reader() {
 386         let in_buf = vec![0, 1, 2, 3, 4, 5, 6, 7];
 387         let mut reader = &mut &in_buf[..];
 388         let mut buf = [];
 389         assert_eq!(reader.read(&mut buf).unwrap(), 0);
 390         let mut buf = [0];
 391         assert_eq!(reader.read(&mut buf).unwrap(), 1);
 392         assert_eq!(reader.len(), 7);
 393         let b: &[_] = &[0];
 394         assert_eq!(&buf[..], b);
 395         let mut buf = [0; 4];
 396         assert_eq!(reader.read(&mut buf).unwrap(), 4);
 397         assert_eq!(reader.len(), 3);
 398         let b: &[_] = &[1, 2, 3, 4];
 399         assert_eq!(&buf[..], b);
 400         assert_eq!(reader.read(&mut buf).unwrap(), 3);
 401         let b: &[_] = &[5, 6, 7];
 402         assert_eq!(&buf[..3], b);
 403         assert_eq!(reader.read(&mut buf).unwrap(), 0);
 404     }
 405
 406     #[test]
 407     fn test_buf_reader() {
 408         let in_buf = vec![0, 1, 2, 3, 4, 5, 6, 7];
 409         let mut reader = Cursor::new(&in_buf[..]);
 410         let mut buf = [];
 411         assert_eq!(reader.read(&mut buf).unwrap(), 0);
 412         assert_eq!(reader.position(), 0);
 413         let mut buf = [0];
 414         assert_eq!(reader.read(&mut buf).unwrap(), 1);
 415         assert_eq!(reader.position(), 1);
 416         let b: &[_] = &[0];
 417         assert_eq!(buf, b);
 418         let mut buf = [0; 4];
 419         assert_eq!(reader.read(&mut buf).unwrap(), 4);
 420         assert_eq!(reader.position(), 5);
 421         let b: &[_] = &[1, 2, 3, 4];
 422         assert_eq!(buf, b);
 423         assert_eq!(reader.read(&mut buf).unwrap(), 3);
 424         let b: &[_] = &[5, 6, 7];
 425         assert_eq!(&buf[..3], b);
 426         assert_eq!(reader.read(&mut buf).unwrap(), 0);
 427     }
 428
 429     #[test]
 430     fn test_read_char() {
 431         let b = &b"Vi\xE1\xBB\x87t"[..];
 432         let mut c = Cursor::new(b).chars();
 433         assert_eq!(c.next().unwrap().unwrap(), 'V');
 434         assert_eq!(c.next().unwrap().unwrap(), 'i');
 435         assert_eq!(c.next().unwrap().unwrap(), 'ệ');
 436         assert_eq!(c.next().unwrap().unwrap(), 't');
 437         assert!(c.next().is_none());
 438     }
 439
 440     #[test]
 441     fn test_read_bad_char() {
 442         let b = &b"\x80"[..];
 443         let mut c = Cursor::new(b).chars();
 444         assert!(c.next().unwrap().is_err());
 445     }
 446
 447     #[test]
 448     fn seek_past_end() {
 449         let buf = [0xff];
 450         let mut r = Cursor::new(&buf[..]);
 451         assert_eq!(r.seek(SeekFrom::Start(10)).unwrap(), 10);
 452         assert_eq!(r.read(&mut [0]).unwrap(), 0);
 453
 454         let mut r = Cursor::new(vec!(10));
 455         assert_eq!(r.seek(SeekFrom::Start(10)).unwrap(), 10);
 456         assert_eq!(r.read(&mut [0]).unwrap(), 0);
 457
 458         let mut buf = [0];
 459         let mut r = Cursor::new(&mut buf[..]);
 460         assert_eq!(r.seek(SeekFrom::Start(10)).unwrap(), 10);
 461         assert_eq!(r.write(&[3]).unwrap(), 0);
 462     }
 463
 464     #[test]
 465     fn seek_before_0() {
 466         let buf = [0xff];
 467         let mut r = Cursor::new(&buf[..]);
 468         assert!(r.seek(SeekFrom::End(-2)).is_err());
 469
 470         let mut r = Cursor::new(vec!(10));
 471         assert!(r.seek(SeekFrom::End(-2)).is_err());
 472
 473         let mut buf = [0];
 474         let mut r = Cursor::new(&mut buf[..]);
 475         assert!(r.seek(SeekFrom::End(-2)).is_err());
 476     }
 477
 478     #[test]
 479     fn test_seekable_mem_writer() {
 480         let mut writer = Cursor::new(Vec::<u8>::new());
 481         assert_eq!(writer.position(), 0);
 482         assert_eq!(writer.write(&[0]).unwrap(), 1);
 483         assert_eq!(writer.position(), 1);
 484         assert_eq!(writer.write(&[1, 2, 3]).unwrap(), 3);
 485         assert_eq!(writer.write(&[4, 5, 6, 7]).unwrap(), 4);
 486         assert_eq!(writer.position(), 8);
 487         let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7];
 488         assert_eq!(&writer.get_ref()[..], b);
 489
 490         assert_eq!(writer.seek(SeekFrom::Start(0)).unwrap(), 0);
 491         assert_eq!(writer.position(), 0);
 492         assert_eq!(writer.write(&[3, 4]).unwrap(), 2);
 493         let b: &[_] = &[3, 4, 2, 3, 4, 5, 6, 7];
 494         assert_eq!(&writer.get_ref()[..], b);
 495
 496         assert_eq!(writer.seek(SeekFrom::Current(1)).unwrap(), 3);
 497         assert_eq!(writer.write(&[0, 1]).unwrap(), 2);
 498         let b: &[_] = &[3, 4, 2, 0, 1, 5, 6, 7];
 499         assert_eq!(&writer.get_ref()[..], b);
 500
 501         assert_eq!(writer.seek(SeekFrom::End(-1)).unwrap(), 7);
 502         assert_eq!(writer.write(&[1, 2]).unwrap(), 2);
 503         let b: &[_] = &[3, 4, 2, 0, 1, 5, 6, 1, 2];
 504         assert_eq!(&writer.get_ref()[..], b);
 505
 506         assert_eq!(writer.seek(SeekFrom::End(1)).unwrap(), 10);
 507         assert_eq!(writer.write(&[1]).unwrap(), 1);
 508         let b: &[_] = &[3, 4, 2, 0, 1, 5, 6, 1, 2, 0, 1];
 509         assert_eq!(&writer.get_ref()[..], b);
 510     }
 511
 512     #[test]
 513     fn vec_seek_past_end() {
 514         let mut r = Cursor::new(Vec::new());
 515         assert_eq!(r.seek(SeekFrom::Start(10)).unwrap(), 10);
 516         assert_eq!(r.write(&[3]).unwrap(), 1);
 517     }
 518
 519     #[test]
 520     fn vec_seek_before_0() {
 521         let mut r = Cursor::new(Vec::new());
 522         assert!(r.seek(SeekFrom::End(-2)).is_err());
 523     }
 524 }