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