]> git.lizzy.rs Git - rust.git/blob - src/libstd/io/mem.rs
Fixed tidy errors
[rust.git] / src / libstd / io / mem.rs
1 // Copyright 2013 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 // ignore-lexer-test FIXME #15679
12
13 //! Readers and Writers for in-memory buffers
14
15 use cmp::min;
16 use option::None;
17 use result::{Err, Ok};
18 use io;
19 use io::{Reader, Writer, Seek, Buffer, IoError, SeekStyle, IoResult};
20 use slice::{mod, AsSlice, ImmutableSlice};
21 use vec::Vec;
22
23 const BUF_CAPACITY: uint = 128;
24
25 fn combine(seek: SeekStyle, cur: uint, end: uint, offset: i64) -> IoResult<u64> {
26     // compute offset as signed and clamp to prevent overflow
27     let pos = match seek {
28         io::SeekSet => 0,
29         io::SeekEnd => end,
30         io::SeekCur => cur,
31     } as i64;
32
33     if offset + pos < 0 {
34         Err(IoError {
35             kind: io::InvalidInput,
36             desc: "invalid seek to a negative offset",
37             detail: None
38         })
39     } else {
40         Ok((offset + pos) as u64)
41     }
42 }
43
44 /// Writes to an owned, growable byte vector
45 ///
46 /// # Example
47 ///
48 /// ```rust
49 /// # #![allow(unused_must_use)]
50 /// use std::io::MemWriter;
51 ///
52 /// let mut w = MemWriter::new();
53 /// w.write([0, 1, 2]);
54 ///
55 /// assert_eq!(w.unwrap(), vec!(0, 1, 2));
56 /// ```
57 #[deriving(Clone)]
58 pub struct MemWriter {
59     buf: Vec<u8>,
60 }
61
62 impl MemWriter {
63     /// Create a new `MemWriter`.
64     #[inline]
65     pub fn new() -> MemWriter {
66         MemWriter::with_capacity(BUF_CAPACITY)
67     }
68     /// Create a new `MemWriter`, allocating at least `n` bytes for
69     /// the internal buffer.
70     #[inline]
71     pub fn with_capacity(n: uint) -> MemWriter {
72         MemWriter::from_vec(Vec::with_capacity(n))
73     }
74     /// Create a new `MemWriter` that will append to an existing `Vec`.
75     #[inline]
76     pub fn from_vec(buf: Vec<u8>) -> MemWriter {
77         MemWriter { buf: buf }
78     }
79
80     /// Acquires an immutable reference to the underlying buffer of this
81     /// `MemWriter`.
82     #[inline]
83     pub fn get_ref<'a>(&'a self) -> &'a [u8] { self.buf.as_slice() }
84
85     /// Unwraps this `MemWriter`, returning the underlying buffer
86     #[inline]
87     pub fn unwrap(self) -> Vec<u8> { self.buf }
88 }
89
90 impl Writer for MemWriter {
91     #[inline]
92     fn write(&mut self, buf: &[u8]) -> IoResult<()> {
93         self.buf.push_all(buf);
94         Ok(())
95     }
96 }
97
98 /// Reads from an owned byte vector
99 ///
100 /// # Example
101 ///
102 /// ```rust
103 /// # #![allow(unused_must_use)]
104 /// use std::io::MemReader;
105 ///
106 /// let mut r = MemReader::new(vec!(0, 1, 2));
107 ///
108 /// assert_eq!(r.read_to_end().unwrap(), vec!(0, 1, 2));
109 /// ```
110 pub struct MemReader {
111     buf: Vec<u8>,
112     pos: uint
113 }
114
115 impl MemReader {
116     /// Creates a new `MemReader` which will read the buffer given. The buffer
117     /// can be re-acquired through `unwrap`
118     #[inline]
119     pub fn new(buf: Vec<u8>) -> MemReader {
120         MemReader {
121             buf: buf,
122             pos: 0
123         }
124     }
125
126     /// Tests whether this reader has read all bytes in its buffer.
127     ///
128     /// If `true`, then this will no longer return bytes from `read`.
129     #[inline]
130     pub fn eof(&self) -> bool { self.pos >= self.buf.len() }
131
132     /// Acquires an immutable reference to the underlying buffer of this
133     /// `MemReader`.
134     ///
135     /// No method is exposed for acquiring a mutable reference to the buffer
136     /// because it could corrupt the state of this `MemReader`.
137     #[inline]
138     pub fn get_ref<'a>(&'a self) -> &'a [u8] { self.buf.as_slice() }
139
140     /// Unwraps this `MemReader`, returning the underlying buffer
141     #[inline]
142     pub fn unwrap(self) -> Vec<u8> { self.buf }
143 }
144
145 impl Reader for MemReader {
146     #[inline]
147     fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> {
148         if self.eof() { return Err(io::standard_error(io::EndOfFile)) }
149
150         let write_len = min(buf.len(), self.buf.len() - self.pos);
151         {
152             let input = self.buf[self.pos.. self.pos + write_len];
153             let output = buf[mut ..write_len];
154             assert_eq!(input.len(), output.len());
155             slice::bytes::copy_memory(output, input);
156         }
157         self.pos += write_len;
158         assert!(self.pos <= self.buf.len());
159
160         return Ok(write_len);
161     }
162 }
163
164 impl Seek for MemReader {
165     #[inline]
166     fn tell(&self) -> IoResult<u64> { Ok(self.pos as u64) }
167
168     #[inline]
169     fn seek(&mut self, pos: i64, style: SeekStyle) -> IoResult<()> {
170         let new = try!(combine(style, self.pos, self.buf.len(), pos));
171         self.pos = new as uint;
172         Ok(())
173     }
174 }
175
176 impl Buffer for MemReader {
177     #[inline]
178     fn fill_buf<'a>(&'a mut self) -> IoResult<&'a [u8]> {
179         if self.pos < self.buf.len() {
180             Ok(self.buf[self.pos..])
181         } else {
182             Err(io::standard_error(io::EndOfFile))
183         }
184     }
185
186     #[inline]
187     fn consume(&mut self, amt: uint) { self.pos += amt; }
188 }
189
190 /// Writes to a fixed-size byte slice
191 ///
192 /// If a write will not fit in the buffer, it returns an error and does not
193 /// write any data.
194 ///
195 /// # Example
196 ///
197 /// ```rust
198 /// # #![allow(unused_must_use)]
199 /// use std::io::BufWriter;
200 ///
201 /// let mut buf = [0, ..4];
202 /// {
203 ///     let mut w = BufWriter::new(buf);
204 ///     w.write([0, 1, 2]);
205 /// }
206 /// assert!(buf == [0, 1, 2, 0]);
207 /// ```
208 pub struct BufWriter<'a> {
209     buf: &'a mut [u8],
210     pos: uint
211 }
212
213 impl<'a> BufWriter<'a> {
214     /// Creates a new `BufWriter` which will wrap the specified buffer. The
215     /// writer initially starts at position 0.
216     #[inline]
217     pub fn new<'a>(buf: &'a mut [u8]) -> BufWriter<'a> {
218         BufWriter {
219             buf: buf,
220             pos: 0
221         }
222     }
223 }
224
225 impl<'a> Writer for BufWriter<'a> {
226     #[inline]
227     fn write(&mut self, buf: &[u8]) -> IoResult<()> {
228         // return an error if the entire write does not fit in the buffer
229         let cap = if self.pos >= self.buf.len() { 0 } else { self.buf.len() - self.pos };
230         if buf.len() > cap {
231             return Err(IoError {
232                 kind: io::OtherIoError,
233                 desc: "Trying to write past end of buffer",
234                 detail: None
235             })
236         }
237
238         slice::bytes::copy_memory(self.buf[mut self.pos..], buf);
239         self.pos += buf.len();
240         Ok(())
241     }
242 }
243
244 impl<'a> Seek for BufWriter<'a> {
245     #[inline]
246     fn tell(&self) -> IoResult<u64> { Ok(self.pos as u64) }
247
248     #[inline]
249     fn seek(&mut self, pos: i64, style: SeekStyle) -> IoResult<()> {
250         let new = try!(combine(style, self.pos, self.buf.len(), pos));
251         self.pos = new as uint;
252         Ok(())
253     }
254 }
255
256 /// Reads from a fixed-size byte slice
257 ///
258 /// # Example
259 ///
260 /// ```rust
261 /// # #![allow(unused_must_use)]
262 /// use std::io::BufReader;
263 ///
264 /// let mut buf = [0, 1, 2, 3];
265 /// let mut r = BufReader::new(buf);
266 ///
267 /// assert_eq!(r.read_to_end().unwrap(), vec!(0, 1, 2, 3));
268 /// ```
269 pub struct BufReader<'a> {
270     buf: &'a [u8],
271     pos: uint
272 }
273
274 impl<'a> BufReader<'a> {
275     /// Creates a new buffered reader which will read the specified buffer
276     #[inline]
277     pub fn new<'a>(buf: &'a [u8]) -> BufReader<'a> {
278         BufReader {
279             buf: buf,
280             pos: 0
281         }
282     }
283
284     /// Tests whether this reader has read all bytes in its buffer.
285     ///
286     /// If `true`, then this will no longer return bytes from `read`.
287     #[inline]
288     pub fn eof(&self) -> bool { self.pos >= self.buf.len() }
289 }
290
291 impl<'a> Reader for BufReader<'a> {
292     #[inline]
293     fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> {
294         if self.eof() { return Err(io::standard_error(io::EndOfFile)) }
295
296         let write_len = min(buf.len(), self.buf.len() - self.pos);
297         {
298             let input = self.buf[self.pos.. self.pos + write_len];
299             let output = buf[mut ..write_len];
300             assert_eq!(input.len(), output.len());
301             slice::bytes::copy_memory(output, input);
302         }
303         self.pos += write_len;
304         assert!(self.pos <= self.buf.len());
305
306         return Ok(write_len);
307      }
308 }
309
310 impl<'a> Seek for BufReader<'a> {
311     #[inline]
312     fn tell(&self) -> IoResult<u64> { Ok(self.pos as u64) }
313
314     #[inline]
315     fn seek(&mut self, pos: i64, style: SeekStyle) -> IoResult<()> {
316         let new = try!(combine(style, self.pos, self.buf.len(), pos));
317         self.pos = new as uint;
318         Ok(())
319     }
320 }
321
322 impl<'a> Buffer for BufReader<'a> {
323     #[inline]
324     fn fill_buf<'a>(&'a mut self) -> IoResult<&'a [u8]> {
325         if self.pos < self.buf.len() {
326             Ok(self.buf[self.pos..])
327         } else {
328             Err(io::standard_error(io::EndOfFile))
329         }
330     }
331
332     #[inline]
333     fn consume(&mut self, amt: uint) { self.pos += amt; }
334 }
335
336 #[cfg(test)]
337 mod test {
338     extern crate test;
339     use prelude::*;
340     use super::*;
341     use io::*;
342     use io;
343     use self::test::Bencher;
344     use str::StrSlice;
345
346     #[test]
347     fn test_mem_writer() {
348         let mut writer = MemWriter::new();
349         writer.write([0]).unwrap();
350         writer.write([1, 2, 3]).unwrap();
351         writer.write([4, 5, 6, 7]).unwrap();
352         let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7];
353         assert_eq!(writer.get_ref(), b);
354     }
355
356     #[test]
357     fn test_buf_writer() {
358         let mut buf = [0 as u8, ..8];
359         {
360             let mut writer = BufWriter::new(buf);
361             assert_eq!(writer.tell(), Ok(0));
362             writer.write([0]).unwrap();
363             assert_eq!(writer.tell(), Ok(1));
364             writer.write([1, 2, 3]).unwrap();
365             writer.write([4, 5, 6, 7]).unwrap();
366             assert_eq!(writer.tell(), Ok(8));
367             writer.write([]).unwrap();
368             assert_eq!(writer.tell(), Ok(8));
369         }
370         let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7];
371         assert_eq!(buf.as_slice(), b);
372     }
373
374     #[test]
375     fn test_buf_writer_seek() {
376         let mut buf = [0 as u8, ..8];
377         {
378             let mut writer = BufWriter::new(buf);
379             assert_eq!(writer.tell(), Ok(0));
380             writer.write([1]).unwrap();
381             assert_eq!(writer.tell(), Ok(1));
382
383             writer.seek(2, SeekSet).unwrap();
384             assert_eq!(writer.tell(), Ok(2));
385             writer.write([2]).unwrap();
386             assert_eq!(writer.tell(), Ok(3));
387
388             writer.seek(-2, SeekCur).unwrap();
389             assert_eq!(writer.tell(), Ok(1));
390             writer.write([3]).unwrap();
391             assert_eq!(writer.tell(), Ok(2));
392
393             writer.seek(-1, SeekEnd).unwrap();
394             assert_eq!(writer.tell(), Ok(7));
395             writer.write([4]).unwrap();
396             assert_eq!(writer.tell(), Ok(8));
397
398         }
399         let b: &[_] = &[1, 3, 2, 0, 0, 0, 0, 4];
400         assert_eq!(buf.as_slice(), b);
401     }
402
403     #[test]
404     fn test_buf_writer_error() {
405         let mut buf = [0 as u8, ..2];
406         let mut writer = BufWriter::new(buf);
407         writer.write([0]).unwrap();
408
409         match writer.write([0, 0]) {
410             Ok(..) => panic!(),
411             Err(e) => assert_eq!(e.kind, io::OtherIoError),
412         }
413     }
414
415     #[test]
416     fn test_mem_reader() {
417         let mut reader = MemReader::new(vec!(0, 1, 2, 3, 4, 5, 6, 7));
418         let mut buf = [];
419         assert_eq!(reader.read(buf), Ok(0));
420         assert_eq!(reader.tell(), Ok(0));
421         let mut buf = [0];
422         assert_eq!(reader.read(buf), Ok(1));
423         assert_eq!(reader.tell(), Ok(1));
424         let b: &[_] = &[0];
425         assert_eq!(buf.as_slice(), b);
426         let mut buf = [0, ..4];
427         assert_eq!(reader.read(buf), Ok(4));
428         assert_eq!(reader.tell(), Ok(5));
429         let b: &[_] = &[1, 2, 3, 4];
430         assert_eq!(buf.as_slice(), b);
431         assert_eq!(reader.read(buf), Ok(3));
432         let b: &[_] = &[5, 6, 7];
433         assert_eq!(buf[0..3], b);
434         assert!(reader.read(buf).is_err());
435         let mut reader = MemReader::new(vec!(0, 1, 2, 3, 4, 5, 6, 7));
436         assert_eq!(reader.read_until(3).unwrap(), vec!(0, 1, 2, 3));
437         assert_eq!(reader.read_until(3).unwrap(), vec!(4, 5, 6, 7));
438         assert!(reader.read(buf).is_err());
439     }
440
441     #[test]
442     fn test_buf_reader() {
443         let in_buf = vec![0, 1, 2, 3, 4, 5, 6, 7];
444         let mut reader = BufReader::new(in_buf.as_slice());
445         let mut buf = [];
446         assert_eq!(reader.read(buf), Ok(0));
447         assert_eq!(reader.tell(), Ok(0));
448         let mut buf = [0];
449         assert_eq!(reader.read(buf), Ok(1));
450         assert_eq!(reader.tell(), Ok(1));
451         let b: &[_] = &[0];
452         assert_eq!(buf.as_slice(), b);
453         let mut buf = [0, ..4];
454         assert_eq!(reader.read(buf), Ok(4));
455         assert_eq!(reader.tell(), Ok(5));
456         let b: &[_] = &[1, 2, 3, 4];
457         assert_eq!(buf.as_slice(), b);
458         assert_eq!(reader.read(buf), Ok(3));
459         let b: &[_] = &[5, 6, 7];
460         assert_eq!(buf[0..3], b);
461         assert!(reader.read(buf).is_err());
462         let mut reader = BufReader::new(in_buf.as_slice());
463         assert_eq!(reader.read_until(3).unwrap(), vec!(0, 1, 2, 3));
464         assert_eq!(reader.read_until(3).unwrap(), vec!(4, 5, 6, 7));
465         assert!(reader.read(buf).is_err());
466     }
467
468     #[test]
469     fn test_read_char() {
470         let b = b"Vi\xE1\xBB\x87t";
471         let mut r = BufReader::new(b);
472         assert_eq!(r.read_char(), Ok('V'));
473         assert_eq!(r.read_char(), Ok('i'));
474         assert_eq!(r.read_char(), Ok('ệ'));
475         assert_eq!(r.read_char(), Ok('t'));
476         assert!(r.read_char().is_err());
477     }
478
479     #[test]
480     fn test_read_bad_char() {
481         let b = b"\x80";
482         let mut r = BufReader::new(b);
483         assert!(r.read_char().is_err());
484     }
485
486     #[test]
487     fn test_write_strings() {
488         let mut writer = MemWriter::new();
489         writer.write_str("testing").unwrap();
490         writer.write_line("testing").unwrap();
491         writer.write_str("testing").unwrap();
492         let mut r = BufReader::new(writer.get_ref());
493         assert_eq!(r.read_to_string().unwrap(), "testingtesting\ntesting".to_string());
494     }
495
496     #[test]
497     fn test_write_char() {
498         let mut writer = MemWriter::new();
499         writer.write_char('a').unwrap();
500         writer.write_char('\n').unwrap();
501         writer.write_char('ệ').unwrap();
502         let mut r = BufReader::new(writer.get_ref());
503         assert_eq!(r.read_to_string().unwrap(), "a\nệ".to_string());
504     }
505
506     #[test]
507     fn test_read_whole_string_bad() {
508         let buf = [0xff];
509         let mut r = BufReader::new(buf);
510         match r.read_to_string() {
511             Ok(..) => panic!(),
512             Err(..) => {}
513         }
514     }
515
516     #[test]
517     fn seek_past_end() {
518         let buf = [0xff];
519         let mut r = BufReader::new(buf);
520         r.seek(10, SeekSet).unwrap();
521         assert!(r.read(&mut []).is_err());
522
523         let mut r = MemReader::new(vec!(10));
524         r.seek(10, SeekSet).unwrap();
525         assert!(r.read(&mut []).is_err());
526
527         let mut buf = [0];
528         let mut r = BufWriter::new(buf);
529         r.seek(10, SeekSet).unwrap();
530         assert!(r.write([3]).is_err());
531     }
532
533     #[test]
534     fn seek_before_0() {
535         let buf = [0xff];
536         let mut r = BufReader::new(buf);
537         assert!(r.seek(-1, SeekSet).is_err());
538
539         let mut r = MemReader::new(vec!(10));
540         assert!(r.seek(-1, SeekSet).is_err());
541
542         let mut buf = [0];
543         let mut r = BufWriter::new(buf);
544         assert!(r.seek(-1, SeekSet).is_err());
545     }
546
547     #[test]
548     fn io_read_at_least() {
549         let mut r = MemReader::new(vec![1, 2, 3, 4, 5, 6, 7, 8]);
550         let mut buf = [0, ..3];
551         assert!(r.read_at_least(buf.len(), buf).is_ok());
552         let b: &[_] = &[1, 2, 3];
553         assert_eq!(buf.as_slice(), b);
554         assert!(r.read_at_least(0, buf[mut ..0]).is_ok());
555         assert_eq!(buf.as_slice(), b);
556         assert!(r.read_at_least(buf.len(), buf).is_ok());
557         let b: &[_] = &[4, 5, 6];
558         assert_eq!(buf.as_slice(), b);
559         assert!(r.read_at_least(buf.len(), buf).is_err());
560         let b: &[_] = &[7, 8, 6];
561         assert_eq!(buf.as_slice(), b);
562     }
563
564     fn do_bench_mem_writer(b: &mut Bencher, times: uint, len: uint) {
565         let src: Vec<u8> = Vec::from_elem(len, 5);
566
567         b.bytes = (times * len) as u64;
568         b.iter(|| {
569             let mut wr = MemWriter::new();
570             for _ in range(0, times) {
571                 wr.write(src.as_slice()).unwrap();
572             }
573
574             let v = wr.unwrap();
575             assert_eq!(v.len(), times * len);
576             assert!(v.iter().all(|x| *x == 5));
577         });
578     }
579
580     #[bench]
581     fn bench_mem_writer_001_0000(b: &mut Bencher) {
582         do_bench_mem_writer(b, 1, 0)
583     }
584
585     #[bench]
586     fn bench_mem_writer_001_0010(b: &mut Bencher) {
587         do_bench_mem_writer(b, 1, 10)
588     }
589
590     #[bench]
591     fn bench_mem_writer_001_0100(b: &mut Bencher) {
592         do_bench_mem_writer(b, 1, 100)
593     }
594
595     #[bench]
596     fn bench_mem_writer_001_1000(b: &mut Bencher) {
597         do_bench_mem_writer(b, 1, 1000)
598     }
599
600     #[bench]
601     fn bench_mem_writer_100_0000(b: &mut Bencher) {
602         do_bench_mem_writer(b, 100, 0)
603     }
604
605     #[bench]
606     fn bench_mem_writer_100_0010(b: &mut Bencher) {
607         do_bench_mem_writer(b, 100, 10)
608     }
609
610     #[bench]
611     fn bench_mem_writer_100_0100(b: &mut Bencher) {
612         do_bench_mem_writer(b, 100, 100)
613     }
614
615     #[bench]
616     fn bench_mem_writer_100_1000(b: &mut Bencher) {
617         do_bench_mem_writer(b, 100, 1000)
618     }
619
620     #[bench]
621     fn bench_mem_reader(b: &mut Bencher) {
622         b.iter(|| {
623             let buf = [5 as u8, ..100].to_vec();
624             {
625                 let mut rdr = MemReader::new(buf);
626                 for _i in range(0u, 10) {
627                     let mut buf = [0 as u8, .. 10];
628                     rdr.read(buf).unwrap();
629                     assert_eq!(buf.as_slice(), [5, .. 10].as_slice());
630                 }
631             }
632         });
633     }
634
635     #[bench]
636     fn bench_buf_writer(b: &mut Bencher) {
637         b.iter(|| {
638             let mut buf = [0 as u8, ..100];
639             {
640                 let mut wr = BufWriter::new(buf);
641                 for _i in range(0u, 10) {
642                     wr.write([5, .. 10]).unwrap();
643                 }
644             }
645             assert_eq!(buf.as_slice(), [5, .. 100].as_slice());
646         });
647     }
648
649     #[bench]
650     fn bench_buf_reader(b: &mut Bencher) {
651         b.iter(|| {
652             let buf = [5 as u8, ..100];
653             {
654                 let mut rdr = BufReader::new(buf);
655                 for _i in range(0u, 10) {
656                     let mut buf = [0 as u8, .. 10];
657                     rdr.read(buf).unwrap();
658                     assert_eq!(buf.as_slice(), [5, .. 10].as_slice());
659                 }
660             }
661         });
662     }
663 }