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::*;
20//!
21//! #[derive(Debug, PartialEq, Eq)]
22//! struct BlockHeader {
23//! last_block: bool, // 1 bit
24//! block_type: u8, // 7 bits
25//! block_size: u32, // 24 bits
26//! }
27//!
28//! impl FromBitStream for BlockHeader {
29//! type Error = std::io::Error;
30//!
31//! fn from_reader<R: BitRead + ?Sized>(r: &mut R) -> std::io::Result<Self> {
32//! Ok(Self {
33//! last_block: r.read_bit()?,
34//! block_type: r.read_in::<7, _>()?,
35//! block_size: r.read_in::<24, _>()?,
36//! })
37//! }
38//! }
39//!
40//! #[derive(Debug, PartialEq, Eq)]
41//! struct Streaminfo {
42//! minimum_block_size: u16, // 16 bits
43//! maximum_block_size: u16, // 16 bits
44//! minimum_frame_size: u32, // 24 bits
45//! maximum_frame_size: u32, // 24 bits
46//! sample_rate: u32, // 20 bits
47//! channels: u8, // 3 bits
48//! bits_per_sample: u8, // 5 bits
49//! total_samples: u64, // 36 bits
50//! md5: [u8; 16], // 16 bytes
51//! }
52//!
53//! impl FromBitStream for Streaminfo {
54//! type Error = std::io::Error;
55//!
56//! fn from_reader<R: BitRead + ?Sized>(r: &mut R) -> std::io::Result<Self> {
57//! Ok(Self {
58//! minimum_block_size: r.read_to()?,
59//! maximum_block_size: r.read_to()?,
60//! minimum_frame_size: r.read_in::<24, _>()?,
61//! maximum_frame_size: r.read_in::<24, _>()?,
62//! sample_rate: r.read_in::<20, _>()?,
63//! channels: r.read_in::<3, u8>()? + 1,
64//! bits_per_sample: r.read_in::<5, u8>()? + 1,
65//! total_samples: r.read_in::<36, _>()?,
66//! md5: r.read_to()?,
67//! })
68//! }
69//! }
70//!
71//! #[derive(Debug, PartialEq, Eq)]
72//! struct VorbisComment {
73//! vendor: String,
74//! comment: Vec<String>,
75//! }
76//!
77//! impl FromBitStream for VorbisComment {
78//! type Error = Box<dyn std::error::Error>;
79//!
80//! fn from_reader<R: BitRead + ?Sized>(r: &mut R) -> Result<Self, Self::Error> {
81//! use bitstream_io::LE;
82//!
83//! fn read_entry<R: BitRead + ?Sized>(
84//! r: &mut R,
85//! ) -> Result<String, Box<dyn std::error::Error>> {
86//! use std::convert::TryInto;
87//! let size = r.read_as_to::<LE, u32>()?.try_into()?;
88//! Ok(String::from_utf8(r.read_to_vec(size)?)?)
89//! }
90//!
91//! Ok(Self {
92//! vendor: read_entry(r)?,
93//! comment: (0..r.read_as_to::<LE, u32>()?)
94//! .map(|_| read_entry(r))
95//! .collect::<Result<Vec<_>, _>>()?,
96//! })
97//! }
98//! }
99//!
100//! // test FLAC file data
101//! let flac: Vec<u8> = vec![0x66,0x4c,0x61,0x43,0x00,0x00,0x00,0x22,
102//! 0x10,0x00,0x10,0x00,0x00,0x06,0x06,0x00,
103//! 0x21,0x62,0x0a,0xc4,0x42,0xf0,0x00,0x04,
104//! 0xa6,0xcc,0xfa,0xf2,0x69,0x2f,0xfd,0xec,
105//! 0x2d,0x5b,0x30,0x01,0x76,0xb4,0x62,0x88,
106//! 0x7d,0x92,0x04,0x00,0x00,0x7a,0x20,0x00,
107//! 0x00,0x00,0x72,0x65,0x66,0x65,0x72,0x65,
108//! 0x6e,0x63,0x65,0x20,0x6c,0x69,0x62,0x46,
109//! 0x4c,0x41,0x43,0x20,0x31,0x2e,0x31,0x2e,
110//! 0x34,0x20,0x32,0x30,0x30,0x37,0x30,0x32,
111//! 0x31,0x33,0x04,0x00,0x00,0x00,0x16,0x00,
112//! 0x00,0x00,0x74,0x69,0x74,0x6c,0x65,0x3d,
113//! 0x32,0x63,0x68,0x20,0x34,0x34,0x31,0x30,
114//! 0x30,0x20,0x20,0x31,0x36,0x62,0x69,0x74,
115//! 0x10,0x00,0x00,0x00,0x61,0x6c,0x62,0x75,
116//! 0x6d,0x3d,0x54,0x65,0x73,0x74,0x20,0x41,
117//! 0x6c,0x62,0x75,0x6d,0x0f,0x00,0x00,0x00,
118//! 0x61,0x72,0x74,0x69,0x73,0x74,0x3d,0x41,
119//! 0x73,0x73,0x6f,0x72,0x74,0x65,0x64,0x0d,
120//! 0x00,0x00,0x00,0x74,0x72,0x61,0x63,0x6b,
121//! 0x6e,0x75,0x6d,0x62,0x65,0x72,0x3d,0x31];
122//!
123//! let mut cursor = Cursor::new(&flac);
124//!
125//! let mut reader = BitReader::endian(&mut cursor, BigEndian);
126//!
127//! // stream marker
128//! assert_eq!(&reader.read_to::<[u8; 4]>().unwrap(), b"fLaC");
129//!
130//! // metadata block header
131//! assert_eq!(
132//! reader.parse::<BlockHeader>().unwrap(),
133//! BlockHeader { last_block: false, block_type: 0, block_size: 34 }
134//! );
135//!
136//! // STREAMINFO block
137//! assert_eq!(
138//! reader.parse::<Streaminfo>().unwrap(),
139//! Streaminfo {
140//! minimum_block_size: 4096,
141//! maximum_block_size: 4096,
142//! minimum_frame_size: 1542,
143//! maximum_frame_size: 8546,
144//! sample_rate: 44100,
145//! channels: 2,
146//! bits_per_sample: 16,
147//! total_samples: 304844,
148//! md5: *b"\xFA\xF2\x69\x2F\xFD\xEC\x2D\x5B\x30\x01\x76\xB4\x62\x88\x7D\x92",
149//! }
150//! );
151//!
152//! // metadata block header
153//! assert_eq!(
154//! reader.parse::<BlockHeader>().unwrap(),
155//! BlockHeader { last_block: false, block_type: 4, block_size: 122 }
156//! );
157//!
158//! // VORBIS_COMMENT block
159//! assert_eq!(
160//! reader.parse::<VorbisComment>().unwrap(),
161//! VorbisComment {
162//! vendor: "reference libFLAC 1.1.4 20070213".to_string(),
163//! comment: vec![
164//! "title=2ch 44100 16bit".to_string(),
165//! "album=Test Album".to_string(),
166//! "artist=Assorted".to_string(),
167//! "tracknumber=1".to_string(),
168//! ],
169//! }
170//! );
171
172#![warn(missing_docs)]
173
174#[cfg(feature = "alloc")]
175use alloc::vec;
176#[cfg(feature = "alloc")]
177use alloc::vec::Vec;
178#[cfg(feature = "alloc")]
179use core2::io::{self, SeekFrom};
180#[cfg(not(feature = "alloc"))]
181use std::io::{self, SeekFrom};
182
183use super::{
184 huffman::ReadHuffmanTree, BitQueue, Endianness, Numeric, PhantomData, Primitive, SignedNumeric,
185};
186
187/// A trait for anything that can read a variable number of
188/// potentially un-aligned values from an input stream
189pub trait BitRead {
190 /// Reads a single bit from the stream.
191 /// `true` indicates 1, `false` indicates 0
192 ///
193 /// # Errors
194 ///
195 /// Passes along any I/O error from the underlying stream.
196 fn read_bit(&mut self) -> io::Result<bool>;
197
198 /// Reads an unsigned value from the stream with
199 /// the given number of bits.
200 ///
201 /// # Errors
202 ///
203 /// Passes along any I/O error from the underlying stream.
204 /// Also returns an error if the output type is too small
205 /// to hold the requested number of bits.
206 fn read<U>(&mut self, bits: u32) -> io::Result<U>
207 where
208 U: Numeric;
209
210 /// Reads an unsigned value from the stream with
211 /// the given constant number of bits.
212 ///
213 /// # Errors
214 ///
215 /// Passes along any I/O error from the underlying stream.
216 /// A compile-time error occurs if the given number of bits
217 /// is larger than the output type.
218 fn read_in<const BITS: u32, U>(&mut self) -> io::Result<U>
219 where
220 U: Numeric,
221 {
222 self.read(BITS)
223 }
224
225 /// Reads a twos-complement signed value from the stream with
226 /// the given number of bits.
227 ///
228 /// # Errors
229 ///
230 /// Passes along any I/O error from the underlying stream.
231 /// Returns an error if the number of bits is 0,
232 /// since one bit is always needed for the sign.
233 /// Also returns an error if the output type is too small
234 /// to hold the requested number of bits.
235 fn read_signed<S>(&mut self, bits: u32) -> io::Result<S>
236 where
237 S: SignedNumeric;
238
239 /// Reads a twos-complement signed value from the stream with
240 /// the given constant number of bits.
241 ///
242 /// # Errors
243 ///
244 /// Passes along any I/O error from the underlying stream.
245 /// A compile-time error occurs if the number of bits is 0,
246 /// since one bit is always needed for the sign.
247 /// A compile-time error occurs if the given number of bits
248 /// is larger than the output type.
249 fn read_signed_in<const BITS: u32, S>(&mut self) -> io::Result<S>
250 where
251 S: SignedNumeric,
252 {
253 self.read_signed(BITS)
254 }
255
256 /// Reads whole value from the stream whose size in bits is equal
257 /// to its type's size.
258 ///
259 /// # Errors
260 ///
261 /// Passes along any I/O error from the underlying stream.
262 fn read_to<V>(&mut self) -> io::Result<V>
263 where
264 V: Primitive;
265
266 /// Reads whole value from the stream whose size in bits is equal
267 /// to its type's size in an endianness that may be different
268 /// from the stream's endianness.
269 ///
270 /// # Errors
271 ///
272 /// Passes along any I/O error from the underlying stream.
273 fn read_as_to<F, V>(&mut self) -> io::Result<V>
274 where
275 F: Endianness,
276 V: Primitive;
277
278 /// Skips the given number of bits in the stream.
279 /// Since this method does not need an accumulator,
280 /// it may be slightly faster than reading to an empty variable.
281 /// In addition, since there is no accumulator,
282 /// there is no upper limit on the number of bits
283 /// which may be skipped.
284 /// These bits are still read from the stream, however,
285 /// and are never skipped via a `seek` method.
286 ///
287 /// # Errors
288 ///
289 /// Passes along any I/O error from the underlying stream.
290 fn skip(&mut self, bits: u32) -> io::Result<()>;
291
292 /// Completely fills the given buffer with whole bytes.
293 /// If the stream is already byte-aligned, it will map
294 /// to a faster `read_exact` call. Otherwise it will read
295 /// bytes individually in 8-bit increments.
296 ///
297 /// # Errors
298 ///
299 /// Passes along any I/O error from the underlying stream.
300 fn read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()> {
301 for b in buf.iter_mut() {
302 *b = self.read_in::<8, _>()?;
303 }
304 Ok(())
305 }
306
307 /// Completely fills a whole buffer with bytes and returns it.
308 /// If the stream is already byte-aligned, it will map
309 /// to a faster `read_exact` call. Otherwise it will read
310 /// bytes individually in 8-bit increments.
311 ///
312 /// # Errors
313 ///
314 /// Passes along any I/O error from the underlying stream.
315 #[inline(always)]
316 #[deprecated(since = "1.8.0", note = "use read_to() method instead")]
317 fn read_to_bytes<const SIZE: usize>(&mut self) -> io::Result<[u8; SIZE]> {
318 self.read_to()
319 }
320
321 /// Completely fills a vector of bytes and returns it.
322 /// If the stream is already byte-aligned, it will map
323 /// to a faster `read_exact` call. Otherwise it will read
324 /// bytes individually in 8-bit increments.
325 ///
326 /// # Errors
327 ///
328 /// Passes along any I/O error from the underlying stream.
329 fn read_to_vec(&mut self, bytes: usize) -> io::Result<Vec<u8>> {
330 read_to_vec(|buf| self.read_bytes(buf), bytes)
331 }
332
333 /// Counts the number of 1 bits in the stream until the next
334 /// 0 bit and returns the amount read.
335 /// Because this field is variably-sized and may be large,
336 /// its output is always a `u32` type.
337 ///
338 /// # Errors
339 ///
340 /// Passes along any I/O error from the underlying stream.
341 fn read_unary0(&mut self) -> io::Result<u32> {
342 let mut unary = 0;
343 while self.read_bit()? {
344 unary += 1;
345 }
346 Ok(unary)
347 }
348
349 /// Counts the number of 0 bits in the stream until the next
350 /// 1 bit and returns the amount read.
351 /// Because this field is variably-sized and may be large,
352 /// its output is always a `u32` type.
353 ///
354 /// # Errors
355 ///
356 /// Passes along any I/O error from the underlying stream.
357 fn read_unary1(&mut self) -> io::Result<u32> {
358 let mut unary = 0;
359 while !(self.read_bit()?) {
360 unary += 1;
361 }
362 Ok(unary)
363 }
364
365 /// Parses and returns complex type
366 fn parse<F: FromBitStream>(&mut self) -> Result<F, F::Error> {
367 F::from_reader(self)
368 }
369
370 /// Parses and returns complex type with context
371 fn parse_with<'a, F: FromBitStreamWith<'a>>(
372 &mut self,
373 context: &F::Context,
374 ) -> Result<F, F::Error> {
375 F::from_reader(self, context)
376 }
377
378 /// Returns true if the stream is aligned at a whole byte.
379 fn byte_aligned(&self) -> bool;
380
381 /// Throws away all unread bit values until the next whole byte.
382 /// Does nothing if the stream is already aligned.
383 fn byte_align(&mut self);
384}
385
386/// A trait for anything that can read Huffman codes
387/// of a given endianness from an input stream
388pub trait HuffmanRead<E: Endianness> {
389 /// Given a compiled Huffman tree, reads bits from the stream
390 /// until the next symbol is encountered.
391 ///
392 /// # Errors
393 ///
394 /// Passes along any I/O error from the underlying stream.
395 fn read_huffman<T>(&mut self, tree: &[ReadHuffmanTree<E, T>]) -> io::Result<T>
396 where
397 T: Clone;
398}
399
400/// For reading non-aligned bits from a stream of bytes in a given endianness.
401///
402/// This will read exactly as many whole bytes needed to return
403/// the requested number of bits. It may cache up to a single partial byte
404/// but no more.
405#[derive(Clone, Debug)]
406pub struct BitReader<R: io::Read, E: Endianness> {
407 reader: R,
408 bitqueue: BitQueue<E, u8>,
409}
410
411impl<R: io::Read, E: Endianness> BitReader<R, E> {
412 /// Wraps a BitReader around something that implements `Read`
413 pub fn new(reader: R) -> BitReader<R, E> {
414 BitReader {
415 reader,
416 bitqueue: BitQueue::new(),
417 }
418 }
419
420 /// Wraps a BitReader around something that implements `Read`
421 /// with the given endianness.
422 pub fn endian(reader: R, _endian: E) -> BitReader<R, E> {
423 BitReader {
424 reader,
425 bitqueue: BitQueue::new(),
426 }
427 }
428
429 /// Unwraps internal reader and disposes of BitReader.
430 ///
431 /// # Warning
432 ///
433 /// Any unread partial bits are discarded.
434 #[inline]
435 pub fn into_reader(self) -> R {
436 self.reader
437 }
438
439 /// If stream is byte-aligned, provides mutable reference
440 /// to internal reader. Otherwise returns `None`
441 #[inline]
442 pub fn reader(&mut self) -> Option<&mut R> {
443 if self.byte_aligned() {
444 Some(&mut self.reader)
445 } else {
446 None
447 }
448 }
449
450 /// Converts `BitReader` to `ByteReader` in the same endianness.
451 ///
452 /// # Warning
453 ///
454 /// Any unread partial bits are discarded.
455 #[inline]
456 pub fn into_bytereader(self) -> ByteReader<R, E> {
457 ByteReader::new(self.into_reader())
458 }
459
460 /// If stream is byte-aligned, provides temporary `ByteReader`
461 /// in the same endianness. Otherwise returns `None`
462 ///
463 /// # Warning
464 ///
465 /// Any reader bits left over when `ByteReader` is dropped are lost.
466 #[inline]
467 pub fn bytereader(&mut self) -> Option<ByteReader<&mut R, E>> {
468 self.reader().map(ByteReader::new)
469 }
470
471 /// Consumes reader and returns any un-read partial byte
472 /// as a `(bits, value)` tuple.
473 ///
474 /// # Examples
475 /// ```
476 /// use std::io::{Read, Cursor};
477 /// use bitstream_io::{BigEndian, BitReader, BitRead};
478 /// let data = [0b1010_0101, 0b0101_1010];
479 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
480 /// assert_eq!(reader.read::<u16>(9).unwrap(), 0b1010_0101_0);
481 /// let (bits, value) = reader.into_unread();
482 /// assert_eq!(bits, 7);
483 /// assert_eq!(value, 0b101_1010);
484 /// ```
485 ///
486 /// ```
487 /// use std::io::{Read, Cursor};
488 /// use bitstream_io::{BigEndian, BitReader, BitRead};
489 /// let data = [0b1010_0101, 0b0101_1010];
490 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
491 /// assert_eq!(reader.read::<u16>(8).unwrap(), 0b1010_0101);
492 /// let (bits, value) = reader.into_unread();
493 /// assert_eq!(bits, 0);
494 /// assert_eq!(value, 0);
495 /// ```
496 #[inline]
497 pub fn into_unread(self) -> (u32, u8) {
498 (self.bitqueue.len(), self.bitqueue.value())
499 }
500}
501
502impl<R: io::Read, E: Endianness> BitRead for BitReader<R, E> {
503 /// # Examples
504 ///
505 /// ```
506 /// use std::io::{Read, Cursor};
507 /// use bitstream_io::{BigEndian, BitReader, BitRead};
508 /// let data = [0b10110111];
509 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
510 /// assert_eq!(reader.read_bit().unwrap(), true);
511 /// assert_eq!(reader.read_bit().unwrap(), false);
512 /// assert_eq!(reader.read_bit().unwrap(), true);
513 /// assert_eq!(reader.read_bit().unwrap(), true);
514 /// assert_eq!(reader.read_bit().unwrap(), false);
515 /// assert_eq!(reader.read_bit().unwrap(), true);
516 /// assert_eq!(reader.read_bit().unwrap(), true);
517 /// assert_eq!(reader.read_bit().unwrap(), true);
518 /// ```
519 ///
520 /// ```
521 /// use std::io::{Read, Cursor};
522 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
523 /// let data = [0b10110111];
524 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
525 /// assert_eq!(reader.read_bit().unwrap(), true);
526 /// assert_eq!(reader.read_bit().unwrap(), true);
527 /// assert_eq!(reader.read_bit().unwrap(), true);
528 /// assert_eq!(reader.read_bit().unwrap(), false);
529 /// assert_eq!(reader.read_bit().unwrap(), true);
530 /// assert_eq!(reader.read_bit().unwrap(), true);
531 /// assert_eq!(reader.read_bit().unwrap(), false);
532 /// assert_eq!(reader.read_bit().unwrap(), true);
533 /// ```
534 #[inline(always)]
535 fn read_bit(&mut self) -> io::Result<bool> {
536 if self.bitqueue.is_empty() {
537 self.bitqueue.set(read_byte(&mut self.reader)?, 8);
538 }
539 Ok(self.bitqueue.pop(1) == 1)
540 }
541
542 /// # Examples
543 /// ```
544 /// use std::io::{Read, Cursor};
545 /// use bitstream_io::{BigEndian, BitReader, BitRead};
546 /// let data = [0b10110111];
547 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
548 /// assert_eq!(reader.read::<u8>(1).unwrap(), 0b1);
549 /// assert_eq!(reader.read::<u8>(2).unwrap(), 0b01);
550 /// assert_eq!(reader.read::<u8>(5).unwrap(), 0b10111);
551 /// ```
552 ///
553 /// ```
554 /// use std::io::{Read, Cursor};
555 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
556 /// let data = [0b10110111];
557 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
558 /// assert_eq!(reader.read::<u8>(1).unwrap(), 0b1);
559 /// assert_eq!(reader.read::<u8>(2).unwrap(), 0b11);
560 /// assert_eq!(reader.read::<u8>(5).unwrap(), 0b10110);
561 /// ```
562 ///
563 /// ```
564 /// use std::io::{Read, Cursor};
565 /// use bitstream_io::{BigEndian, BitReader, BitRead};
566 /// let data = [0;10];
567 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
568 /// assert!(reader.read::<u8>(9).is_err()); // can't read 9 bits to u8
569 /// assert!(reader.read::<u16>(17).is_err()); // can't read 17 bits to u16
570 /// assert!(reader.read::<u32>(33).is_err()); // can't read 33 bits to u32
571 /// assert!(reader.read::<u64>(65).is_err()); // can't read 65 bits to u64
572 /// ```
573 fn read<U>(&mut self, mut bits: u32) -> io::Result<U>
574 where
575 U: Numeric,
576 {
577 if bits <= U::BITS_SIZE {
578 let bitqueue_len = self.bitqueue.len();
579 if bits <= bitqueue_len {
580 Ok(U::from_u8(self.bitqueue.pop(bits)))
581 } else {
582 let mut acc =
583 BitQueue::from_value(U::from_u8(self.bitqueue.pop_all()), bitqueue_len);
584 bits -= bitqueue_len;
585
586 read_aligned(&mut self.reader, bits / 8, &mut acc)?;
587 read_unaligned(&mut self.reader, bits % 8, &mut acc, &mut self.bitqueue)?;
588 Ok(acc.value())
589 }
590 } else {
591 Err(io::Error::new(
592 io::ErrorKind::InvalidInput,
593 "excessive bits for type read",
594 ))
595 }
596 }
597
598 /// # Examples
599 /// ```
600 /// use std::io::{Read, Cursor};
601 /// use bitstream_io::{BigEndian, BitReader, BitRead};
602 /// let data = [0b10110111];
603 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
604 /// assert_eq!(reader.read_in::<1, u8>().unwrap(), 0b1);
605 /// assert_eq!(reader.read_in::<2, u8>().unwrap(), 0b01);
606 /// assert_eq!(reader.read_in::<5, u8>().unwrap(), 0b10111);
607 /// ```
608 ///
609 /// ```
610 /// use std::io::{Read, Cursor};
611 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
612 /// let data = [0b10110111];
613 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
614 /// assert_eq!(reader.read_in::<1, u8>().unwrap(), 0b1);
615 /// assert_eq!(reader.read_in::<2, u8>().unwrap(), 0b11);
616 /// assert_eq!(reader.read_in::<5, u8>().unwrap(), 0b10110);
617 /// ```
618 #[inline]
619 fn read_in<const BITS: u32, U>(&mut self) -> io::Result<U>
620 where
621 U: Numeric,
622 {
623 const {
624 assert!(BITS <= U::BITS_SIZE, "excessive bits for type read");
625 }
626
627 let bitqueue_len = self.bitqueue.len();
628 if BITS <= bitqueue_len {
629 Ok(U::from_u8(self.bitqueue.pop_fixed::<BITS>()))
630 } else {
631 let mut bits = BITS;
632 let mut acc = BitQueue::from_value(U::from_u8(self.bitqueue.pop_all()), bitqueue_len);
633 bits -= bitqueue_len;
634
635 read_aligned(&mut self.reader, bits / 8, &mut acc)?;
636 read_unaligned(&mut self.reader, bits % 8, &mut acc, &mut self.bitqueue)?;
637 Ok(acc.value())
638 }
639 }
640
641 /// # Examples
642 /// ```
643 /// use std::io::{Read, Cursor};
644 /// use bitstream_io::{BigEndian, BitReader, BitRead};
645 /// let data = [0b10110111];
646 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
647 /// assert_eq!(reader.read_signed::<i8>(4).unwrap(), -5);
648 /// assert_eq!(reader.read_signed::<i8>(4).unwrap(), 7);
649 /// ```
650 ///
651 /// ```
652 /// use std::io::{Read, Cursor};
653 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
654 /// let data = [0b10110111];
655 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
656 /// assert_eq!(reader.read_signed::<i8>(4).unwrap(), 7);
657 /// assert_eq!(reader.read_signed::<i8>(4).unwrap(), -5);
658 /// ```
659 ///
660 /// ```
661 /// use std::io::{Read, Cursor};
662 /// use bitstream_io::{BigEndian, BitReader, BitRead};
663 /// let data = [0;10];
664 /// let mut r = BitReader::endian(Cursor::new(&data), BigEndian);
665 /// assert!(r.read_signed::<i8>(9).is_err()); // can't read 9 bits to i8
666 /// assert!(r.read_signed::<i16>(17).is_err()); // can't read 17 bits to i16
667 /// assert!(r.read_signed::<i32>(33).is_err()); // can't read 33 bits to i32
668 /// assert!(r.read_signed::<i64>(65).is_err()); // can't read 65 bits to i64
669 /// ```
670 #[inline]
671 fn read_signed<S>(&mut self, bits: u32) -> io::Result<S>
672 where
673 S: SignedNumeric,
674 {
675 match bits {
676 0 => Err(io::Error::new(
677 io::ErrorKind::InvalidInput,
678 "signed reads need at least 1 bit for sign",
679 )),
680 bits if bits <= S::BITS_SIZE => E::read_signed(self, bits),
681 _ => Err(io::Error::new(
682 io::ErrorKind::InvalidInput,
683 "excessive bits for type read",
684 )),
685 }
686 }
687
688 /// # Examples
689 /// ```
690 /// use std::io::{Read, Cursor};
691 /// use bitstream_io::{BigEndian, BitReader, BitRead};
692 /// let data = [0b10110111];
693 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
694 /// assert_eq!(reader.read_signed_in::<4, i8>().unwrap(), -5);
695 /// assert_eq!(reader.read_signed_in::<4, i8>().unwrap(), 7);
696 /// ```
697 ///
698 /// ```
699 /// use std::io::{Read, Cursor};
700 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
701 /// let data = [0b10110111];
702 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
703 /// assert_eq!(reader.read_signed_in::<4, i8>().unwrap(), 7);
704 /// assert_eq!(reader.read_signed_in::<4, i8>().unwrap(), -5);
705 /// ```
706 #[inline]
707 fn read_signed_in<const BITS: u32, S>(&mut self) -> io::Result<S>
708 where
709 S: SignedNumeric,
710 {
711 const {
712 assert!(BITS > 0, "signed reads need at least 1 bit for sign");
713 assert!(BITS <= S::BITS_SIZE, "excessive bits for type read");
714 }
715 E::read_signed_fixed::<_, BITS, S>(self)
716 }
717
718 #[inline]
719 fn read_to<V>(&mut self) -> io::Result<V>
720 where
721 V: Primitive,
722 {
723 E::read_primitive(self)
724 }
725
726 #[inline]
727 fn read_as_to<F, V>(&mut self) -> io::Result<V>
728 where
729 F: Endianness,
730 V: Primitive,
731 {
732 F::read_primitive(self)
733 }
734
735 /// # Examples
736 /// ```
737 /// use std::io::{Read, Cursor};
738 /// use bitstream_io::{BigEndian, BitReader, BitRead};
739 /// let data = [0b10110111];
740 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
741 /// assert!(reader.skip(3).is_ok());
742 /// assert_eq!(reader.read::<u8>(5).unwrap(), 0b10111);
743 /// ```
744 ///
745 /// ```
746 /// use std::io::{Read, Cursor};
747 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
748 /// let data = [0b10110111];
749 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
750 /// assert!(reader.skip(3).is_ok());
751 /// assert_eq!(reader.read::<u8>(5).unwrap(), 0b10110);
752 /// ```
753 fn skip(&mut self, mut bits: u32) -> io::Result<()> {
754 use core::cmp::min;
755
756 let to_drop = min(self.bitqueue.len(), bits);
757 if to_drop != 0 {
758 self.bitqueue.drop(to_drop);
759 bits -= to_drop;
760 }
761
762 skip_aligned(&mut self.reader, bits / 8)?;
763 skip_unaligned(&mut self.reader, bits % 8, &mut self.bitqueue)
764 }
765
766 /// # Example
767 /// ```
768 /// use std::io::{Read, Cursor};
769 /// use bitstream_io::{BigEndian, BitReader, BitRead};
770 /// let data = b"foobar";
771 /// let mut reader = BitReader::endian(Cursor::new(data), BigEndian);
772 /// assert!(reader.skip(24).is_ok());
773 /// let mut buf = [0;3];
774 /// assert!(reader.read_bytes(&mut buf).is_ok());
775 /// assert_eq!(&buf, b"bar");
776 /// ```
777 fn read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()> {
778 if self.byte_aligned() {
779 self.reader.read_exact(buf)
780 } else {
781 for b in buf.iter_mut() {
782 *b = self.read_in::<8, _>()?;
783 }
784 Ok(())
785 }
786 }
787
788 /// # Examples
789 /// ```
790 /// use std::io::{Read, Cursor};
791 /// use bitstream_io::{BigEndian, BitReader, BitRead};
792 /// let data = [0b01110111, 0b11111110];
793 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
794 /// assert_eq!(reader.read_unary0().unwrap(), 0);
795 /// assert_eq!(reader.read_unary0().unwrap(), 3);
796 /// assert_eq!(reader.read_unary0().unwrap(), 10);
797 /// ```
798 ///
799 /// ```
800 /// use std::io::{Read, Cursor};
801 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
802 /// let data = [0b11101110, 0b01111111];
803 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
804 /// assert_eq!(reader.read_unary0().unwrap(), 0);
805 /// assert_eq!(reader.read_unary0().unwrap(), 3);
806 /// assert_eq!(reader.read_unary0().unwrap(), 10);
807 /// ```
808 fn read_unary0(&mut self) -> io::Result<u32> {
809 if self.bitqueue.is_empty() {
810 read_aligned_unary(&mut self.reader, 0b1111_1111, &mut self.bitqueue)
811 .map(|u| u + self.bitqueue.pop_1())
812 } else if self.bitqueue.all_1() {
813 let base = self.bitqueue.len();
814 self.bitqueue.clear();
815 read_aligned_unary(&mut self.reader, 0b1111_1111, &mut self.bitqueue)
816 .map(|u| base + u + self.bitqueue.pop_1())
817 } else {
818 Ok(self.bitqueue.pop_1())
819 }
820 }
821
822 /// # Examples
823 /// ```
824 /// use std::io::{Read, Cursor};
825 /// use bitstream_io::{BigEndian, BitReader, BitRead};
826 /// let data = [0b10001000, 0b00000001];
827 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
828 /// assert_eq!(reader.read_unary1().unwrap(), 0);
829 /// assert_eq!(reader.read_unary1().unwrap(), 3);
830 /// assert_eq!(reader.read_unary1().unwrap(), 10);
831 /// ```
832 ///
833 /// ```
834 /// use std::io::{Read, Cursor};
835 /// use bitstream_io::{LittleEndian, BitReader, BitRead};
836 /// let data = [0b00010001, 0b10000000];
837 /// let mut reader = BitReader::endian(Cursor::new(&data), LittleEndian);
838 /// assert_eq!(reader.read_unary1().unwrap(), 0);
839 /// assert_eq!(reader.read_unary1().unwrap(), 3);
840 /// assert_eq!(reader.read_unary1().unwrap(), 10);
841 /// ```
842 fn read_unary1(&mut self) -> io::Result<u32> {
843 if self.bitqueue.is_empty() {
844 read_aligned_unary(&mut self.reader, 0b0000_0000, &mut self.bitqueue)
845 .map(|u| u + self.bitqueue.pop_0())
846 } else if self.bitqueue.all_0() {
847 let base = self.bitqueue.len();
848 self.bitqueue.clear();
849 read_aligned_unary(&mut self.reader, 0b0000_0000, &mut self.bitqueue)
850 .map(|u| base + u + self.bitqueue.pop_0())
851 } else {
852 Ok(self.bitqueue.pop_0())
853 }
854 }
855
856 /// # Example
857 /// ```
858 /// use std::io::{Read, Cursor};
859 /// use bitstream_io::{BigEndian, BitReader, BitRead};
860 /// let data = [0];
861 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
862 /// assert_eq!(reader.byte_aligned(), true);
863 /// assert!(reader.skip(1).is_ok());
864 /// assert_eq!(reader.byte_aligned(), false);
865 /// assert!(reader.skip(7).is_ok());
866 /// assert_eq!(reader.byte_aligned(), true);
867 /// ```
868 #[inline]
869 fn byte_aligned(&self) -> bool {
870 self.bitqueue.is_empty()
871 }
872
873 /// # Example
874 /// ```
875 /// use std::io::{Read, Cursor};
876 /// use bitstream_io::{BigEndian, BitReader, BitRead};
877 /// let data = [0x00, 0xFF];
878 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
879 /// assert_eq!(reader.read::<u8>(4).unwrap(), 0);
880 /// reader.byte_align();
881 /// assert_eq!(reader.read::<u8>(8).unwrap(), 0xFF);
882 /// ```
883 #[inline]
884 fn byte_align(&mut self) {
885 self.bitqueue.clear()
886 }
887}
888
889impl<R, E> BitReader<R, E>
890where
891 E: Endianness,
892 R: io::Read + io::Seek,
893{
894 /// # Example
895 /// ```
896 /// use std::io::{Read, Cursor, SeekFrom};
897 /// use bitstream_io::{BigEndian, BitReader, BitRead};
898 /// let data = [0x00, 0xFF];
899 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
900 /// assert_eq!(reader.position_in_bits().unwrap(), 0);
901 ///
902 /// let pos = reader.seek_bits(SeekFrom::Start(5)).unwrap();
903 /// assert!(pos == 5 && 5 == reader.position_in_bits().unwrap());
904 ///
905 /// let pos = reader.seek_bits(SeekFrom::Current(-2)).unwrap();
906 /// assert!(pos == 3 && 3 == reader.position_in_bits().unwrap()); ///
907 ///
908 /// let pos = reader.seek_bits(SeekFrom::End(5)).unwrap();
909 /// assert!(pos == 11 && 11 == reader.position_in_bits().unwrap());
910 /// ```
911 pub fn seek_bits(&mut self, from: io::SeekFrom) -> io::Result<u64> {
912 match from {
913 io::SeekFrom::Start(from_start_pos) => {
914 let (bytes, bits) = (from_start_pos / 8, (from_start_pos % 8) as u32);
915 self.byte_align();
916 self.reader.seek(io::SeekFrom::Start(bytes))?;
917 self.skip(bits)?;
918 Ok(from_start_pos)
919 }
920 io::SeekFrom::End(from_end_pos) => {
921 let reader_end = self.reader.seek(io::SeekFrom::End(0))?;
922 let new_pos = (reader_end * 8) as i64 - from_end_pos;
923 assert!(new_pos >= 0, "The final position should be greater than 0");
924 self.seek_bits(io::SeekFrom::Start(new_pos as u64))
925 }
926 io::SeekFrom::Current(offset) => {
927 let new_pos = self.position_in_bits()? as i64 + offset;
928 assert!(new_pos >= 0, "The final position should be greater than 0");
929 self.seek_bits(io::SeekFrom::Start(new_pos as u64))
930 }
931 }
932 }
933
934 /// # Example
935 /// ```
936 /// use std::fs::read;
937 /// use std::io::{Read, Cursor, SeekFrom};
938 /// use bitstream_io::{BigEndian, BitReader, BitRead};
939 /// let data = [0x00, 0xFF];
940 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
941 /// assert_eq!(reader.position_in_bits().unwrap(), 0);
942 ///
943 /// let _: i32 = reader.read_signed(5).unwrap();
944 /// assert_eq!(reader.position_in_bits().unwrap(), 5);
945 ///
946 /// reader.read_bit().unwrap();
947 /// assert_eq!(reader.position_in_bits().unwrap(), 6);
948 /// ```
949 #[inline]
950 pub fn position_in_bits(&mut self) -> io::Result<u64> {
951 let bytes = self.reader.seek(SeekFrom::Current(0))?;
952 Ok(bytes * 8 - (self.bitqueue.len() as u64))
953 }
954}
955
956impl<R: io::Read, E: Endianness> HuffmanRead<E> for BitReader<R, E> {
957 /// # Example
958 /// ```
959 /// use std::io::{Read, Cursor};
960 /// use bitstream_io::{BigEndian, BitReader, HuffmanRead};
961 /// use bitstream_io::huffman::compile_read_tree;
962 /// let tree = compile_read_tree(
963 /// vec![('a', vec![0]),
964 /// ('b', vec![1, 0]),
965 /// ('c', vec![1, 1, 0]),
966 /// ('d', vec![1, 1, 1])]).unwrap();
967 /// let data = [0b10110111];
968 /// let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
969 /// assert_eq!(reader.read_huffman(&tree).unwrap(), 'b');
970 /// assert_eq!(reader.read_huffman(&tree).unwrap(), 'c');
971 /// assert_eq!(reader.read_huffman(&tree).unwrap(), 'd');
972 /// ```
973 fn read_huffman<T>(&mut self, tree: &[ReadHuffmanTree<E, T>]) -> io::Result<T>
974 where
975 T: Clone,
976 {
977 let mut result: &ReadHuffmanTree<E, T> = &tree[self.bitqueue.to_state()];
978 loop {
979 match result {
980 ReadHuffmanTree::Done(ref value, ref queue_val, ref queue_bits, _) => {
981 self.bitqueue.set(*queue_val, *queue_bits);
982 return Ok(value.clone());
983 }
984 ReadHuffmanTree::Continue(ref tree) => {
985 result = &tree[read_byte(&mut self.reader)? as usize];
986 }
987 ReadHuffmanTree::InvalidState => {
988 panic!("invalid state");
989 }
990 }
991 }
992 }
993}
994
995#[inline]
996fn read_byte<R>(mut reader: R) -> io::Result<u8>
997where
998 R: io::Read,
999{
1000 let mut byte: u8 = 0;
1001 reader
1002 .read_exact(core::slice::from_mut(&mut byte))
1003 .map(|()| byte)
1004}
1005
1006fn read_aligned<R, E, N>(mut reader: R, bytes: u32, acc: &mut BitQueue<E, N>) -> io::Result<()>
1007where
1008 R: io::Read,
1009 E: Endianness,
1010 N: Numeric,
1011{
1012 if bytes > 0 {
1013 let mut buf: ::Bytes = N::buffer();
1014 reader.read_exact(&mut buf.as_mut()[0..bytes as usize])?;
1015 for b: &u8 in &buf.as_ref()[0..bytes as usize] {
1016 acc.push_fixed::<8>(N::from_u8(*b));
1017 }
1018 }
1019 Ok(())
1020}
1021
1022fn skip_aligned<R>(mut reader: R, mut bytes: u32) -> io::Result<()>
1023where
1024 R: io::Read,
1025{
1026 use core::cmp::min;
1027
1028 /*skip up to 8 bytes at a time
1029 (unlike with read_aligned, "bytes" may be larger than any native type)*/
1030 let mut buf: [u8; 8] = [0; 8];
1031 while bytes > 0 {
1032 let to_read: u32 = min(v1:8, v2:bytes);
1033 reader.read_exact(&mut buf[0..to_read as usize])?;
1034 bytes -= to_read;
1035 }
1036 Ok(())
1037}
1038
1039#[inline]
1040fn read_unaligned<R, E, N>(
1041 reader: R,
1042 bits: u32,
1043 acc: &mut BitQueue<E, N>,
1044 rem: &mut BitQueue<E, u8>,
1045) -> io::Result<()>
1046where
1047 R: io::Read,
1048 E: Endianness,
1049 N: Numeric,
1050{
1051 debug_assert!(bits <= 8);
1052
1053 if bits > 0 {
1054 rem.set(value:read_byte(reader)?, bits:8);
1055 acc.push(bits, N::from_u8(rem.pop(bits)));
1056 }
1057 Ok(())
1058}
1059
1060#[inline]
1061fn skip_unaligned<R, E>(reader: R, bits: u32, rem: &mut BitQueue<E, u8>) -> io::Result<()>
1062where
1063 R: io::Read,
1064 E: Endianness,
1065{
1066 debug_assert!(bits <= 8);
1067
1068 if bits > 0 {
1069 rem.set(value:read_byte(reader)?, bits:8);
1070 rem.pop(bits);
1071 }
1072 Ok(())
1073}
1074
1075#[inline]
1076fn read_aligned_unary<R, E>(
1077 mut reader: R,
1078 continue_val: u8,
1079 rem: &mut BitQueue<E, u8>,
1080) -> io::Result<u32>
1081where
1082 R: io::Read,
1083 E: Endianness,
1084{
1085 let mut acc: u32 = 0;
1086 let mut byte: u8 = read_byte(reader.by_ref())?;
1087 while byte == continue_val {
1088 acc += 8;
1089 byte = read_byte(reader.by_ref())?;
1090 }
1091 rem.set(value:byte, bits:8);
1092 Ok(acc)
1093}
1094
1095/// A trait for anything that can read aligned values from an input stream
1096pub trait ByteRead {
1097 /// Reads whole numeric value from stream
1098 ///
1099 /// # Errors
1100 ///
1101 /// Passes along any I/O error from the underlying stream.
1102 ///
1103 /// # Examples
1104 /// ```
1105 /// use std::io::{Read, Cursor};
1106 /// use bitstream_io::{BigEndian, ByteReader, ByteRead};
1107 /// let data = [0b00000000, 0b11111111];
1108 /// let mut reader = ByteReader::endian(Cursor::new(&data), BigEndian);
1109 /// assert_eq!(reader.read::<u16>().unwrap(), 0b0000000011111111);
1110 /// ```
1111 ///
1112 /// ```
1113 /// use std::io::{Read, Cursor};
1114 /// use bitstream_io::{LittleEndian, ByteReader, ByteRead};
1115 /// let data = [0b00000000, 0b11111111];
1116 /// let mut reader = ByteReader::endian(Cursor::new(&data), LittleEndian);
1117 /// assert_eq!(reader.read::<u16>().unwrap(), 0b1111111100000000);
1118 /// ```
1119 fn read<V>(&mut self) -> Result<V, io::Error>
1120 where
1121 V: Primitive;
1122
1123 /// Reads whole numeric value from stream in a potentially different endianness
1124 ///
1125 /// # Errors
1126 ///
1127 /// Passes along any I/O error from the underlying stream.
1128 ///
1129 /// # Examples
1130 /// ```
1131 /// use std::io::{Read, Cursor};
1132 /// use bitstream_io::{BigEndian, ByteReader, ByteRead, LittleEndian};
1133 /// let data = [0b00000000, 0b11111111];
1134 /// let mut reader = ByteReader::endian(Cursor::new(&data), BigEndian);
1135 /// assert_eq!(reader.read_as::<LittleEndian, u16>().unwrap(), 0b1111111100000000);
1136 /// ```
1137 ///
1138 /// ```
1139 /// use std::io::{Read, Cursor};
1140 /// use bitstream_io::{BigEndian, ByteReader, ByteRead, LittleEndian};
1141 /// let data = [0b00000000, 0b11111111];
1142 /// let mut reader = ByteReader::endian(Cursor::new(&data), LittleEndian);
1143 /// assert_eq!(reader.read_as::<BigEndian, u16>().unwrap(), 0b0000000011111111);
1144 /// ```
1145 fn read_as<F, V>(&mut self) -> Result<V, io::Error>
1146 where
1147 F: Endianness,
1148 V: Primitive;
1149
1150 /// Completely fills the given buffer with whole bytes.
1151 ///
1152 /// # Errors
1153 ///
1154 /// Passes along any I/O error from the underlying stream.
1155 fn read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()> {
1156 for b in buf.iter_mut() {
1157 *b = self.read()?;
1158 }
1159 Ok(())
1160 }
1161
1162 /// Completely fills a whole buffer with bytes and returns it.
1163 ///
1164 /// # Errors
1165 ///
1166 /// Passes along any I/O error from the underlying stream.
1167 #[inline(always)]
1168 #[deprecated(since = "1.8.0", note = "use read() method instead")]
1169 fn read_to_bytes<const SIZE: usize>(&mut self) -> io::Result<[u8; SIZE]> {
1170 self.read()
1171 }
1172
1173 /// Completely fills a vector of bytes and returns it.
1174 ///
1175 /// # Errors
1176 ///
1177 /// Passes along any I/O error from the underlying stream.
1178 fn read_to_vec(&mut self, bytes: usize) -> io::Result<Vec<u8>> {
1179 read_to_vec(|buf| self.read_bytes(buf), bytes)
1180 }
1181
1182 /// Skips the given number of bytes in the stream.
1183 ///
1184 /// # Errors
1185 ///
1186 /// Passes along any I/O error from the underlying stream.
1187 fn skip(&mut self, bytes: u32) -> io::Result<()>;
1188
1189 /// Parses and returns complex type
1190 fn parse<F: FromByteStream>(&mut self) -> Result<F, F::Error> {
1191 F::from_reader(self)
1192 }
1193
1194 /// Parses and returns complex type with context
1195 fn parse_with<'a, F: FromByteStreamWith<'a>>(
1196 &mut self,
1197 context: &F::Context,
1198 ) -> Result<F, F::Error> {
1199 F::from_reader(self, context)
1200 }
1201
1202 /// Returns mutable reference to underlying reader
1203 fn reader_ref(&mut self) -> &mut dyn io::Read;
1204}
1205
1206/// For reading aligned bytes from a stream of bytes in a given endianness.
1207///
1208/// This only reads aligned values and maintains no internal state.
1209#[derive(Debug)]
1210pub struct ByteReader<R: io::Read, E: Endianness> {
1211 phantom: PhantomData<E>,
1212 reader: R,
1213}
1214
1215impl<R: io::Read, E: Endianness> ByteReader<R, E> {
1216 /// Wraps a ByteReader around something that implements `Read`
1217 pub fn new(reader: R) -> ByteReader<R, E> {
1218 ByteReader {
1219 phantom: PhantomData,
1220 reader,
1221 }
1222 }
1223
1224 /// Wraps a ByteReader around something that implements `Read`
1225 /// with the given endianness.
1226 pub fn endian(reader: R, _endian: E) -> ByteReader<R, E> {
1227 ByteReader {
1228 phantom: PhantomData,
1229 reader,
1230 }
1231 }
1232
1233 /// Unwraps internal reader and disposes of `ByteReader`.
1234 #[inline]
1235 pub fn into_reader(self) -> R {
1236 self.reader
1237 }
1238
1239 /// Provides mutable reference to internal reader
1240 #[inline]
1241 pub fn reader(&mut self) -> &mut R {
1242 &mut self.reader
1243 }
1244
1245 /// Converts `ByteReader` to `BitReader` in the same endianness.
1246 #[inline]
1247 pub fn into_bitreader(self) -> BitReader<R, E> {
1248 BitReader::new(self.into_reader())
1249 }
1250
1251 /// Provides temporary `BitReader` in the same endianness.
1252 ///
1253 /// # Warning
1254 ///
1255 /// Any unread bits left over when `BitReader` is dropped are lost.
1256 #[inline]
1257 pub fn bitreader(&mut self) -> BitReader<&mut R, E> {
1258 BitReader::new(self.reader())
1259 }
1260}
1261
1262impl<R: io::Read, E: Endianness> ByteRead for ByteReader<R, E> {
1263 #[inline]
1264 fn read<V>(&mut self) -> Result<V, io::Error>
1265 where
1266 V: Primitive,
1267 {
1268 E::read_numeric(&mut self.reader)
1269 }
1270
1271 #[inline]
1272 fn read_as<F, V>(&mut self) -> Result<V, io::Error>
1273 where
1274 F: Endianness,
1275 V: Primitive,
1276 {
1277 F::read_numeric(&mut self.reader)
1278 }
1279
1280 #[inline]
1281 fn read_bytes(&mut self, buf: &mut [u8]) -> io::Result<()> {
1282 self.reader.read_exact(buf)
1283 }
1284
1285 #[inline]
1286 fn skip(&mut self, bytes: u32) -> io::Result<()> {
1287 skip_aligned(&mut self.reader, bytes)
1288 }
1289
1290 #[inline]
1291 fn reader_ref(&mut self) -> &mut dyn io::Read {
1292 &mut self.reader
1293 }
1294}
1295
1296/// Implemented by complex types that don't require any additional context
1297/// to parse themselves from a reader. Analagous to `FromStr`.
1298///
1299/// # Example
1300/// ```
1301/// use std::io::{Cursor, Read};
1302/// use bitstream_io::{BigEndian, BitRead, BitReader, FromBitStream};
1303///
1304/// #[derive(Debug, PartialEq, Eq)]
1305/// struct BlockHeader {
1306/// last_block: bool,
1307/// block_type: u8,
1308/// block_size: u32,
1309/// }
1310///
1311/// impl FromBitStream for BlockHeader {
1312/// type Error = std::io::Error;
1313///
1314/// fn from_reader<R: BitRead + ?Sized>(r: &mut R) -> std::io::Result<Self> {
1315/// Ok(Self {
1316/// last_block: r.read_bit()?,
1317/// block_type: r.read(7)?,
1318/// block_size: r.read(24)?,
1319/// })
1320/// }
1321/// }
1322///
1323/// let mut reader = BitReader::endian(Cursor::new(b"\x04\x00\x00\x7A"), BigEndian);
1324/// assert_eq!(
1325/// reader.parse::<BlockHeader>().unwrap(),
1326/// BlockHeader { last_block: false, block_type: 4, block_size: 122 }
1327/// );
1328/// ```
1329pub trait FromBitStream {
1330 /// Error generated during parsing, such as `io::Error`
1331 type Error;
1332
1333 /// Parse Self from reader
1334 fn from_reader<R: BitRead + ?Sized>(r: &mut R) -> Result<Self, Self::Error>
1335 where
1336 Self: Sized;
1337}
1338
1339/// Implemented by complex types that require some immutable context
1340/// to parse themselves from a reader.
1341///
1342/// # Example
1343/// ```
1344/// use std::io::{Cursor, Read};
1345/// use bitstream_io::{BigEndian, BitRead, BitReader, FromBitStreamWith};
1346///
1347/// #[derive(Default)]
1348/// struct Streaminfo {
1349/// minimum_block_size: u16,
1350/// maximum_block_size: u16,
1351/// minimum_frame_size: u32,
1352/// maximum_frame_size: u32,
1353/// sample_rate: u32,
1354/// channels: u8,
1355/// bits_per_sample: u8,
1356/// total_samples: u64,
1357/// md5: [u8; 16],
1358/// }
1359///
1360/// #[derive(Debug, PartialEq, Eq)]
1361/// struct FrameHeader {
1362/// variable_block_size: bool,
1363/// block_size: u32,
1364/// sample_rate: u32,
1365/// channel_assignment: u8,
1366/// sample_size: u8,
1367/// frame_number: u64,
1368/// crc8: u8,
1369/// }
1370///
1371/// impl FromBitStreamWith<'_> for FrameHeader {
1372/// type Context = Streaminfo;
1373///
1374/// type Error = FrameHeaderError;
1375///
1376/// fn from_reader<R: BitRead + ?Sized>(
1377/// r: &mut R,
1378/// streaminfo: &Streaminfo,
1379/// ) -> Result<Self, Self::Error> {
1380/// if r.read::<u16>(14)? != 0b11111111111110 {
1381/// return Err(FrameHeaderError::InvalidSync);
1382/// }
1383///
1384/// if r.read_bit()? != false {
1385/// return Err(FrameHeaderError::InvalidReservedBit);
1386/// }
1387///
1388/// let variable_block_size = r.read_bit()?;
1389///
1390/// let block_size_bits = r.read::<u8>(4)?;
1391///
1392/// let sample_rate_bits = r.read::<u8>(4)?;
1393///
1394/// let channel_assignment = r.read::<u8>(4)?;
1395///
1396/// let sample_size = match r.read::<u8>(3)? {
1397/// 0b000 => streaminfo.bits_per_sample,
1398/// 0b001 => 8,
1399/// 0b010 => 12,
1400/// 0b011 => return Err(FrameHeaderError::InvalidSampleSize),
1401/// 0b100 => 16,
1402/// 0b101 => 20,
1403/// 0b110 => 24,
1404/// 0b111 => 32,
1405/// _ => unreachable!(),
1406/// };
1407///
1408/// if r.read_bit()? != false {
1409/// return Err(FrameHeaderError::InvalidReservedBit);
1410/// }
1411///
1412/// let frame_number = read_utf8(r)?;
1413///
1414/// Ok(FrameHeader {
1415/// variable_block_size,
1416/// block_size: match block_size_bits {
1417/// 0b0000 => return Err(FrameHeaderError::InvalidBlockSize),
1418/// 0b0001 => 192,
1419/// n @ 0b010..=0b0101 => 576 * (1 << (n - 2)),
1420/// 0b0110 => r.read::<u32>(8)? + 1,
1421/// 0b0111 => r.read::<u32>(16)? + 1,
1422/// n @ 0b1000..=0b1111 => 256 * (1 << (n - 8)),
1423/// _ => unreachable!(),
1424/// },
1425/// sample_rate: match sample_rate_bits {
1426/// 0b0000 => streaminfo.sample_rate,
1427/// 0b0001 => 88200,
1428/// 0b0010 => 176400,
1429/// 0b0011 => 192000,
1430/// 0b0100 => 8000,
1431/// 0b0101 => 16000,
1432/// 0b0110 => 22050,
1433/// 0b0111 => 24000,
1434/// 0b1000 => 32000,
1435/// 0b1001 => 44100,
1436/// 0b1010 => 48000,
1437/// 0b1011 => 96000,
1438/// 0b1100 => r.read::<u32>(8)? * 1000,
1439/// 0b1101 => r.read::<u32>(16)?,
1440/// 0b1110 => r.read::<u32>(16)? * 10,
1441/// 0b1111 => return Err(FrameHeaderError::InvalidSampleRate),
1442/// _ => unreachable!(),
1443/// },
1444/// channel_assignment,
1445/// sample_size,
1446/// frame_number,
1447/// crc8: r.read(8)?
1448/// })
1449/// }
1450/// }
1451///
1452/// #[derive(Debug)]
1453/// enum FrameHeaderError {
1454/// Io(std::io::Error),
1455/// InvalidSync,
1456/// InvalidReservedBit,
1457/// InvalidSampleSize,
1458/// InvalidBlockSize,
1459/// InvalidSampleRate,
1460/// }
1461///
1462/// impl From<std::io::Error> for FrameHeaderError {
1463/// fn from(err: std::io::Error) -> Self {
1464/// Self::Io(err)
1465/// }
1466/// }
1467///
1468/// fn read_utf8<R: BitRead + ?Sized>(r: &mut R) -> Result<u64, std::io::Error> {
1469/// r.read(8) // left unimplimented in this example
1470/// }
1471///
1472/// let mut reader = BitReader::endian(Cursor::new(b"\xFF\xF8\xC9\x18\x00\xC2"), BigEndian);
1473/// assert_eq!(
1474/// reader.parse_with::<FrameHeader>(&Streaminfo::default()).unwrap(),
1475/// FrameHeader {
1476/// variable_block_size: false,
1477/// block_size: 4096,
1478/// sample_rate: 44100,
1479/// channel_assignment: 1,
1480/// sample_size: 16,
1481/// frame_number: 0,
1482/// crc8: 0xC2,
1483/// }
1484/// );
1485/// ```
1486///
1487/// # Example with lifetime-contrained `Context`
1488///
1489/// In some cases, the `Context` can depend on a reference to another `struct`.
1490///
1491/// ```
1492/// use std::io::{Cursor, Read};
1493/// use bitstream_io::{BigEndian, BitRead, BitReader, FromBitStreamWith};
1494///
1495/// #[derive(Default)]
1496/// struct ModeParameters {
1497/// size_len: u8,
1498/// index_len: u8,
1499/// index_delta_len: u8,
1500/// // ...
1501/// }
1502///
1503/// struct AuHeaderParseContext<'a> {
1504/// params: &'a ModeParameters,
1505/// base_index: Option<u32>,
1506/// }
1507///
1508/// #[derive(Debug, PartialEq, Eq)]
1509/// struct AuHeader {
1510/// size: u32,
1511/// index: u32,
1512/// // ...
1513/// }
1514///
1515/// impl<'a> FromBitStreamWith<'a> for AuHeader {
1516/// type Context = AuHeaderParseContext<'a>;
1517///
1518/// type Error = AuHeaderError;
1519///
1520/// fn from_reader<R: BitRead + ?Sized>(
1521/// r: &mut R,
1522/// ctx: &AuHeaderParseContext<'a>,
1523/// ) -> Result<Self, Self::Error> {
1524/// let size = r.read::<u32>(ctx.params.size_len as u32)?;
1525/// let index = match ctx.base_index {
1526/// None => r.read::<u32>(ctx.params.index_len as u32)?,
1527/// Some(base_index) => {
1528/// base_index
1529/// + 1
1530/// + r.read::<u32>(ctx.params.index_delta_len as u32)?
1531/// }
1532/// };
1533///
1534/// Ok(AuHeader {
1535/// size,
1536/// index,
1537/// // ...
1538/// })
1539/// }
1540/// }
1541///
1542/// #[derive(Debug)]
1543/// enum AuHeaderError {
1544/// Io(std::io::Error),
1545/// }
1546///
1547/// impl From<std::io::Error> for AuHeaderError {
1548/// fn from(err: std::io::Error) -> Self {
1549/// Self::Io(err)
1550/// }
1551/// }
1552///
1553/// let mut reader = BitReader::endian(Cursor::new(b"\xFF\xEA\xFF\x10"), BigEndian);
1554///
1555/// let mode_params = ModeParameters {
1556/// size_len: 10,
1557/// index_len: 6,
1558/// index_delta_len: 2,
1559/// // ...
1560/// };
1561///
1562/// let mut ctx = AuHeaderParseContext {
1563/// params: &mode_params,
1564/// base_index: None,
1565/// };
1566///
1567/// let header1 = reader.parse_with::<AuHeader>(&ctx).unwrap();
1568/// assert_eq!(
1569/// header1,
1570/// AuHeader {
1571/// size: 1023,
1572/// index: 42,
1573/// }
1574/// );
1575///
1576/// ctx.base_index = Some(header1.index);
1577///
1578/// assert_eq!(
1579/// reader.parse_with::<AuHeader>(&ctx).unwrap(),
1580/// AuHeader {
1581/// size: 1020,
1582/// index: 44,
1583/// }
1584/// );
1585/// ```
1586pub trait FromBitStreamWith<'a> {
1587 /// Some context to use when parsing
1588 type Context: 'a;
1589
1590 /// Error generated during parsing, such as `io::Error`
1591 type Error;
1592
1593 /// Parse Self from reader with the given context
1594 fn from_reader<R: BitRead + ?Sized>(
1595 r: &mut R,
1596 context: &Self::Context,
1597 ) -> Result<Self, Self::Error>
1598 where
1599 Self: Sized;
1600}
1601
1602/// Implemented by complex types that don't require any additional context
1603/// to parse themselves from a reader. Analagous to `FromStr`.
1604pub trait FromByteStream {
1605 /// Error generated during parsing, such as `io::Error`
1606 type Error;
1607
1608 /// Parse Self from reader
1609 fn from_reader<R: ByteRead + ?Sized>(r: &mut R) -> Result<Self, Self::Error>
1610 where
1611 Self: Sized;
1612}
1613
1614/// Implemented by complex types that require some additional context
1615/// to parse themselves from a reader. Analagous to `FromStr`.
1616pub trait FromByteStreamWith<'a> {
1617 /// Some context to use when parsing
1618 type Context: 'a;
1619
1620 /// Error generated during parsing, such as `io::Error`
1621 type Error;
1622
1623 /// Parse Self from reader
1624 fn from_reader<R: ByteRead + ?Sized>(
1625 r: &mut R,
1626 context: &Self::Context,
1627 ) -> Result<Self, Self::Error>
1628 where
1629 Self: Sized;
1630}
1631
1632fn read_to_vec(
1633 mut read: impl FnMut(&mut [u8]) -> io::Result<()>,
1634 bytes: usize,
1635) -> io::Result<Vec<u8>> {
1636 const MAX_CHUNK: usize = 4096;
1637
1638 match bytes {
1639 0 => Ok(Vec::new()),
1640 bytes: usize if bytes <= MAX_CHUNK => {
1641 let mut buf: Vec = vec![0; bytes];
1642 read(&mut buf)?;
1643 Ok(buf)
1644 }
1645 mut bytes: usize => {
1646 let mut whole: Vec = Vec::with_capacity(MAX_CHUNK);
1647 let mut chunk: [u8; MAX_CHUNK] = [0; MAX_CHUNK];
1648 while bytes > 0 {
1649 let chunk_size: usize = bytes.min(MAX_CHUNK);
1650 let chunk: &mut [u8] = &mut chunk[0..chunk_size];
1651 read(chunk)?;
1652 whole.extend_from_slice(chunk);
1653 bytes -= chunk_size;
1654 }
1655 Ok(whole)
1656 }
1657 }
1658}
1659