bitbuffer/readstream.rs
1use std::mem::size_of;
2use std::ops::BitOrAssign;
3
4use num_traits::{Float, PrimInt, WrappingSub};
5
6use crate::endianness::Endianness;
7use crate::num_traits::{IsSigned, UncheckedPrimitiveFloat, UncheckedPrimitiveInt};
8use crate::readbuffer::Data;
9use crate::BitReadBuffer;
10use crate::{BitError, BitRead, BitReadSized, Result};
11use std::borrow::Cow;
12use std::cmp::min;
13
14/// Stream that provides an easy way to iterate trough a [`BitBuffer`]
15///
16/// # Examples
17///
18/// ```
19/// use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian};
20///
21/// let bytes = vec![
22/// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
23/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
24/// ];
25/// let buffer = BitReadBuffer::new(&bytes, LittleEndian);
26/// let mut stream = BitReadStream::new(buffer);
27/// ```
28///
29/// [`BitBuffer`]: struct.BitBuffer.html
30#[derive(Debug)]
31pub struct BitReadStream<'a, E>
32where
33 E: Endianness,
34{
35 buffer: BitReadBuffer<'a, E>,
36 start_pos: usize,
37 pos: usize,
38}
39
40impl<'a, E> BitReadStream<'a, E>
41where
42 E: Endianness,
43{
44 /// Create a new stream from a [`BitBuffer`]
45 ///
46 /// # Examples
47 ///
48 /// ```
49 /// use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian};
50 ///
51 /// let bytes = vec![
52 /// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
53 /// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
54 /// ];
55 /// let buffer = BitReadBuffer::new(&bytes, LittleEndian);
56 /// let mut stream = BitReadStream::new(buffer);
57 /// ```
58 ///
59 /// [`BitBuffer`]: struct.BitBuffer.html
60 pub fn new(buffer: BitReadBuffer<'a, E>) -> Self {
61 BitReadStream {
62 start_pos: 0,
63 pos: 0,
64 buffer,
65 }
66 }
67
68 /// Read a single bit from the stream as boolean
69 ///
70 /// # Errors
71 ///
72 /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
73 ///
74 /// # Examples
75 ///
76 /// ```
77 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
78 /// #
79 /// # fn main() -> Result<()> {
80 /// # let bytes = vec![
81 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
82 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
83 /// # ];
84 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
85 /// # let mut stream = BitReadStream::new(buffer);
86 /// assert_eq!(stream.read_bool()?, true);
87 /// assert_eq!(stream.read_bool()?, false);
88 /// assert_eq!(stream.pos(), 2);
89 /// #
90 /// # Ok(())
91 /// # }
92 /// ```
93 ///
94 /// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
95 #[inline]
96 pub fn read_bool(&mut self) -> Result<bool> {
97 let result = self.buffer.read_bool(self.pos);
98 if result.is_ok() {
99 self.pos += 1;
100 }
101 result
102 }
103
104 #[doc(hidden)]
105 #[inline]
106 pub unsafe fn read_bool_unchecked(&mut self) -> bool {
107 let result = self.buffer.read_bool_unchecked(self.pos);
108 self.pos += 1;
109 result
110 }
111
112 /// Read a sequence of bits from the stream as integer
113 ///
114 /// # Errors
115 ///
116 /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
117 /// - [`ReadError::TooManyBits`]: to many bits requested for the chosen integer type
118 ///
119 /// # Examples
120 ///
121 /// ```
122 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
123 /// #
124 /// # fn main() -> Result<()> {
125 /// # let bytes = vec![
126 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
127 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
128 /// # ];
129 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
130 /// # let mut stream = BitReadStream::new(buffer);
131 /// assert_eq!(stream.read_int::<u16>(3)?, 0b101);
132 /// assert_eq!(stream.read_int::<u16>(3)?, 0b110);
133 /// assert_eq!(stream.pos(), 6);
134 /// #
135 /// # Ok(())
136 /// # }
137 /// ```
138 ///
139 /// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
140 /// [`ReadError::TooManyBits`]: enum.ReadError.html#variant.TooManyBits
141 #[inline]
142 pub fn read_int<T>(&mut self, count: usize) -> Result<T>
143 where
144 T: PrimInt + BitOrAssign + IsSigned + UncheckedPrimitiveInt + WrappingSub,
145 {
146 let result = self.buffer.read_int(self.pos, count);
147 if result.is_ok() {
148 self.pos += count;
149 }
150 result
151 }
152
153 #[doc(hidden)]
154 #[inline]
155 pub unsafe fn read_int_unchecked<T>(&mut self, count: usize, end: bool) -> T
156 where
157 T: PrimInt + BitOrAssign + IsSigned + UncheckedPrimitiveInt + WrappingSub,
158 {
159 let result = self.buffer.read_int_unchecked(self.pos, count, end);
160 self.pos += count;
161 result
162 }
163
164 /// Read a sequence of bits from the stream as float
165 ///
166 /// # Errors
167 ///
168 /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
169 ///
170 /// # Examples
171 ///
172 /// ```
173 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
174 /// #
175 /// # fn main() -> Result<()> {
176 /// # let bytes = vec![
177 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
178 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
179 /// # ];
180 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
181 /// # let mut stream = BitReadStream::new(buffer);
182 /// let result = stream.read_float::<f32>()?;
183 /// assert_eq!(stream.pos(), 32);
184 /// #
185 /// # Ok(())
186 /// # }
187 /// ```
188 ///
189 /// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
190 #[inline]
191 pub fn read_float<T>(&mut self) -> Result<T>
192 where
193 T: Float + UncheckedPrimitiveFloat,
194 {
195 let count = size_of::<T>() * 8;
196 let result = self.buffer.read_float(self.pos);
197 if result.is_ok() {
198 self.pos += count;
199 }
200 result
201 }
202
203 #[doc(hidden)]
204 #[inline]
205 pub unsafe fn read_float_unchecked<T>(&mut self, end: bool) -> T
206 where
207 T: Float + UncheckedPrimitiveFloat,
208 {
209 let count = size_of::<T>() * 8;
210 let result = self.buffer.read_float_unchecked(self.pos, end);
211 self.pos += count;
212 result
213 }
214
215 /// Read a series of bytes from the stream
216 ///
217 /// If the current read position is on a byte boundary, the output will be borrowed, otherwise it will be copied into a new Vec
218 ///
219 /// # Errors
220 ///
221 /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
222 ///
223 /// # Examples
224 ///
225 /// ```
226 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
227 /// #
228 /// # fn main() -> Result<()> {
229 /// # use std::borrow::Borrow;
230 /// let bytes = vec![
231 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
232 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
233 /// # ];
234 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
235 /// # let mut stream = BitReadStream::new(buffer);
236 /// assert_eq!(stream.read_bytes(3)?.to_vec(), &[0b1011_0101, 0b0110_1010, 0b1010_1100]);
237 /// assert_eq!(stream.pos(), 24);
238 /// #
239 /// # Ok(())
240 /// # }
241 /// ```
242 ///
243 /// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
244 #[inline]
245 pub fn read_bytes(&mut self, byte_count: usize) -> Result<Cow<'a, [u8]>> {
246 let count = byte_count * 8;
247 let result = self.buffer.read_bytes(self.pos, byte_count);
248 if result.is_ok() {
249 self.pos += count;
250 }
251 result
252 }
253
254 #[doc(hidden)]
255 #[inline]
256 pub unsafe fn read_bytes_unchecked(&mut self, byte_count: usize) -> Cow<'a, [u8]> {
257 let count = byte_count * 8;
258 let result = self.buffer.read_bytes_unchecked(self.pos, byte_count);
259 self.pos += count;
260 result
261 }
262
263 /// Read a series of bytes from the stream as utf8 string
264 ///
265 /// You can either read a fixed number of bytes, or a dynamic length null-terminated string
266 ///
267 /// If the current read position is on a byte boundary, the output will be borrowed, otherwise it will be copied into a new String
268 ///
269 /// # Errors
270 ///
271 /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
272 /// - [`ReadError::Utf8Error`]: the read bytes are not valid utf8
273 ///
274 /// # Examples
275 ///
276 /// ```
277 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
278 /// #
279 /// # fn main() -> Result<()> {
280 /// # let bytes = vec![
281 /// # 0x48, 0x65, 0x6c, 0x6c,
282 /// # 0x6f, 0x20, 0x77, 0x6f,
283 /// # 0x72, 0x6c, 0x64, 0,
284 /// # 0, 0, 0, 0
285 /// # ];
286 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
287 /// # let mut stream = BitReadStream::new(buffer);
288 /// // Fixed length string
289 /// stream.set_pos(0);
290 /// assert_eq!(stream.read_string(Some(11))?, "Hello world".to_owned());
291 /// assert_eq!(11 * 8, stream.pos());
292 /// // fixed length with null padding
293 /// stream.set_pos(0);
294 /// assert_eq!(stream.read_string(Some(16))?, "Hello world".to_owned());
295 /// assert_eq!(16 * 8, stream.pos());
296 /// // null terminated
297 /// stream.set_pos(0);
298 /// assert_eq!(stream.read_string(None)?, "Hello world".to_owned());
299 /// assert_eq!(12 * 8, stream.pos()); // 1 more for the terminating null byte
300 /// #
301 /// # Ok(())
302 /// # }
303 /// ```
304 ///
305 /// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
306 /// [`ReadError::Utf8Error`]: enum.ReadError.html#variant.Utf8Error
307 #[inline]
308 pub fn read_string(&mut self, byte_len: Option<usize>) -> Result<Cow<'a, str>> {
309 let max_length = self.bits_left() / 8;
310
311 let result = self
312 .buffer
313 .read_string(self.pos, byte_len)
314 .map_err(|mut err| {
315 // still advance the stream on malformed utf8
316 if let BitError::Utf8Error(_, len) = &mut err {
317 self.pos += match byte_len {
318 Some(len) => len * 8,
319 None => min(*len + 1, max_length) * 8,
320 };
321
322 *len = (*len).min(max_length);
323 }
324 err
325 })?;
326
327 let read = match byte_len {
328 Some(len) => len * 8,
329 None => (result.len() + 1).min(max_length) * 8,
330 };
331
332 self.pos += read;
333 Ok(result)
334 }
335
336 /// Read a sequence of bits from the stream as a BitStream
337 ///
338 /// # Errors
339 ///
340 /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
341 ///
342 /// # Examples
343 ///
344 /// ```
345 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
346 /// #
347 /// # fn main() -> Result<()> {
348 /// # let bytes = vec![
349 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
350 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
351 /// # ];
352 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
353 /// # let mut stream = BitReadStream::new(buffer);
354 /// let mut bits = stream.read_bits(3)?;
355 /// assert_eq!(stream.pos(), 3);
356 /// assert_eq!(bits.pos(), 0);
357 /// assert_eq!(bits.bit_len(), 3);
358 /// assert_eq!(stream.read_int::<u8>(3)?, 0b110);
359 /// assert_eq!(bits.read_int::<u8>(3)?, 0b101);
360 /// assert_eq!(true, bits.read_int::<u8>(1).is_err());
361 /// #
362 /// # Ok(())
363 /// # }
364 /// ```
365 ///
366 /// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
367 pub fn read_bits(&mut self, count: usize) -> Result<Self> {
368 let result = BitReadStream {
369 buffer: self.buffer.get_sub_buffer(self.pos + count)?,
370 start_pos: self.pos,
371 pos: self.pos,
372 };
373 self.pos += count;
374 Ok(result)
375 }
376
377 /// Skip a number of bits in the stream
378 ///
379 /// # Errors
380 ///
381 /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream to skip
382 ///
383 /// # Examples
384 ///
385 /// ```
386 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
387 /// #
388 /// # fn main() -> Result<()> {
389 /// # let bytes = vec![
390 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
391 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
392 /// # ];
393 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
394 /// # let mut stream = BitReadStream::new(buffer);
395 /// stream.skip_bits(3)?;
396 /// assert_eq!(stream.pos(), 3);
397 /// assert_eq!(stream.read_int::<u8>(3)?, 0b110);
398 /// #
399 /// # Ok(())
400 /// # }
401 /// ```
402 ///
403 /// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
404 pub fn skip_bits(&mut self, count: usize) -> Result<()> {
405 if count <= self.bits_left() {
406 self.pos += count;
407 Ok(())
408 } else {
409 Err(BitError::NotEnoughData {
410 requested: count,
411 bits_left: self.bits_left(),
412 })
413 }
414 }
415
416 /// Align the stream on the next byte and returns the amount of bits read
417 ///
418 /// # Errors
419 ///
420 /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream to skip
421 ///
422 /// # Examples
423 ///
424 /// ```
425 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
426 /// #
427 /// # fn main() -> Result<()> {
428 /// # let bytes = vec![
429 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
430 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
431 /// # ];
432 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
433 /// # let mut stream = BitReadStream::new(buffer);
434 /// stream.align()?;
435 /// assert_eq!(stream.pos(), 0);
436 ///
437 /// stream.skip_bits(3)?;
438 /// assert_eq!(stream.pos(), 3);
439 /// stream.align();
440 /// assert_eq!(stream.pos(), 8);
441 /// assert_eq!(stream.read_int::<u8>(4)?, 0b1010);
442 /// #
443 /// # Ok(())
444 /// # }
445 /// ```
446 ///
447 /// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
448 pub fn align(&mut self) -> Result<usize> {
449 match self.pos % 8 {
450 0 => Ok(0),
451 n => self.skip_bits(8 - n).map(|_| 8 - n),
452 }
453 }
454
455 /// Set the position of the stream
456 ///
457 /// # Errors
458 ///
459 /// - [`ReadError::IndexOutOfBounds`]: new position is outside the bounds of the stream
460 ///
461 /// # Examples
462 ///
463 /// ```
464 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
465 /// #
466 /// # fn main() -> Result<()> {
467 /// # let bytes = vec![
468 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
469 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
470 /// # ];
471 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
472 /// # let mut stream = BitReadStream::new(buffer);
473 /// stream.set_pos(3)?;
474 /// assert_eq!(stream.pos(), 3);
475 /// assert_eq!(stream.read_int::<u8>(3)?, 0b110);
476 /// #
477 /// # Ok(())
478 /// # }
479 /// ```
480 ///
481 /// [`ReadError::IndexOutOfBounds`]: enum.ReadError.html#variant.IndexOutOfBounds
482 pub fn set_pos(&mut self, pos: usize) -> Result<()> {
483 if pos > self.bit_len() {
484 return Err(BitError::IndexOutOfBounds {
485 pos,
486 size: self.bit_len(),
487 });
488 }
489 self.pos = pos + self.start_pos;
490 Ok(())
491 }
492
493 /// Get the length of the stream in bits
494 ///
495 /// # Examples
496 ///
497 /// ```
498 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
499 /// #
500 /// # fn main() -> Result<()> {
501 /// # let bytes = vec![
502 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
503 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
504 /// # ];
505 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
506 /// # let mut stream = BitReadStream::new(buffer);
507 /// assert_eq!(stream.bit_len(), 64);
508 /// #
509 /// # Ok(())
510 /// # }
511 /// ```
512 pub fn bit_len(&self) -> usize {
513 self.buffer.bit_len() - self.start_pos
514 }
515
516 /// Get the current position in the stream
517 ///
518 /// # Examples
519 ///
520 /// ```
521 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
522 /// #
523 /// # fn main() -> Result<()> {
524 /// # let bytes = vec![
525 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
526 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
527 /// # ];
528 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
529 /// # let mut stream = BitReadStream::new(buffer);
530 /// assert_eq!(stream.pos(), 0);
531 /// stream.skip_bits(5)?;
532 /// assert_eq!(stream.pos(), 5);
533 /// #
534 /// # Ok(())
535 /// # }
536 /// ```
537 pub fn pos(&self) -> usize {
538 self.pos - self.start_pos
539 }
540
541 /// Get the number of bits left in the stream
542 ///
543 /// # Examples
544 ///
545 /// ```
546 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
547 /// #
548 /// # fn main() -> Result<()> {
549 /// # let bytes = vec![
550 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
551 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
552 /// # ];
553 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
554 /// # let mut stream = BitReadStream::new(buffer);
555 /// assert_eq!(stream.bits_left(), 64);
556 /// stream.skip_bits(5)?;
557 /// assert_eq!(stream.bits_left(), 59);
558 /// #
559 /// # Ok(())
560 /// # }
561 /// ```
562 pub fn bits_left(&self) -> usize {
563 self.bit_len() - self.pos()
564 }
565
566 /// Read a value based on the provided type
567 ///
568 /// # Examples
569 ///
570 /// ```
571 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
572 /// #
573 /// # fn main() -> Result<()> {
574 /// # let bytes = vec![
575 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
576 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
577 /// # ];
578 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
579 /// # let mut stream = BitReadStream::new(buffer);
580 /// let int: u8 = stream.read()?;
581 /// assert_eq!(int, 0b1011_0101);
582 /// let boolean: bool = stream.read()?;
583 /// assert_eq!(false, boolean);
584 /// #
585 /// # Ok(())
586 /// # }
587 /// ```
588 ///
589 /// ```
590 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
591 /// use bitbuffer::BitRead;
592 /// #
593 /// #[derive(BitRead, Debug, PartialEq)]
594 /// struct ComplexType {
595 /// first: u8,
596 /// #[size = 15]
597 /// second: u16,
598 /// third: bool,
599 /// }
600 /// #
601 /// # fn main() -> Result<()> {
602 /// # let bytes = vec![
603 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
604 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
605 /// # ];
606 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
607 /// # let mut stream = BitReadStream::new(buffer);
608 /// let data: ComplexType = stream.read()?;
609 /// assert_eq!(data, ComplexType {
610 /// first: 0b1011_0101,
611 /// second: 0b010_1100_0110_1010,
612 /// third: true,
613 /// });
614 /// #
615 /// # Ok(())
616 /// # }
617 /// ```
618 #[inline]
619 pub fn read<T: BitRead<'a, E>>(&mut self) -> Result<T> {
620 T::read(self)
621 }
622
623 #[doc(hidden)]
624 #[inline]
625 pub unsafe fn read_unchecked<T: BitRead<'a, E>>(&mut self, end: bool) -> Result<T> {
626 T::read_unchecked(self, end)
627 }
628
629 /// Read a value based on the provided type and size
630 ///
631 /// The meaning of the size parameter differs depending on the type that is being read
632 ///
633 /// # Examples
634 ///
635 /// ```
636 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
637 /// #
638 /// # fn main() -> Result<()> {
639 /// # let bytes = vec![
640 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
641 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
642 /// # ];
643 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
644 /// # let mut stream = BitReadStream::new(buffer);
645 /// let int: u8 = stream.read_sized(7)?;
646 /// assert_eq!(int, 0b011_0101);
647 /// #
648 /// # Ok(())
649 /// # }
650 /// ```
651 ///
652 /// ```
653 /// # use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian, Result};
654 /// #
655 /// # fn main() -> Result<()> {
656 /// # let bytes = vec![
657 /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
658 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
659 /// # ];
660 /// # let buffer = BitReadBuffer::new(&bytes, LittleEndian);
661 /// # let mut stream = BitReadStream::new(buffer);
662 /// let data: Vec<u16> = stream.read_sized(3)?;
663 /// assert_eq!(data, vec![0b0110_1010_1011_0101, 0b1001_1001_1010_1100, 0b1001_1001_1001_1001]);
664 /// #
665 /// # Ok(())
666 /// # }
667 /// ```
668 #[inline]
669 pub fn read_sized<T: BitReadSized<'a, E>>(&mut self, size: usize) -> Result<T> {
670 T::read(self, size)
671 }
672
673 /// Read a value based on the provided type without advancing the stream
674 #[inline]
675 pub fn peek<T: BitRead<'a, E>>(&mut self) -> Result<T> {
676 let pos = self.pos;
677 let result = T::read(self);
678 self.pos = pos;
679 result
680 }
681
682 /// Read a value based on the provided type and size without advancing the stream
683 #[inline]
684 pub fn peek_sized<T: BitReadSized<'a, E>>(&mut self, size: usize) -> Result<T> {
685 let pos = self.pos;
686 let result = T::read(self, size);
687 self.pos = pos;
688 result
689 }
690
691 #[doc(hidden)]
692 #[inline]
693 pub unsafe fn read_sized_unchecked<T: BitReadSized<'a, E>>(
694 &mut self,
695 size: usize,
696 end: bool,
697 ) -> Result<T> {
698 T::read_unchecked(self, size, end)
699 }
700
701 /// Check if we can read a number of bits from the stream
702 pub fn check_read(&self, count: usize) -> Result<bool> {
703 if self.bits_left() < count + 64 {
704 if self.bits_left() < count {
705 Err(BitError::NotEnoughData {
706 requested: count,
707 bits_left: self.bits_left(),
708 })
709 } else {
710 Ok(true)
711 }
712 } else {
713 Ok(false)
714 }
715 }
716
717 /// Create an owned copy of this stream
718 pub fn to_owned(&self) -> BitReadStream<'static, E> {
719 match self.buffer.bytes {
720 Data::Owned(_) => BitReadStream {
721 // already owned, so buffer.to_owned is a cheap rc clone
722 buffer: self.buffer.to_owned(),
723 start_pos: self.pos,
724 pos: self.pos,
725 },
726 Data::Borrowed(bytes) => {
727 // instead of calling buffer.to_owned blindly, we only copy the bytes that this stream covers
728 let byte_pos = self.start_pos / 8;
729 let bit_offset = self.start_pos & 7;
730
731 let end = self.buffer.bit_len() / 8 + 1;
732 let end = min(end, self.buffer.byte_len());
733
734 let sub_bytes = bytes[byte_pos..end].to_vec();
735 let buffer = BitReadBuffer::from(sub_bytes)
736 .get_sub_buffer(self.buffer.bit_len() - self.start_pos + bit_offset)
737 .unwrap();
738
739 BitReadStream {
740 buffer,
741 start_pos: bit_offset,
742 pos: bit_offset + (self.pos - self.start_pos),
743 }
744 }
745 }
746 }
747}
748
749impl<E: Endianness> Clone for BitReadStream<'_, E> {
750 fn clone(&self) -> Self {
751 BitReadStream {
752 buffer: self.buffer.clone(),
753 start_pos: self.pos,
754 pos: self.pos,
755 }
756 }
757}
758
759impl<E: Endianness> PartialEq for BitReadStream<'_, E> {
760 fn eq(&self, other: &Self) -> bool {
761 // clones so we can mut
762 let mut self_clone = self.clone();
763 self_clone.set_pos(0).ok();
764 let mut other_clone = other.clone();
765 other_clone.set_pos(0).ok();
766
767 if self_clone.bits_left() != other_clone.bits_left() {
768 return false;
769 }
770
771 while self_clone.bits_left() > 32 {
772 if self_clone.read::<u32>().ok() != other_clone.read().ok() {
773 return false;
774 }
775 }
776
777 while self_clone.bits_left() > 0 {
778 if self_clone.read::<bool>().ok() != other_clone.read().ok() {
779 return false;
780 }
781 }
782
783 true
784 }
785}
786
787impl<'a, E: Endianness> From<BitReadBuffer<'a, E>> for BitReadStream<'a, E> {
788 fn from(buffer: BitReadBuffer<'a, E>) -> Self {
789 BitReadStream::new(buffer)
790 }
791}
792
793impl<'a, E: Endianness> From<&'a [u8]> for BitReadStream<'a, E> {
794 fn from(bytes: &'a [u8]) -> Self {
795 BitReadStream::new(BitReadBuffer::from(bytes))
796 }
797}
798
799#[cfg(feature = "serde")]
800use serde::{de, ser::SerializeStruct, Deserialize, Deserializer, Serialize, Serializer};
801
802#[cfg(feature = "serde")]
803impl<'a, E: Endianness> Serialize for BitReadStream<'a, E> {
804 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
805 where
806 S: Serializer,
807 {
808 let mut stream = self.clone();
809 let mut data = stream.read_bytes(self.bits_left() / 8).unwrap().to_vec();
810 if stream.bits_left() > 0 {
811 data.push(stream.read_sized(stream.bits_left()).unwrap());
812 }
813
814 let mut s = serializer.serialize_struct("BitReadStream", 3)?;
815 s.serialize_field("data", &data)?;
816 s.serialize_field("bit_length", &self.bit_len())?;
817 s.end()
818 }
819}
820
821#[cfg(feature = "serde")]
822impl<'de, E: Endianness> Deserialize<'de> for BitReadStream<'static, E> {
823 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
824 where
825 D: Deserializer<'de>,
826 {
827 #[derive(Deserialize)]
828 struct BitData {
829 data: Vec<u8>,
830 bit_length: usize,
831 }
832
833 let data = BitData::deserialize(deserializer)?;
834 let mut buffer = BitReadBuffer::new_owned(data.data, E::endianness());
835 buffer
836 .truncate(data.bit_length)
837 .map_err(de::Error::custom)?;
838 Ok(BitReadStream::new(buffer))
839 }
840}
841
842#[cfg(feature = "serde")]
843#[test]
844fn test_serde_roundtrip() {
845 use crate::LittleEndian;
846
847 let mut buffer = BitReadBuffer::new_owned(vec![55; 8], LittleEndian);
848 buffer.truncate(61).unwrap();
849 let stream = BitReadStream::new(buffer);
850 assert_eq!(61, stream.bit_len());
851
852 let json = serde_json::to_string(&stream).unwrap();
853
854 let result: BitReadStream<LittleEndian> = serde_json::from_str(&json).unwrap();
855
856 assert_eq!(result, stream);
857}
858
859#[cfg(feature = "schemars")]
860impl<'a, E: Endianness> schemars::JsonSchema for BitReadStream<'a, E> {
861 fn schema_name() -> String {
862 "BitReadStream".into()
863 }
864
865 fn json_schema(gen: &mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema {
866 #[derive(schemars::JsonSchema)]
867 #[allow(dead_code)]
868 struct StreamSchema {
869 data: Vec<u8>,
870 bit_length: usize,
871 }
872 StreamSchema::json_schema(gen)
873 }
874}
875
876#[cfg(feature = "schemars_1")]
877impl<'a, E: Endianness> schemars_1::JsonSchema for BitReadStream<'a, E> {
878 fn schema_name() -> std::borrow::Cow<'static, str> {
879 "BitReadStream".into()
880 }
881
882 fn json_schema(gen: &mut schemars_1::SchemaGenerator) -> schemars_1::Schema {
883 use schemars_1 as schemars;
884
885 #[derive(schemars_1::JsonSchema)]
886 #[allow(dead_code)]
887 struct StreamSchema {
888 data: Vec<u8>,
889 bit_length: usize,
890 }
891 StreamSchema::json_schema(gen)
892 }
893}