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