qubit-io-binary 0.8.6

Synchronous and asynchronous binary stream I/O adapters for Rust
Documentation
// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Internal helpers for decoding values through transcoding input adapters.

use std::io::Error;
use std::io::Result;

use qubit_codec::Codec;
use qubit_codec::TranscodeDecodeInput;
use qubit_io::Input;

use super::stream_codec_decode_error::StreamCodecDecodeError;

/// Codec-oriented helpers for [`TranscodeDecodeInput`].
///
/// # Type Parameters
///
/// - `I`: Underlying Qubit input type.
pub(crate) trait TranscodeDecodeInputExt<I> {
    /// Strictly decodes one value through the underlying buffered input.
    ///
    /// The codec's decode reset and finish phases must not declare output.
    /// Codecs with lifecycle output should use
    /// [`TranscodeDecodeInput::read_decoded_lifecycle_with`] directly.
    ///
    /// # Type Parameters
    ///
    /// - `C`: Codec used to decode the next value.
    ///
    /// # Returns
    ///
    /// Returns the decoded codec value.
    ///
    /// # Errors
    ///
    /// Returns I/O errors from the input or codec. Returns
    /// [`std::io::ErrorKind::Unsupported`] before reading input when the codec
    /// declares decode lifecycle output.
    fn read_decoded<C>(&mut self) -> Result<C::Value>
    where
        I: Input,
        C: Codec<Unit = I::Item> + Default,
        C::DecodeError: StreamCodecDecodeError;
}

impl<I> TranscodeDecodeInputExt<I> for TranscodeDecodeInput<I>
where
    I: Input,
    I::Item: Copy + Default,
{
    /// Decodes one value with a default codec and preserves its I/O error kind.
    ///
    /// This adapter uses the strict decode lifecycle; codecs that emit output
    /// during reset or finish are rejected before input is consumed.
    ///
    /// # Type Parameters
    ///
    /// - `C`: Codec used to decode the next value.
    ///
    /// # Returns
    ///
    /// Returns the decoded codec value.
    ///
    /// # Errors
    ///
    /// Returns I/O errors from the input or codec. Returns
    /// [`std::io::ErrorKind::Unsupported`] before reading input when the codec
    /// declares decode lifecycle output.
    #[inline]
    fn read_decoded<C>(&mut self) -> Result<C::Value>
    where
        C: Codec<Unit = I::Item> + Default,
        C::DecodeError: StreamCodecDecodeError,
    {
        let mut codec = C::default();
        self.read_decoded_with(&mut codec, |source| Error::new(source.io_error_kind(), source))
    }
}