1 // Copyright 2017 Brian Langenberger
2 //
3 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
6 // option. This file may not be copied, modified, or distributed
7 // except according to those terms.
8
9 //! Traits and implementations for reading bits from a stream.
10 //!
11 //! ## Example
12 //!
13 //! Reading the initial STREAMINFO block from a FLAC file,
14 //! as documented in its
15 //! [specification](https://xiph.org/flac/format.html#stream).
16 //!
17 //! ```
18 //! use std::io::{Cursor, Read};
19 //! use bitstream_io::{BigEndian, BitReader, BitRead};
20 //!
21 //! let flac: Vec<u8> = vec![0x66,0x4C,0x61,0x43,0x00,0x00,0x00,0x22,
22 //! 0x10,0x00,0x10,0x00,0x00,0x06,0x06,0x00,
23 //! 0x21,0x62,0x0A,0xC4,0x42,0xF0,0x00,0x04,
24 //! 0xA6,0xCC,0xFA,0xF2,0x69,0x2F,0xFD,0xEC,
25 //! 0x2D,0x5B,0x30,0x01,0x76,0xB4,0x62,0x88,
26 //! 0x7D,0x92];
27 //!
28 //! let mut cursor = Cursor::new(&flac);
29 //! {
30 //! let mut reader = BitReader::endian(&mut cursor, BigEndian);
31 //!
32 //! // stream marker
33 //! let mut file_header: [u8; 4] = [0, 0, 0, 0];
34 //! reader.read_bytes(&mut file_header).unwrap();
35 //! assert_eq!(&file_header, b"fLaC");
36 //!
37 //! // metadata block header
38 //! let last_block: bool = reader.read_bit().unwrap();
39 //! let block_type: u8 = reader.read(7).unwrap();
40 //! let block_size: u32 = reader.read(24).unwrap();
41 //! assert_eq!(last_block, false);
42 //! assert_eq!(block_type, 0);
43 //! assert_eq!(block_size, 34);
44 //!
45 //! // STREAMINFO block
46 //! let minimum_block_size: u16 = reader.read(16).unwrap();
47 //! let maximum_block_size: u16 = reader.read(16).unwrap();
48 //! let minimum_frame_size: u32 = reader.read(24).unwrap();
49 //! let maximum_frame_size: u32 = reader.read(24).unwrap();
50 //! let sample_rate: u32 = reader.read(20).unwrap();
51 //! let channels = reader.read::<u8>(3).unwrap() + 1;
52 //! let bits_per_sample = reader.read::<u8>(5).unwrap() + 1;
53 //! let total_samples: u64 = reader.read(36).unwrap();
54 //! assert_eq!(minimum_block_size, 4096);
55 //! assert_eq!(maximum_block_size, 4096);
56 //! assert_eq!(minimum_frame_size, 1542);
57 //! assert_eq!(maximum_frame_size, 8546);
58 //! assert_eq!(sample_rate, 44100);
59 //! assert_eq!(channels, 2);
60 //! assert_eq!(bits_per_sample, 16);
61 //! assert_eq!(total_samples, 304844);
62 //! }
63 //!
64 //! // STREAMINFO's MD5 sum
65 //!
66 //! // Note that the wrapped reader can be used once bitstream reading
67 //! // is finished at exactly the position one would expect.
68 //!
69 //! let mut md5 = [0; 16];
70 //! cursor.read_exact(&mut md5).unwrap();
71 //! assert_eq!(&md5,
72 //! b"\xFA\xF2\x69\x2F\xFD\xEC\x2D\x5B\x30\x01\x76\xB4\x62\x88\x7D\x92");
73 //! ```
74
75 #![warn(missing_docs)]
76
77 use std::io;
78
79 use super::{huffman::ReadHuffmanTree, BitQueue, Endianness, Numeric, PhantomData, SignedNumeric};
80
81 /// A trait for anything that can read a variable number of
82 /// potentially un-aligned values from an input stream
83 pub trait BitRead {
84 /// Reads a single bit from the stream.
85 /// `true` indicates 1, `false` indicates 0
86 ///
87 /// # Errors
88 ///
89 /// Passes along any I/O error from the underlying stream.
read_bit(&mut self) -> io::Result<bool>90 fn read_bit(&mut self) -> io::Result<bool>;
91
92 /// Reads an unsigned value from the stream with
93 /// the given number of bits.
94 ///
95 /// # Errors
96 ///
97 /// Passes along any I/O error from the underlying stream.
98 /// Also returns an error if the output type is too small
99 /// to hold the requested number of bits.
read<U>(&mut self, bits: u32) -> io::Result<U> where U: Numeric100 fn read<U>(&mut self, bits: u32) -> io::Result<U>
101 where
102 U: Numeric;
103
104 /// Reads a twos-complement signed value from the stream with
105 /// the given number of bits.
106 ///
107 /// # Errors
108 ///
109 /// Passes along any I/O error from the underlying stream.
110 /// Also returns an error if the output type is too small
111 /// to hold the requested number of bits.
read_signed<S>(&mut self, bits: u32) -> io::Result<S> where S: SignedNumeric112 fn read_signed<S>(&mut self, bits: u32) -> io::Result<S>
113 where
114 S: SignedNumeric;
115
116 /// Skips the given number of bits in the stream.
117 /// Since this method does not need an accumulator,
118 /// it may be slightly faster than reading to an empty variable.
119 /// In addition, since there is no accumulator,
120 /// there is no upper limit on the number of bits
121 /// which may be skipped.
122 /// These bits are still read from the stream, however,
123 /// and are never skipped via a `seek` method.
124 ///
125 /// # Errors
126 ///
127 /// Passes along any I/O error from the underlying stream.
skip(&mut self, bits: u32) -> io::Result<()>128 fn skip(&mut self, bits: u32) -> io::Result<()>;
129
130 /// Completely fills the given buffer with whole bytes.
131 /// If the stream is already byte-aligned, it will map
132 /// to a faster `read_exact` call. Otherwise it will read
133 /// bytes individually in 8-bit increments.
134 ///
135 /// # Errors
136 ///
137 /// Passes along any I/O error from the underlying stream.
read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()>138 fn read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()> {
139 for b in buf.iter_mut() {
140 *b = self.read(8)?;
141 }
142 Ok(())
143 }
144
145 /// Counts the number of 1 bits in the stream until the next
146 /// 0 bit and returns the amount read.
147 /// Because this field is variably-sized and may be large,
148 /// its output is always a `u32` type.
149 ///
150 /// # Errors
151 ///
152 /// Passes along any I/O error from the underlying stream.
read_unary0(&mut self) -> io::Result<u32>153 fn read_unary0(&mut self) -> io::Result<u32> {
154 let mut unary = 0;
155 while self.read_bit()? {
156 unary += 1;
157 }
158 Ok(unary)
159 }
160
161 /// Counts the number of 0 bits in the stream until the next
162 /// 1 bit and returns the amount read.
163 /// Because this field is variably-sized and may be large,
164 /// its output is always a `u32` type.
165 ///
166 /// # Errors
167 ///
168 /// Passes along any I/O error from the underlying stream.
read_unary1(&mut self) -> io::Result<u32>169 fn read_unary1(&mut self) -> io::Result<u32> {
170 let mut unary = 0;
171 while !(self.read_bit()?) {
172 unary += 1;
173 }
174 Ok(unary)
175 }
176
177 /// Returns true if the stream is aligned at a whole byte.
byte_aligned(&self) -> bool178 fn byte_aligned(&self) -> bool;
179
180 /// Throws away all unread bit values until the next whole byte.
181 /// Does nothing if the stream is already aligned.
byte_align(&mut self)182 fn byte_align(&mut self);
183 }
184
185 /// A trait for anything that can read Huffman codes
186 /// of a given endianness from an input stream
187 pub trait HuffmanRead<E: Endianness> {
188 /// Given a compiled Huffman tree, reads bits from the stream
189 /// until the next symbol is encountered.
190 ///
191 /// # Errors
192 ///
193 /// Passes along any I/O error from the underlying stream.
read_huffman<T>(&mut self, tree: &[ReadHuffmanTree<E, T>]) -> io::Result<T> where T: Clone194 fn read_huffman<T>(&mut self, tree: &[ReadHuffmanTree<E, T>]) -> io::Result<T>
195 where
196 T: Clone;
197 }
198
199 /// For reading non-aligned bits from a stream of bytes in a given endianness.
200 ///
201 /// This will read exactly as many whole bytes needed to return
202 /// the requested number of bits. It may cache up to a single partial byte
203 /// but no more.
204 #[derive(Clone)]
205 pub struct BitReader<R: io::Read, E: Endianness> {
206 reader: R,
207 bitqueue: BitQueue<E, u8>,
208 }
209
210 impl<R: io::Read, E: Endianness> BitReader<R, E> {
211 /// Wraps a BitReader around something that implements `Read`
new(reader: R) -> BitReader<R, E>212 pub fn new(reader: R) -> BitReader<R, E> {
213 BitReader {
214 reader,
215 bitqueue: BitQueue::new(),
216 }
217 }
218
219 /// Wraps a BitReader around something that implements `Read`
220 /// with the given endianness.
endian(reader: R, _endian: E) -> BitReader<R, E>221 pub fn endian(reader: R, _endian: E) -> BitReader<R, E> {
222 BitReader {
223 reader,
224 bitqueue: BitQueue::new(),
225 }
226 }
227
228 /// Unwraps internal reader and disposes of BitReader.
229 ///
230 /// # Warning
231 ///
232 /// Any unread partial bits are discarded.
233 #[inline]
into_reader(self) -> R234 pub fn into_reader(self) -> R {
235 self.reader
236 }
237
238 /// If stream is byte-aligned, provides mutable reference
239 /// to internal reader. Otherwise returns `None`
240 #[inline]
reader(&mut self) -> Option<&mut R>241 pub fn reader(&mut self) -> Option<&mut R> {
242 if self.byte_aligned() {
243 Some(&mut self.reader)
244 } else {
245 None
246 }
247 }
248
249 /// Converts `BitReader` to `ByteReader` in the same endianness.
250 ///
251 /// # Warning
252 ///
253 /// Any unread partial bits are discarded.
254 #[inline]
into_bytereader(self) -> ByteReader<R, E>255 pub fn into_bytereader(self) -> ByteReader<R, E> {
256 ByteReader::new(self.into_reader())
257 }
258
259 /// If stream is byte-aligned, provides temporary `ByteReader`
260 /// in the same endianness. Otherwise returns `None`
261 ///
262 /// # Warning
263 ///
264 /// Any reader bits left over when `ByteReader` is dropped are lost.
265 #[inline]
bytereader(&mut self) -> Option<ByteReader<&mut R, E>>266 pub fn bytereader(&mut self) -> Option<ByteReader<&mut R, E>> {
267 self.reader().map(ByteReader::new)
268 }
269
270 /// Consumes reader and returns any un-read partial byte
271 /// as a `(bits, value)` tuple.
272 ///
273 /// # Examples
274 /// ```
275 /// use std::io::{Read, Cursor};
276 /// use bitstream_io::{BigEndian, BitReader, BitRead};
277 /// let data = [0b1010_0101, 0b0101_1010];
278 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
279 /// assert_eq!(reader.read::<u16>(9).unwrap(), 0b1010_0101_0);
280 /// let (bits, value) = reader.into_unread();
281 /// assert_eq!(bits, 7);
282 /// assert_eq!(value, 0b101_1010);
283 /// ```
284 ///
285 /// ```
286 /// use std::io::{Read, Cursor};
287 /// use bitstream_io::{BigEndian, BitReader, BitRead};
288 /// let data = [0b1010_0101, 0b0101_1010];
289 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
290 /// assert_eq!(reader.read::<u16>(8).unwrap(), 0b1010_0101);
291 /// let (bits, value) = reader.into_unread();
292 /// assert_eq!(bits, 0);
293 /// assert_eq!(value, 0);
294 /// ```
295 #[inline]
into_unread(self) -> (u32, u8)296 pub fn into_unread(self) -> (u32, u8) {
297 (self.bitqueue.len(), self.bitqueue.value())
298 }
299 }
300
301 impl<R: io::Read, E: Endianness> BitRead for BitReader<R, E> {
302 /// # Examples
303 ///
304 /// ```
305 /// use std::io::{Read, Cursor};
306 /// use bitstream_io::{BigEndian, BitReader, BitRead};
307 /// let data = [0b10110111];
308 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
309 /// assert_eq!(reader.read_bit().unwrap(), true);
310 /// assert_eq!(reader.read_bit().unwrap(), false);
311 /// assert_eq!(reader.read_bit().unwrap(), true);
312 /// assert_eq!(reader.read_bit().unwrap(), true);
313 /// assert_eq!(reader.read_bit().unwrap(), false);
314 /// assert_eq!(reader.read_bit().unwrap(), true);
315 /// assert_eq!(reader.read_bit().unwrap(), true);
316 /// assert_eq!(reader.read_bit().unwrap(), true);
317 /// ```
318 ///
319 /// ```
320 /// use std::io::{Read, Cursor};
321 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
322 /// let data = [0b10110111];
323 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
324 /// assert_eq!(reader.read_bit().unwrap(), true);
325 /// assert_eq!(reader.read_bit().unwrap(), true);
326 /// assert_eq!(reader.read_bit().unwrap(), true);
327 /// assert_eq!(reader.read_bit().unwrap(), false);
328 /// assert_eq!(reader.read_bit().unwrap(), true);
329 /// assert_eq!(reader.read_bit().unwrap(), true);
330 /// assert_eq!(reader.read_bit().unwrap(), false);
331 /// assert_eq!(reader.read_bit().unwrap(), true);
332 /// ```
333 #[inline(always)]
read_bit(&mut self) -> io::Result<bool>334 fn read_bit(&mut self) -> io::Result<bool> {
335 if self.bitqueue.is_empty() {
336 self.bitqueue.set(read_byte(&mut self.reader)?, 8);
337 }
338 Ok(self.bitqueue.pop(1) == 1)
339 }
340
341 /// # Examples
342 /// ```
343 /// use std::io::{Read, Cursor};
344 /// use bitstream_io::{BigEndian, BitReader, BitRead};
345 /// let data = [0b10110111];
346 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
347 /// assert_eq!(reader.read::<u8>(1).unwrap(), 0b1);
348 /// assert_eq!(reader.read::<u8>(2).unwrap(), 0b01);
349 /// assert_eq!(reader.read::<u8>(5).unwrap(), 0b10111);
350 /// ```
351 ///
352 /// ```
353 /// use std::io::{Read, Cursor};
354 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
355 /// let data = [0b10110111];
356 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
357 /// assert_eq!(reader.read::<u8>(1).unwrap(), 0b1);
358 /// assert_eq!(reader.read::<u8>(2).unwrap(), 0b11);
359 /// assert_eq!(reader.read::<u8>(5).unwrap(), 0b10110);
360 /// ```
361 ///
362 /// ```
363 /// use std::io::{Read, Cursor};
364 /// use bitstream_io::{BigEndian, BitReader, BitRead};
365 /// let data = [0;10];
366 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
367 /// assert!(reader.read::<u8>(9).is_err()); // can't read 9 bits to u8
368 /// assert!(reader.read::<u16>(17).is_err()); // can't read 17 bits to u16
369 /// assert!(reader.read::<u32>(33).is_err()); // can't read 33 bits to u32
370 /// assert!(reader.read::<u64>(65).is_err()); // can't read 65 bits to u64
371 /// ```
read<U>(&mut self, mut bits: u32) -> io::Result<U> where U: Numeric,372 fn read<U>(&mut self, mut bits: u32) -> io::Result<U>
373 where
374 U: Numeric,
375 {
376 if bits <= U::bits_size() {
377 let bitqueue_len = self.bitqueue.len();
378 if bits <= bitqueue_len {
379 Ok(U::from_u8(self.bitqueue.pop(bits)))
380 } else {
381 let mut acc =
382 BitQueue::from_value(U::from_u8(self.bitqueue.pop_all()), bitqueue_len);
383 bits -= bitqueue_len;
384
385 read_aligned(&mut self.reader, bits / 8, &mut acc)?;
386 read_unaligned(&mut self.reader, bits % 8, &mut acc, &mut self.bitqueue)?;
387 Ok(acc.value())
388 }
389 } else {
390 Err(io::Error::new(
391 io::ErrorKind::InvalidInput,
392 "excessive bits for type read",
393 ))
394 }
395 }
396
397 /// # Examples
398 /// ```
399 /// use std::io::{Read, Cursor};
400 /// use bitstream_io::{BigEndian, BitReader, BitRead};
401 /// let data = [0b10110111];
402 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
403 /// assert_eq!(reader.read_signed::<i8>(4).unwrap(), -5);
404 /// assert_eq!(reader.read_signed::<i8>(4).unwrap(), 7);
405 /// ```
406 ///
407 /// ```
408 /// use std::io::{Read, Cursor};
409 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
410 /// let data = [0b10110111];
411 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
412 /// assert_eq!(reader.read_signed::<i8>(4).unwrap(), 7);
413 /// assert_eq!(reader.read_signed::<i8>(4).unwrap(), -5);
414 /// ```
415 ///
416 /// ```
417 /// use std::io::{Read, Cursor};
418 /// use bitstream_io::{BigEndian, BitReader, BitRead};
419 /// let data = [0;10];
420 /// let mut r = BitReader::endian(Cursor::new(&data), BigEndian);
421 /// assert!(r.read_signed::<i8>(9).is_err()); // can't read 9 bits to i8
422 /// assert!(r.read_signed::<i16>(17).is_err()); // can't read 17 bits to i16
423 /// assert!(r.read_signed::<i32>(33).is_err()); // can't read 33 bits to i32
424 /// assert!(r.read_signed::<i64>(65).is_err()); // can't read 65 bits to i64
425 /// ```
426 #[inline]
read_signed<S>(&mut self, bits: u32) -> io::Result<S> where S: SignedNumeric,427 fn read_signed<S>(&mut self, bits: u32) -> io::Result<S>
428 where
429 S: SignedNumeric,
430 {
431 E::read_signed(self, bits)
432 }
433
434 /// # Examples
435 /// ```
436 /// use std::io::{Read, Cursor};
437 /// use bitstream_io::{BigEndian, BitReader, BitRead};
438 /// let data = [0b10110111];
439 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
440 /// assert!(reader.skip(3).is_ok());
441 /// assert_eq!(reader.read::<u8>(5).unwrap(), 0b10111);
442 /// ```
443 ///
444 /// ```
445 /// use std::io::{Read, Cursor};
446 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
447 /// let data = [0b10110111];
448 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
449 /// assert!(reader.skip(3).is_ok());
450 /// assert_eq!(reader.read::<u8>(5).unwrap(), 0b10110);
451 /// ```
skip(&mut self, mut bits: u32) -> io::Result<()>452 fn skip(&mut self, mut bits: u32) -> io::Result<()> {
453 use std::cmp::min;
454
455 let to_drop = min(self.bitqueue.len(), bits);
456 if to_drop != 0 {
457 self.bitqueue.drop(to_drop);
458 bits -= to_drop;
459 }
460
461 skip_aligned(&mut self.reader, bits / 8)?;
462 skip_unaligned(&mut self.reader, bits % 8, &mut self.bitqueue)
463 }
464
465 /// # Example
466 /// ```
467 /// use std::io::{Read, Cursor};
468 /// use bitstream_io::{BigEndian, BitReader, BitRead};
469 /// let data = b"foobar";
470 /// let mut reader = BitReader::endian(Cursor::new(data), BigEndian);
471 /// assert!(reader.skip(24).is_ok());
472 /// let mut buf = [0;3];
473 /// assert!(reader.read_bytes(&mut buf).is_ok());
474 /// assert_eq!(&buf, b"bar");
475 /// ```
read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()>476 fn read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()> {
477 if self.byte_aligned() {
478 self.reader.read_exact(buf)
479 } else {
480 for b in buf.iter_mut() {
481 *b = self.read(8)?;
482 }
483 Ok(())
484 }
485 }
486
487 /// # Examples
488 /// ```
489 /// use std::io::{Read, Cursor};
490 /// use bitstream_io::{BigEndian, BitReader, BitRead};
491 /// let data = [0b01110111, 0b11111110];
492 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
493 /// assert_eq!(reader.read_unary0().unwrap(), 0);
494 /// assert_eq!(reader.read_unary0().unwrap(), 3);
495 /// assert_eq!(reader.read_unary0().unwrap(), 10);
496 /// ```
497 ///
498 /// ```
499 /// use std::io::{Read, Cursor};
500 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
501 /// let data = [0b11101110, 0b01111111];
502 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
503 /// assert_eq!(reader.read_unary0().unwrap(), 0);
504 /// assert_eq!(reader.read_unary0().unwrap(), 3);
505 /// assert_eq!(reader.read_unary0().unwrap(), 10);
506 /// ```
read_unary0(&mut self) -> io::Result<u32>507 fn read_unary0(&mut self) -> io::Result<u32> {
508 if self.bitqueue.is_empty() {
509 read_aligned_unary(&mut self.reader, 0b1111_1111, &mut self.bitqueue)
510 .map(|u| u + self.bitqueue.pop_1())
511 } else if self.bitqueue.all_1() {
512 let base = self.bitqueue.len();
513 self.bitqueue.clear();
514 read_aligned_unary(&mut self.reader, 0b1111_1111, &mut self.bitqueue)
515 .map(|u| base + u + self.bitqueue.pop_1())
516 } else {
517 Ok(self.bitqueue.pop_1())
518 }
519 }
520
521 /// # Examples
522 /// ```
523 /// use std::io::{Read, Cursor};
524 /// use bitstream_io::{BigEndian, BitReader, BitRead};
525 /// let data = [0b10001000, 0b00000001];
526 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
527 /// assert_eq!(reader.read_unary1().unwrap(), 0);
528 /// assert_eq!(reader.read_unary1().unwrap(), 3);
529 /// assert_eq!(reader.read_unary1().unwrap(), 10);
530 /// ```
531 ///
532 /// ```
533 /// use std::io::{Read, Cursor};
534 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
535 /// let data = [0b00010001, 0b10000000];
536 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
537 /// assert_eq!(reader.read_unary1().unwrap(), 0);
538 /// assert_eq!(reader.read_unary1().unwrap(), 3);
539 /// assert_eq!(reader.read_unary1().unwrap(), 10);
540 /// ```
read_unary1(&mut self) -> io::Result<u32>541 fn read_unary1(&mut self) -> io::Result<u32> {
542 if self.bitqueue.is_empty() {
543 read_aligned_unary(&mut self.reader, 0b0000_0000, &mut self.bitqueue)
544 .map(|u| u + self.bitqueue.pop_0())
545 } else if self.bitqueue.all_0() {
546 let base = self.bitqueue.len();
547 self.bitqueue.clear();
548 read_aligned_unary(&mut self.reader, 0b0000_0000, &mut self.bitqueue)
549 .map(|u| base + u + self.bitqueue.pop_0())
550 } else {
551 Ok(self.bitqueue.pop_0())
552 }
553 }
554
555 /// # Example
556 /// ```
557 /// use std::io::{Read, Cursor};
558 /// use bitstream_io::{BigEndian, BitReader, BitRead};
559 /// let data = [0];
560 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
561 /// assert_eq!(reader.byte_aligned(), true);
562 /// assert!(reader.skip(1).is_ok());
563 /// assert_eq!(reader.byte_aligned(), false);
564 /// assert!(reader.skip(7).is_ok());
565 /// assert_eq!(reader.byte_aligned(), true);
566 /// ```
567 #[inline]
byte_aligned(&self) -> bool568 fn byte_aligned(&self) -> bool {
569 self.bitqueue.is_empty()
570 }
571
572 /// # Example
573 /// ```
574 /// use std::io::{Read, Cursor};
575 /// use bitstream_io::{BigEndian, BitReader, BitRead};
576 /// let data = [0x00, 0xFF];
577 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
578 /// assert_eq!(reader.read::<u8>(4).unwrap(), 0);
579 /// reader.byte_align();
580 /// assert_eq!(reader.read::<u8>(8).unwrap(), 0xFF);
581 /// ```
582 #[inline]
byte_align(&mut self)583 fn byte_align(&mut self) {
584 self.bitqueue.clear()
585 }
586 }
587
588 impl<R: io::Read, E: Endianness> HuffmanRead<E> for BitReader<R, E> {
589 /// # Example
590 /// ```
591 /// use std::io::{Read, Cursor};
592 /// use bitstream_io::{BigEndian, BitReader, HuffmanRead};
593 /// use bitstream_io::huffman::compile_read_tree;
594 /// let tree = compile_read_tree(
595 /// vec![('a', vec![0]),
596 /// ('b', vec![1, 0]),
597 /// ('c', vec![1, 1, 0]),
598 /// ('d', vec![1, 1, 1])]).unwrap();
599 /// let data = [0b10110111];
600 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
601 /// assert_eq!(reader.read_huffman(&tree).unwrap(), 'b');
602 /// assert_eq!(reader.read_huffman(&tree).unwrap(), 'c');
603 /// assert_eq!(reader.read_huffman(&tree).unwrap(), 'd');
604 /// ```
read_huffman<T>(&mut self, tree: &[ReadHuffmanTree<E, T>]) -> io::Result<T> where T: Clone,605 fn read_huffman<T>(&mut self, tree: &[ReadHuffmanTree<E, T>]) -> io::Result<T>
606 where
607 T: Clone,
608 {
609 let mut result: &ReadHuffmanTree<E, T> = &tree[self.bitqueue.to_state()];
610 loop {
611 match result {
612 ReadHuffmanTree::Done(ref value, ref queue_val, ref queue_bits, _) => {
613 self.bitqueue.set(*queue_val, *queue_bits);
614 return Ok(value.clone());
615 }
616 ReadHuffmanTree::Continue(ref tree) => {
617 result = &tree[read_byte(&mut self.reader)? as usize];
618 }
619 ReadHuffmanTree::InvalidState => {
620 panic!("invalid state");
621 }
622 }
623 }
624 }
625 }
626
627 #[inline]
read_byte<R>(mut reader: R) -> io::Result<u8> where R: io::Read,628 fn read_byte<R>(mut reader: R) -> io::Result<u8>
629 where
630 R: io::Read,
631 {
632 let mut buf = [0; 1];
633 reader.read_exact(&mut buf).map(|()| buf[0])
634 }
635
read_aligned<R, E, N>(mut reader: R, bytes: u32, acc: &mut BitQueue<E, N>) -> io::Result<()> where R: io::Read, E: Endianness, N: Numeric,636 fn read_aligned<R, E, N>(mut reader: R, bytes: u32, acc: &mut BitQueue<E, N>) -> io::Result<()>
637 where
638 R: io::Read,
639 E: Endianness,
640 N: Numeric,
641 {
642 debug_assert!(bytes <= 16);
643
644 if bytes > 0 {
645 let mut buf = [0; 16];
646 reader.read_exact(&mut buf[0..bytes as usize])?;
647 for b in &buf[0..bytes as usize] {
648 acc.push(8, N::from_u8(*b));
649 }
650 }
651 Ok(())
652 }
653
skip_aligned<R>(mut reader: R, mut bytes: u32) -> io::Result<()> where R: io::Read,654 fn skip_aligned<R>(mut reader: R, mut bytes: u32) -> io::Result<()>
655 where
656 R: io::Read,
657 {
658 use std::cmp::min;
659
660 /*skip up to 8 bytes at a time
661 (unlike with read_aligned, "bytes" may be larger than any native type)*/
662 let mut buf = [0; 8];
663 while bytes > 0 {
664 let to_read = min(8, bytes);
665 reader.read_exact(&mut buf[0..to_read as usize])?;
666 bytes -= to_read;
667 }
668 Ok(())
669 }
670
671 #[inline]
read_unaligned<R, E, N>( reader: R, bits: u32, acc: &mut BitQueue<E, N>, rem: &mut BitQueue<E, u8>, ) -> io::Result<()> where R: io::Read, E: Endianness, N: Numeric,672 fn read_unaligned<R, E, N>(
673 reader: R,
674 bits: u32,
675 acc: &mut BitQueue<E, N>,
676 rem: &mut BitQueue<E, u8>,
677 ) -> io::Result<()>
678 where
679 R: io::Read,
680 E: Endianness,
681 N: Numeric,
682 {
683 debug_assert!(bits <= 8);
684
685 if bits > 0 {
686 rem.set(read_byte(reader)?, 8);
687 acc.push(bits, N::from_u8(rem.pop(bits)));
688 }
689 Ok(())
690 }
691
692 #[inline]
skip_unaligned<R, E>(reader: R, bits: u32, rem: &mut BitQueue<E, u8>) -> io::Result<()> where R: io::Read, E: Endianness,693 fn skip_unaligned<R, E>(reader: R, bits: u32, rem: &mut BitQueue<E, u8>) -> io::Result<()>
694 where
695 R: io::Read,
696 E: Endianness,
697 {
698 debug_assert!(bits <= 8);
699
700 if bits > 0 {
701 rem.set(read_byte(reader)?, 8);
702 rem.pop(bits);
703 }
704 Ok(())
705 }
706
707 #[inline]
read_aligned_unary<R, E>( mut reader: R, continue_val: u8, rem: &mut BitQueue<E, u8>, ) -> io::Result<u32> where R: io::Read, E: Endianness,708 fn read_aligned_unary<R, E>(
709 mut reader: R,
710 continue_val: u8,
711 rem: &mut BitQueue<E, u8>,
712 ) -> io::Result<u32>
713 where
714 R: io::Read,
715 E: Endianness,
716 {
717 let mut acc = 0;
718 let mut byte = read_byte(reader.by_ref())?;
719 while byte == continue_val {
720 acc += 8;
721 byte = read_byte(reader.by_ref())?;
722 }
723 rem.set(byte, 8);
724 Ok(acc)
725 }
726
727 /// A trait for anything that can read aligned values from an input stream
728 pub trait ByteRead {
729 /// Reads whole numeric value from stream
730 ///
731 /// # Errors
732 ///
733 /// Passes along any I/O error from the underlying stream.
734 ///
735 /// # Examples
736 /// ```
737 /// use std::io::{Read, Cursor};
738 /// use bitstream_io::{BigEndian, ByteReader, ByteRead};
739 /// let data = [0b00000000, 0b11111111];
740 /// let mut reader = ByteReader::endian(Cursor::new(&data), BigEndian);
741 /// assert_eq!(reader.read::<u16>().unwrap(), 0b0000000011111111);
742 /// ```
743 ///
744 /// ```
745 /// use std::io::{Read, Cursor};
746 /// use bitstream_io::{LittleEndian, ByteReader, ByteRead};
747 /// let data = [0b00000000, 0b11111111];
748 /// let mut reader = ByteReader::endian(Cursor::new(&data), LittleEndian);
749 /// assert_eq!(reader.read::<u16>().unwrap(), 0b1111111100000000);
750 /// ```
read<N: Numeric>(&mut self) -> Result<N, io::Error>751 fn read<N: Numeric>(&mut self) -> Result<N, io::Error>;
752
753 /// Completely fills the given buffer with whole bytes.
754 ///
755 /// # Errors
756 ///
757 /// Passes along any I/O error from the underlying stream.
read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()>758 fn read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()> {
759 for b in buf.iter_mut() {
760 *b = self.read()?;
761 }
762 Ok(())
763 }
764 }
765
766 /// For reading aligned bytes from a stream of bytes in a given endianness.
767 ///
768 /// This only reads aligned values and maintains no internal state.
769 pub struct ByteReader<R: io::Read, E: Endianness> {
770 phantom: PhantomData<E>,
771 reader: R,
772 }
773
774 impl<R: io::Read, E: Endianness> ByteReader<R, E> {
775 /// Wraps a ByteReader around something that implements `Read`
new(reader: R) -> ByteReader<R, E>776 pub fn new(reader: R) -> ByteReader<R, E> {
777 ByteReader {
778 phantom: PhantomData,
779 reader,
780 }
781 }
782
783 /// Wraps a ByteReader around something that implements `Read`
784 /// with the given endianness.
endian(reader: R, _endian: E) -> ByteReader<R, E>785 pub fn endian(reader: R, _endian: E) -> ByteReader<R, E> {
786 ByteReader {
787 phantom: PhantomData,
788 reader,
789 }
790 }
791
792 /// Unwraps internal reader and disposes of `ByteReader`.
793 #[inline]
into_reader(self) -> R794 pub fn into_reader(self) -> R {
795 self.reader
796 }
797
798 /// Provides mutable reference to internal reader
799 #[inline]
reader(&mut self) -> &mut R800 pub fn reader(&mut self) -> &mut R {
801 &mut self.reader
802 }
803
804 /// Converts `ByteReader` to `BitReader` in the same endianness.
805 #[inline]
into_bitreader(self) -> BitReader<R, E>806 pub fn into_bitreader(self) -> BitReader<R, E> {
807 BitReader::new(self.into_reader())
808 }
809
810 /// Provides temporary `BitReader` in the same endianness.
811 ///
812 /// # Warning
813 ///
814 /// Any unread bits left over when `BitReader` is dropped are lost.
815 #[inline]
bitreader(&mut self) -> BitReader<&mut R, E>816 pub fn bitreader(&mut self) -> BitReader<&mut R, E> {
817 BitReader::new(self.reader())
818 }
819 }
820
821 impl<R: io::Read, E: Endianness> ByteRead for ByteReader<R, E> {
822 #[inline]
read<N: Numeric>(&mut self) -> Result<N, io::Error>823 fn read<N: Numeric>(&mut self) -> Result<N, io::Error> {
824 E::read_numeric(&mut self.reader)
825 }
826
827 #[inline]
read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()>828 fn read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()> {
829 self.reader.read_exact(buf)
830 }
831 }
832