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}