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}