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}