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