Skip to main content

qubit_io_binary/ext/
binary_read_ext.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8
9//! Extension methods for decoding fixed-width binary values from byte streams.
10
11use std::io::Result;
12
13use qubit_codec::BigEndian;
14use qubit_codec::ByteOrder;
15use qubit_codec::LittleEndian;
16use qubit_codec_binary::BinaryCodec;
17use qubit_io::Input;
18
19use crate::util::decode_infallible_unchecked;
20
21macro_rules! read_binary_value {
22    ($reader:expr, $ty:ty, $order:ty) => {
23        read_binary::<{ BinaryCodec::<$ty, $order>::MIN_UNITS_PER_VALUE }, _, _, _>($reader, |bytes| {
24            type Codec = BinaryCodec<$ty, $order>;
25            // SAFETY: The local buffer is exactly the codec's minimum buffer
26            // length.
27            unsafe { decode_infallible_unchecked::<Codec>(bytes, 0) }
28        })
29    };
30}
31
32/// Resolves a runtime byte-order choice to a big-endian branch.
33///
34/// # Parameters
35///
36/// - `byte_order`: Runtime byte-order selection.
37///
38/// # Returns
39///
40/// Returns `true` for big endian, `false` for little endian, and the target's
41/// native ordering for [`ByteOrder::NativeEndian`].
42#[must_use]
43#[inline]
44const fn use_big_endian(byte_order: ByteOrder) -> bool {
45    match byte_order {
46        ByteOrder::BigEndian => true,
47        ByteOrder::LittleEndian => false,
48        ByteOrder::NativeEndian => cfg!(target_endian = "big"),
49    }
50}
51
52/// Extension methods for reading fixed-width binary values from byte streams.
53///
54/// # Examples
55///
56/// ```
57/// use std::io::Cursor;
58///
59/// use qubit_io_binary::BinaryReadExt;
60///
61/// let mut input = Cursor::new([0x12, 0x34]);
62/// assert_eq!(input.read_u16_be().unwrap(), 0x1234);
63/// ```
64pub trait BinaryReadExt: Input<Item = u8> {
65    /// Reads an unsigned 8-bit integer.
66    ///
67    /// # Returns
68    ///
69    /// Returns the decoded scalar.
70    ///
71    /// # Errors
72    ///
73    /// Returns an input error, including an unexpected-end-of-input error
74    /// when a complete scalar is unavailable.
75    #[inline(always)]
76    fn read_u8(&mut self) -> Result<u8> {
77        read_binary_value!(self, u8, BigEndian)
78    }
79
80    /// Reads a signed 8-bit integer.
81    ///
82    /// # Returns
83    ///
84    /// Returns the decoded scalar.
85    ///
86    /// # Errors
87    ///
88    /// Returns an input error, including an unexpected-end-of-input error
89    /// when a complete scalar is unavailable.
90    #[inline(always)]
91    fn read_i8(&mut self) -> Result<i8> {
92        read_binary_value!(self, i8, BigEndian)
93    }
94
95    /// Reads an unsigned 16-bit integer using a runtime byte order.
96    ///
97    /// # Parameters
98    ///
99    /// - `byte_order`: Byte order used to decode the value.
100    ///
101    /// # Returns
102    ///
103    /// Returns the decoded scalar.
104    ///
105    /// # Errors
106    ///
107    /// Returns an input error, including an unexpected-end-of-input error
108    /// when a complete scalar is unavailable.
109    #[inline]
110    fn read_u16(&mut self, byte_order: ByteOrder) -> Result<u16> {
111        if use_big_endian(byte_order) {
112            self.read_u16_be()
113        } else {
114            self.read_u16_le()
115        }
116    }
117
118    /// Reads a big-endian unsigned 16-bit integer.
119    ///
120    /// # Returns
121    ///
122    /// Returns the decoded scalar.
123    ///
124    /// # Errors
125    ///
126    /// Returns an input error, including an unexpected-end-of-input error
127    /// when a complete scalar is unavailable.
128    #[inline(always)]
129    fn read_u16_be(&mut self) -> Result<u16> {
130        read_binary_value!(self, u16, BigEndian)
131    }
132
133    /// Reads a little-endian unsigned 16-bit integer.
134    ///
135    /// # Returns
136    ///
137    /// Returns the decoded scalar.
138    ///
139    /// # Errors
140    ///
141    /// Returns an input error, including an unexpected-end-of-input error
142    /// when a complete scalar is unavailable.
143    #[inline(always)]
144    fn read_u16_le(&mut self) -> Result<u16> {
145        read_binary_value!(self, u16, LittleEndian)
146    }
147
148    /// Reads an unsigned 32-bit integer using a runtime byte order.
149    ///
150    /// # Parameters
151    ///
152    /// - `byte_order`: Byte order used to decode the value.
153    ///
154    /// # Returns
155    ///
156    /// Returns the decoded scalar.
157    ///
158    /// # Errors
159    ///
160    /// Returns an input error, including an unexpected-end-of-input error
161    /// when a complete scalar is unavailable.
162    #[inline]
163    fn read_u32(&mut self, byte_order: ByteOrder) -> Result<u32> {
164        if use_big_endian(byte_order) {
165            self.read_u32_be()
166        } else {
167            self.read_u32_le()
168        }
169    }
170
171    /// Reads a big-endian unsigned 32-bit integer.
172    ///
173    /// # Returns
174    ///
175    /// Returns the decoded scalar.
176    ///
177    /// # Errors
178    ///
179    /// Returns an input error, including an unexpected-end-of-input error
180    /// when a complete scalar is unavailable.
181    #[inline(always)]
182    fn read_u32_be(&mut self) -> Result<u32> {
183        read_binary_value!(self, u32, BigEndian)
184    }
185
186    /// Reads a little-endian unsigned 32-bit integer.
187    ///
188    /// # Returns
189    ///
190    /// Returns the decoded scalar.
191    ///
192    /// # Errors
193    ///
194    /// Returns an input error, including an unexpected-end-of-input error
195    /// when a complete scalar is unavailable.
196    #[inline(always)]
197    fn read_u32_le(&mut self) -> Result<u32> {
198        read_binary_value!(self, u32, LittleEndian)
199    }
200
201    /// Reads an unsigned 64-bit integer using a runtime byte order.
202    ///
203    /// # Parameters
204    ///
205    /// - `byte_order`: Byte order used to decode the value.
206    ///
207    /// # Returns
208    ///
209    /// Returns the decoded scalar.
210    ///
211    /// # Errors
212    ///
213    /// Returns an input error, including an unexpected-end-of-input error
214    /// when a complete scalar is unavailable.
215    #[inline]
216    fn read_u64(&mut self, byte_order: ByteOrder) -> Result<u64> {
217        if use_big_endian(byte_order) {
218            self.read_u64_be()
219        } else {
220            self.read_u64_le()
221        }
222    }
223
224    /// Reads a big-endian unsigned 64-bit integer.
225    ///
226    /// # Returns
227    ///
228    /// Returns the decoded scalar.
229    ///
230    /// # Errors
231    ///
232    /// Returns an input error, including an unexpected-end-of-input error
233    /// when a complete scalar is unavailable.
234    #[inline(always)]
235    fn read_u64_be(&mut self) -> Result<u64> {
236        read_binary_value!(self, u64, BigEndian)
237    }
238
239    /// Reads a little-endian unsigned 64-bit integer.
240    ///
241    /// # Returns
242    ///
243    /// Returns the decoded scalar.
244    ///
245    /// # Errors
246    ///
247    /// Returns an input error, including an unexpected-end-of-input error
248    /// when a complete scalar is unavailable.
249    #[inline(always)]
250    fn read_u64_le(&mut self) -> Result<u64> {
251        read_binary_value!(self, u64, LittleEndian)
252    }
253
254    /// Reads an unsigned 128-bit integer using a runtime byte order.
255    ///
256    /// # Parameters
257    ///
258    /// - `byte_order`: Byte order used to decode the value.
259    ///
260    /// # Returns
261    ///
262    /// Returns the decoded scalar.
263    ///
264    /// # Errors
265    ///
266    /// Returns an input error, including an unexpected-end-of-input error
267    /// when a complete scalar is unavailable.
268    #[inline]
269    fn read_u128(&mut self, byte_order: ByteOrder) -> Result<u128> {
270        if use_big_endian(byte_order) {
271            self.read_u128_be()
272        } else {
273            self.read_u128_le()
274        }
275    }
276
277    /// Reads a big-endian unsigned 128-bit integer.
278    ///
279    /// # Returns
280    ///
281    /// Returns the decoded scalar.
282    ///
283    /// # Errors
284    ///
285    /// Returns an input error, including an unexpected-end-of-input error
286    /// when a complete scalar is unavailable.
287    #[inline(always)]
288    fn read_u128_be(&mut self) -> Result<u128> {
289        read_binary_value!(self, u128, BigEndian)
290    }
291
292    /// Reads a little-endian unsigned 128-bit integer.
293    ///
294    /// # Returns
295    ///
296    /// Returns the decoded scalar.
297    ///
298    /// # Errors
299    ///
300    /// Returns an input error, including an unexpected-end-of-input error
301    /// when a complete scalar is unavailable.
302    #[inline(always)]
303    fn read_u128_le(&mut self) -> Result<u128> {
304        read_binary_value!(self, u128, LittleEndian)
305    }
306
307    /// Reads a signed 16-bit integer using a runtime byte order.
308    ///
309    /// # Parameters
310    ///
311    /// - `byte_order`: Byte order used to decode the value.
312    ///
313    /// # Returns
314    ///
315    /// Returns the decoded scalar.
316    ///
317    /// # Errors
318    ///
319    /// Returns an input error, including an unexpected-end-of-input error
320    /// when a complete scalar is unavailable.
321    #[inline]
322    fn read_i16(&mut self, byte_order: ByteOrder) -> Result<i16> {
323        if use_big_endian(byte_order) {
324            self.read_i16_be()
325        } else {
326            self.read_i16_le()
327        }
328    }
329
330    /// Reads a big-endian signed 16-bit integer.
331    ///
332    /// # Returns
333    ///
334    /// Returns the decoded scalar.
335    ///
336    /// # Errors
337    ///
338    /// Returns an input error, including an unexpected-end-of-input error
339    /// when a complete scalar is unavailable.
340    #[inline(always)]
341    fn read_i16_be(&mut self) -> Result<i16> {
342        read_binary_value!(self, i16, BigEndian)
343    }
344
345    /// Reads a little-endian signed 16-bit integer.
346    ///
347    /// # Returns
348    ///
349    /// Returns the decoded scalar.
350    ///
351    /// # Errors
352    ///
353    /// Returns an input error, including an unexpected-end-of-input error
354    /// when a complete scalar is unavailable.
355    #[inline(always)]
356    fn read_i16_le(&mut self) -> Result<i16> {
357        read_binary_value!(self, i16, LittleEndian)
358    }
359
360    /// Reads a signed 32-bit integer using a runtime byte order.
361    ///
362    /// # Parameters
363    ///
364    /// - `byte_order`: Byte order used to decode the value.
365    ///
366    /// # Returns
367    ///
368    /// Returns the decoded scalar.
369    ///
370    /// # Errors
371    ///
372    /// Returns an input error, including an unexpected-end-of-input error
373    /// when a complete scalar is unavailable.
374    #[inline]
375    fn read_i32(&mut self, byte_order: ByteOrder) -> Result<i32> {
376        if use_big_endian(byte_order) {
377            self.read_i32_be()
378        } else {
379            self.read_i32_le()
380        }
381    }
382
383    /// Reads a big-endian signed 32-bit integer.
384    ///
385    /// # Returns
386    ///
387    /// Returns the decoded scalar.
388    ///
389    /// # Errors
390    ///
391    /// Returns an input error, including an unexpected-end-of-input error
392    /// when a complete scalar is unavailable.
393    #[inline(always)]
394    fn read_i32_be(&mut self) -> Result<i32> {
395        read_binary_value!(self, i32, BigEndian)
396    }
397
398    /// Reads a little-endian signed 32-bit integer.
399    ///
400    /// # Returns
401    ///
402    /// Returns the decoded scalar.
403    ///
404    /// # Errors
405    ///
406    /// Returns an input error, including an unexpected-end-of-input error
407    /// when a complete scalar is unavailable.
408    #[inline(always)]
409    fn read_i32_le(&mut self) -> Result<i32> {
410        read_binary_value!(self, i32, LittleEndian)
411    }
412
413    /// Reads a signed 64-bit integer using a runtime byte order.
414    ///
415    /// # Parameters
416    ///
417    /// - `byte_order`: Byte order used to decode the value.
418    ///
419    /// # Returns
420    ///
421    /// Returns the decoded scalar.
422    ///
423    /// # Errors
424    ///
425    /// Returns an input error, including an unexpected-end-of-input error
426    /// when a complete scalar is unavailable.
427    #[inline]
428    fn read_i64(&mut self, byte_order: ByteOrder) -> Result<i64> {
429        if use_big_endian(byte_order) {
430            self.read_i64_be()
431        } else {
432            self.read_i64_le()
433        }
434    }
435
436    /// Reads a big-endian signed 64-bit integer.
437    ///
438    /// # Returns
439    ///
440    /// Returns the decoded scalar.
441    ///
442    /// # Errors
443    ///
444    /// Returns an input error, including an unexpected-end-of-input error
445    /// when a complete scalar is unavailable.
446    #[inline(always)]
447    fn read_i64_be(&mut self) -> Result<i64> {
448        read_binary_value!(self, i64, BigEndian)
449    }
450
451    /// Reads a little-endian signed 64-bit integer.
452    ///
453    /// # Returns
454    ///
455    /// Returns the decoded scalar.
456    ///
457    /// # Errors
458    ///
459    /// Returns an input error, including an unexpected-end-of-input error
460    /// when a complete scalar is unavailable.
461    #[inline(always)]
462    fn read_i64_le(&mut self) -> Result<i64> {
463        read_binary_value!(self, i64, LittleEndian)
464    }
465
466    /// Reads a signed 128-bit integer using a runtime byte order.
467    ///
468    /// # Parameters
469    ///
470    /// - `byte_order`: Byte order used to decode the value.
471    ///
472    /// # Returns
473    ///
474    /// Returns the decoded scalar.
475    ///
476    /// # Errors
477    ///
478    /// Returns an input error, including an unexpected-end-of-input error
479    /// when a complete scalar is unavailable.
480    #[inline]
481    fn read_i128(&mut self, byte_order: ByteOrder) -> Result<i128> {
482        if use_big_endian(byte_order) {
483            self.read_i128_be()
484        } else {
485            self.read_i128_le()
486        }
487    }
488
489    /// Reads a big-endian signed 128-bit integer.
490    ///
491    /// # Returns
492    ///
493    /// Returns the decoded scalar.
494    ///
495    /// # Errors
496    ///
497    /// Returns an input error, including an unexpected-end-of-input error
498    /// when a complete scalar is unavailable.
499    #[inline(always)]
500    fn read_i128_be(&mut self) -> Result<i128> {
501        read_binary_value!(self, i128, BigEndian)
502    }
503
504    /// Reads a little-endian signed 128-bit integer.
505    ///
506    /// # Returns
507    ///
508    /// Returns the decoded scalar.
509    ///
510    /// # Errors
511    ///
512    /// Returns an input error, including an unexpected-end-of-input error
513    /// when a complete scalar is unavailable.
514    #[inline(always)]
515    fn read_i128_le(&mut self) -> Result<i128> {
516        read_binary_value!(self, i128, LittleEndian)
517    }
518
519    /// Reads a 32-bit float using a runtime byte order.
520    ///
521    /// # Parameters
522    ///
523    /// - `byte_order`: Byte order used to decode the value.
524    ///
525    /// # Returns
526    ///
527    /// Returns the decoded scalar.
528    ///
529    /// # Errors
530    ///
531    /// Returns an input error, including an unexpected-end-of-input error
532    /// when a complete scalar is unavailable.
533    #[inline]
534    fn read_f32(&mut self, byte_order: ByteOrder) -> Result<f32> {
535        if use_big_endian(byte_order) {
536            self.read_f32_be()
537        } else {
538            self.read_f32_le()
539        }
540    }
541
542    /// Reads a big-endian 32-bit float.
543    ///
544    /// # Returns
545    ///
546    /// Returns the decoded scalar.
547    ///
548    /// # Errors
549    ///
550    /// Returns an input error, including an unexpected-end-of-input error
551    /// when a complete scalar is unavailable.
552    #[inline(always)]
553    fn read_f32_be(&mut self) -> Result<f32> {
554        read_binary_value!(self, f32, BigEndian)
555    }
556
557    /// Reads a little-endian 32-bit float.
558    ///
559    /// # Returns
560    ///
561    /// Returns the decoded scalar.
562    ///
563    /// # Errors
564    ///
565    /// Returns an input error, including an unexpected-end-of-input error
566    /// when a complete scalar is unavailable.
567    #[inline(always)]
568    fn read_f32_le(&mut self) -> Result<f32> {
569        read_binary_value!(self, f32, LittleEndian)
570    }
571
572    /// Reads a 64-bit float using a runtime byte order.
573    ///
574    /// # Parameters
575    ///
576    /// - `byte_order`: Byte order used to decode the value.
577    ///
578    /// # Returns
579    ///
580    /// Returns the decoded scalar.
581    ///
582    /// # Errors
583    ///
584    /// Returns an input error, including an unexpected-end-of-input error
585    /// when a complete scalar is unavailable.
586    #[inline]
587    fn read_f64(&mut self, byte_order: ByteOrder) -> Result<f64> {
588        if use_big_endian(byte_order) {
589            self.read_f64_be()
590        } else {
591            self.read_f64_le()
592        }
593    }
594
595    /// Reads a big-endian 64-bit float.
596    ///
597    /// # Returns
598    ///
599    /// Returns the decoded scalar.
600    ///
601    /// # Errors
602    ///
603    /// Returns an input error, including an unexpected-end-of-input error
604    /// when a complete scalar is unavailable.
605    #[inline(always)]
606    fn read_f64_be(&mut self) -> Result<f64> {
607        read_binary_value!(self, f64, BigEndian)
608    }
609
610    /// Reads a little-endian 64-bit float.
611    ///
612    /// # Returns
613    ///
614    /// Returns the decoded scalar.
615    ///
616    /// # Errors
617    ///
618    /// Returns an input error, including an unexpected-end-of-input error
619    /// when a complete scalar is unavailable.
620    #[inline(always)]
621    fn read_f64_le(&mut self) -> Result<f64> {
622        read_binary_value!(self, f64, LittleEndian)
623    }
624}
625
626impl<R> BinaryReadExt for R where R: Input<Item = u8> + ?Sized {}
627
628/// Reads and decodes one fixed-width value.
629///
630/// # Type Parameters
631///
632/// - `N`: Encoded scalar width in bytes.
633/// - `T`: Decoded value type.
634/// - `R`: Source byte input.
635/// - `F`: Infallible decoding callback.
636///
637/// # Parameters
638///
639/// - `reader`: Source from which the fixed-width payload is read.
640/// - `decode`: Callback that decodes the initialized local buffer.
641///
642/// # Returns
643///
644/// Returns the decoded value.
645///
646/// # Errors
647///
648/// Returns an input error, including an unexpected-end-of-input error when the
649/// payload is truncated.
650#[inline]
651fn read_binary<const N: usize, T, R, F>(reader: &mut R, decode: F) -> Result<T>
652where
653    R: Input<Item = u8> + ?Sized,
654    F: FnOnce(&[u8]) -> T,
655{
656    let mut bytes = [0u8; N];
657    Input::read_exactly(reader, &mut bytes)?;
658    Ok(decode(&bytes))
659}