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}