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 iter::repeat;
  17 use num::Int;
  18 use slice;
  19
  20 /// A `Cursor` is a type which wraps a non-I/O object to provide a `Seek`
  21 /// implementation.
  22 ///
  23 /// Cursors are typically used with memory buffer objects in order to allow
  24 /// `Seek`, `Read`, and `Write` implementations. For example, common cursor types
  25 /// include `Cursor<Vec<u8>>` and `Cursor<&[u8]>`.
  26 ///
  27 /// Implementations of the I/O traits for `Cursor<T>` are currently not generic
  28 /// over `T` itself. Instead, specific implementations are provided for various
  29 /// in-memory buffer types like `Vec<u8>` and `&[u8]`.
  30 #[stable(feature = "rust1", since = "1.0.0")]
  31 #[derive(Clone, Debug)]
  32 pub struct Cursor<T> {
  33     inner: T,
  34     pos: u64,
  35 }
  36
  37 impl<T> Cursor<T> {
  38     /// Create a new cursor wrapping the provided underlying I/O object.
  39     #[stable(feature = "rust1", since = "1.0.0")]
  40     pub fn new(inner: T) -> Cursor<T> {
  41         Cursor { pos: 0, inner: inner }
  42     }
  43
  44     /// Consume this cursor, returning the underlying value.
  45     #[stable(feature = "rust1", since = "1.0.0")]
  46     pub fn into_inner(self) -> T { self.inner }
  47
  48     /// Get a reference to the underlying value in this cursor.
  49     #[stable(feature = "rust1", since = "1.0.0")]
  50     pub fn get_ref(&self) -> &T { &self.inner }
  51
  52     /// Get a mutable reference to the underlying value in this cursor.
  53     ///
  54     /// Care should be taken to avoid modifying the internal I/O state of the
  55     /// underlying value as it may corrupt this cursor's position.
  56     #[stable(feature = "rust1", since = "1.0.0")]
  57     pub fn get_mut(&mut self) -> &mut T { &mut self.inner }
  58
  59     /// Returns the current value of this cursor
  60     #[stable(feature = "rust1", since = "1.0.0")]
  61     pub fn position(&self) -> u64 { self.pos }
  62
  63     /// Sets the value of this cursor
  64     #[stable(feature = "rust1", since = "1.0.0")]
  65     pub fn set_position(&mut self, pos: u64) { self.pos = pos; }
  66 }
  67
  68 macro_rules! seek {
  69     () => {
  70         fn seek(&mut self, style: SeekFrom) -> io::Result<u64> {
  71             let pos = match style {
  72                 SeekFrom::Start(n) => { self.pos = n; return Ok(n) }
  73                 SeekFrom::End(n) => self.inner.len() as i64 + n,
  74                 SeekFrom::Current(n) => self.pos as i64 + n,
  75             };
  76
  77             if pos < 0 {
  78                 Err(Error::new(ErrorKind::InvalidInput,
  79                                "invalid seek to a negative position",
  80                                None))
  81             } else {
  82                 self.pos = pos as u64;
  83                 Ok(self.pos)
  84             }
  85         }
  86     }
  87 }
  88
  89 #[stable(feature = "rust1", since = "1.0.0")]
  90 impl<'a> io::Seek for Cursor<&'a [u8]> { seek!(); }
  91 #[stable(feature = "rust1", since = "1.0.0")]
  92 impl<'a> io::Seek for Cursor<&'a mut [u8]> { seek!(); }
  93 #[stable(feature = "rust1", since = "1.0.0")]
  94 impl io::Seek for Cursor<Vec<u8>> { seek!(); }
  95
  96 macro_rules! read {
  97     () => {
  98         fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
  99             let n = try!(Read::read(&mut try!(self.fill_buf()), buf));
 100             self.pos += n as u64;
 101             Ok(n)
 102         }
 103     }
 104 }
 105
 106 #[stable(feature = "rust1", since = "1.0.0")]
 107 impl<'a> Read for Cursor<&'a [u8]> { read!(); }
 108 #[stable(feature = "rust1", since = "1.0.0")]
 109 impl<'a> Read for Cursor<&'a mut [u8]> { read!(); }
 110 #[stable(feature = "rust1", since = "1.0.0")]
 111 impl Read for Cursor<Vec<u8>> { read!(); }
 112
 113 macro_rules! buffer {
 114     () => {
 115         fn fill_buf(&mut self) -> io::Result<&[u8]> {
 116             let amt = cmp::min(self.pos, self.inner.len() as u64);
 117             Ok(&self.inner[(amt as usize)..])
 118         }
 119         fn consume(&mut self, amt: usize) { self.pos += amt as u64; }
 120     }
 121 }
 122
 123 #[stable(feature = "rust1", since = "1.0.0")]
 124 impl<'a> BufRead for Cursor<&'a [u8]> { buffer!(); }
 125 #[stable(feature = "rust1", since = "1.0.0")]
 126 impl<'a> BufRead for Cursor<&'a mut [u8]> { buffer!(); }
 127 #[stable(feature = "rust1", since = "1.0.0")]
 128 impl<'a> BufRead for Cursor<Vec<u8>> { buffer!(); }
 129
 130 #[stable(feature = "rust1", since = "1.0.0")]
 131 impl<'a> Write for Cursor<&'a mut [u8]> {
 132     fn write(&mut self, data: &[u8]) -> io::Result<usize> {
 133         let pos = cmp::min(self.pos, self.inner.len() as u64);
 134         let amt = try!((&mut self.inner[(pos as usize)..]).write(data));
 135         self.pos += amt as u64;
 136         Ok(amt)
 137     }
 138     fn flush(&mut self) -> io::Result<()> { Ok(()) }
 139 }
 140
 141 #[stable(feature = "rust1", since = "1.0.0")]
 142 impl Write for Cursor<Vec<u8>> {
 143     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 144         // Make sure the internal buffer is as least as big as where we
 145         // currently are
 146         let pos = self.position();
 147         let amt = pos.saturating_sub(self.inner.len() as u64);
 148         self.inner.extend(repeat(0).take(amt as usize));
 149
 150         // Figure out what bytes will be used to overwrite what's currently
 151         // there (left), and what will be appended on the end (right)
 152         let space = self.inner.len() - pos as usize;
 153         let (left, right) = buf.split_at(cmp::min(space, buf.len()));
 154         slice::bytes::copy_memory(&mut self.inner[(pos as usize)..], left);
 155         self.inner.push_all(right);
 156
 157         // Bump us forward
 158         self.set_position(pos + buf.len() as u64);
 159         Ok(buf.len())
 160     }
 161     fn flush(&mut self) -> io::Result<()> { Ok(()) }
 162 }
 163
 164
 165 #[cfg(test)]
 166 mod tests {
 167     use core::prelude::*;
 168
 169     use io::prelude::*;
 170     use io::{Cursor, SeekFrom};
 171     use vec::Vec;
 172
 173     #[test]
 174     fn test_vec_writer() {
 175         let mut writer = Vec::new();
 176         assert_eq!(writer.write(&[0]), Ok(1));
 177         assert_eq!(writer.write(&[1, 2, 3]), Ok(3));
 178         assert_eq!(writer.write(&[4, 5, 6, 7]), Ok(4));
 179         let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7];
 180         assert_eq!(writer, b);
 181     }
 182
 183     #[test]
 184     fn test_mem_writer() {
 185         let mut writer = Cursor::new(Vec::new());
 186         assert_eq!(writer.write(&[0]), Ok(1));
 187         assert_eq!(writer.write(&[1, 2, 3]), Ok(3));
 188         assert_eq!(writer.write(&[4, 5, 6, 7]), Ok(4));
 189         let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7];
 190         assert_eq!(&writer.get_ref()[..], b);
 191     }
 192
 193     #[test]
 194     fn test_buf_writer() {
 195         let mut buf = [0 as u8; 9];
 196         {
 197             let mut writer = Cursor::new(&mut buf[..]);
 198             assert_eq!(writer.position(), 0);
 199             assert_eq!(writer.write(&[0]), Ok(1));
 200             assert_eq!(writer.position(), 1);
 201             assert_eq!(writer.write(&[1, 2, 3]), Ok(3));
 202             assert_eq!(writer.write(&[4, 5, 6, 7]), Ok(4));
 203             assert_eq!(writer.position(), 8);
 204             assert_eq!(writer.write(&[]), Ok(0));
 205             assert_eq!(writer.position(), 8);
 206
 207             assert_eq!(writer.write(&[8, 9]), Ok(1));
 208             assert_eq!(writer.write(&[10]), Ok(0));
 209         }
 210         let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8];
 211         assert_eq!(buf, b);
 212     }
 213
 214     #[test]
 215     fn test_buf_writer_seek() {
 216         let mut buf = [0 as u8; 8];
 217         {
 218             let mut writer = Cursor::new(&mut buf[..]);
 219             assert_eq!(writer.position(), 0);
 220             assert_eq!(writer.write(&[1]), Ok(1));
 221             assert_eq!(writer.position(), 1);
 222
 223             assert_eq!(writer.seek(SeekFrom::Start(2)), Ok(2));
 224             assert_eq!(writer.position(), 2);
 225             assert_eq!(writer.write(&[2]), Ok(1));
 226             assert_eq!(writer.position(), 3);
 227
 228             assert_eq!(writer.seek(SeekFrom::Current(-2)), Ok(1));
 229             assert_eq!(writer.position(), 1);
 230             assert_eq!(writer.write(&[3]), Ok(1));
 231             assert_eq!(writer.position(), 2);
 232
 233             assert_eq!(writer.seek(SeekFrom::End(-1)), Ok(7));
 234             assert_eq!(writer.position(), 7);
 235             assert_eq!(writer.write(&[4]), Ok(1));
 236             assert_eq!(writer.position(), 8);
 237
 238         }
 239         let b: &[_] = &[1, 3, 2, 0, 0, 0, 0, 4];
 240         assert_eq!(buf, b);
 241     }
 242
 243     #[test]
 244     fn test_buf_writer_error() {
 245         let mut buf = [0 as u8; 2];
 246         let mut writer = Cursor::new(&mut buf[..]);
 247         assert_eq!(writer.write(&[0]), Ok(1));
 248         assert_eq!(writer.write(&[0, 0]), Ok(1));
 249         assert_eq!(writer.write(&[0, 0]), Ok(0));
 250     }
 251
 252     #[test]
 253     fn test_mem_reader() {
 254         let mut reader = Cursor::new(vec!(0, 1, 2, 3, 4, 5, 6, 7));
 255         let mut buf = [];
 256         assert_eq!(reader.read(&mut buf), Ok(0));
 257         assert_eq!(reader.position(), 0);
 258         let mut buf = [0];
 259         assert_eq!(reader.read(&mut buf), Ok(1));
 260         assert_eq!(reader.position(), 1);
 261         let b: &[_] = &[0];
 262         assert_eq!(buf, b);
 263         let mut buf = [0; 4];
 264         assert_eq!(reader.read(&mut buf), Ok(4));
 265         assert_eq!(reader.position(), 5);
 266         let b: &[_] = &[1, 2, 3, 4];
 267         assert_eq!(buf, b);
 268         assert_eq!(reader.read(&mut buf), Ok(3));
 269         let b: &[_] = &[5, 6, 7];
 270         assert_eq!(&buf[..3], b);
 271         assert_eq!(reader.read(&mut buf), Ok(0));
 272     }
 273
 274     #[test]
 275     fn read_to_end() {
 276         let mut reader = Cursor::new(vec!(0, 1, 2, 3, 4, 5, 6, 7));
 277         let mut v = Vec::new();
 278         reader.read_to_end(&mut v).unwrap();
 279         assert_eq!(v, [0, 1, 2, 3, 4, 5, 6, 7]);
 280     }
 281
 282     #[test]
 283     fn test_slice_reader() {
 284         let in_buf = vec![0, 1, 2, 3, 4, 5, 6, 7];
 285         let mut reader = &mut in_buf.as_slice();
 286         let mut buf = [];
 287         assert_eq!(reader.read(&mut buf), Ok(0));
 288         let mut buf = [0];
 289         assert_eq!(reader.read(&mut buf), Ok(1));
 290         assert_eq!(reader.len(), 7);
 291         let b: &[_] = &[0];
 292         assert_eq!(buf.as_slice(), b);
 293         let mut buf = [0; 4];
 294         assert_eq!(reader.read(&mut buf), Ok(4));
 295         assert_eq!(reader.len(), 3);
 296         let b: &[_] = &[1, 2, 3, 4];
 297         assert_eq!(buf.as_slice(), b);
 298         assert_eq!(reader.read(&mut buf), Ok(3));
 299         let b: &[_] = &[5, 6, 7];
 300         assert_eq!(&buf[..3], b);
 301         assert_eq!(reader.read(&mut buf), Ok(0));
 302     }
 303
 304     #[test]
 305     fn test_buf_reader() {
 306         let in_buf = vec![0, 1, 2, 3, 4, 5, 6, 7];
 307         let mut reader = Cursor::new(in_buf.as_slice());
 308         let mut buf = [];
 309         assert_eq!(reader.read(&mut buf), Ok(0));
 310         assert_eq!(reader.position(), 0);
 311         let mut buf = [0];
 312         assert_eq!(reader.read(&mut buf), Ok(1));
 313         assert_eq!(reader.position(), 1);
 314         let b: &[_] = &[0];
 315         assert_eq!(buf, b);
 316         let mut buf = [0; 4];
 317         assert_eq!(reader.read(&mut buf), Ok(4));
 318         assert_eq!(reader.position(), 5);
 319         let b: &[_] = &[1, 2, 3, 4];
 320         assert_eq!(buf, b);
 321         assert_eq!(reader.read(&mut buf), Ok(3));
 322         let b: &[_] = &[5, 6, 7];
 323         assert_eq!(&buf[..3], b);
 324         assert_eq!(reader.read(&mut buf), Ok(0));
 325     }
 326
 327     #[test]
 328     fn test_read_char() {
 329         let b = &b"Vi\xE1\xBB\x87t"[..];
 330         let mut c = Cursor::new(b).chars();
 331         assert_eq!(c.next(), Some(Ok('V')));
 332         assert_eq!(c.next(), Some(Ok('i')));
 333         assert_eq!(c.next(), Some(Ok('ệ')));
 334         assert_eq!(c.next(), Some(Ok('t')));
 335         assert_eq!(c.next(), None);
 336     }
 337
 338     #[test]
 339     fn test_read_bad_char() {
 340         let b = &b"\x80"[..];
 341         let mut c = Cursor::new(b).chars();
 342         assert!(c.next().unwrap().is_err());
 343     }
 344
 345     #[test]
 346     fn seek_past_end() {
 347         let buf = [0xff];
 348         let mut r = Cursor::new(&buf[..]);
 349         assert_eq!(r.seek(SeekFrom::Start(10)), Ok(10));
 350         assert_eq!(r.read(&mut [0]), Ok(0));
 351
 352         let mut r = Cursor::new(vec!(10));
 353         assert_eq!(r.seek(SeekFrom::Start(10)), Ok(10));
 354         assert_eq!(r.read(&mut [0]), Ok(0));
 355
 356         let mut buf = [0];
 357         let mut r = Cursor::new(&mut buf[..]);
 358         assert_eq!(r.seek(SeekFrom::Start(10)), Ok(10));
 359         assert_eq!(r.write(&[3]), Ok(0));
 360     }
 361
 362     #[test]
 363     fn seek_before_0() {
 364         let buf = [0xff];
 365         let mut r = Cursor::new(&buf[..]);
 366         assert!(r.seek(SeekFrom::End(-2)).is_err());
 367
 368         let mut r = Cursor::new(vec!(10));
 369         assert!(r.seek(SeekFrom::End(-2)).is_err());
 370
 371         let mut buf = [0];
 372         let mut r = Cursor::new(&mut buf[..]);
 373         assert!(r.seek(SeekFrom::End(-2)).is_err());
 374     }
 375
 376     #[test]
 377     fn test_seekable_mem_writer() {
 378         let mut writer = Cursor::new(Vec::<u8>::new());
 379         assert_eq!(writer.position(), 0);
 380         assert_eq!(writer.write(&[0]), Ok(1));
 381         assert_eq!(writer.position(), 1);
 382         assert_eq!(writer.write(&[1, 2, 3]), Ok(3));
 383         assert_eq!(writer.write(&[4, 5, 6, 7]), Ok(4));
 384         assert_eq!(writer.position(), 8);
 385         let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7];
 386         assert_eq!(&writer.get_ref()[..], b);
 387
 388         assert_eq!(writer.seek(SeekFrom::Start(0)), Ok(0));
 389         assert_eq!(writer.position(), 0);
 390         assert_eq!(writer.write(&[3, 4]), Ok(2));
 391         let b: &[_] = &[3, 4, 2, 3, 4, 5, 6, 7];
 392         assert_eq!(&writer.get_ref()[..], b);
 393
 394         assert_eq!(writer.seek(SeekFrom::Current(1)), Ok(3));
 395         assert_eq!(writer.write(&[0, 1]), Ok(2));
 396         let b: &[_] = &[3, 4, 2, 0, 1, 5, 6, 7];
 397         assert_eq!(&writer.get_ref()[..], b);
 398
 399         assert_eq!(writer.seek(SeekFrom::End(-1)), Ok(7));
 400         assert_eq!(writer.write(&[1, 2]), Ok(2));
 401         let b: &[_] = &[3, 4, 2, 0, 1, 5, 6, 1, 2];
 402         assert_eq!(&writer.get_ref()[..], b);
 403
 404         assert_eq!(writer.seek(SeekFrom::End(1)), Ok(10));
 405         assert_eq!(writer.write(&[1]), Ok(1));
 406         let b: &[_] = &[3, 4, 2, 0, 1, 5, 6, 1, 2, 0, 1];
 407         assert_eq!(&writer.get_ref()[..], b);
 408     }
 409
 410     #[test]
 411     fn vec_seek_past_end() {
 412         let mut r = Cursor::new(Vec::new());
 413         assert_eq!(r.seek(SeekFrom::Start(10)), Ok(10));
 414         assert_eq!(r.write(&[3]), Ok(1));
 415     }
 416
 417     #[test]
 418     fn vec_seek_before_0() {
 419         let mut r = Cursor::new(Vec::new());
 420         assert!(r.seek(SeekFrom::End(-2)).is_err());
 421     }
 422 }