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