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