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 encoding values through transcoding output adapters.

use std::error::Error as StdError;
use std::io;
use std::io::Error;
use std::io::ErrorKind;

use qubit_codec::Codec;
use qubit_codec::TranscodeEncodeOutput;
use qubit_io::Output;

/// Codec-oriented helpers for [`TranscodeEncodeOutput`].
///
/// # Type Parameters
///
/// - `O`: Underlying Qubit output type.
pub(crate) trait TranscodeEncodeOutputExt<O> {
    /// Encodes one value through the underlying buffered output.
    ///
    /// # Type Parameters
    ///
    /// - `C`: Codec used to encode the value.
    ///
    /// # Parameters
    ///
    /// - `value`: Codec value to encode.
    ///
    /// # Returns
    ///
    /// Returns after the encoded units have been accepted by the buffered
    /// output.
    ///
    /// # Errors
    ///
    /// Returns an output error or an invalid-data error when the codec rejects
    /// the value.
    fn write_encoded<C>(&mut self, value: C::Value) -> io::Result<()>
    where
        O: Output,
        C: Codec<Unit = O::Item> + Default,
        C::EncodeError: StdError + Send + Sync + 'static;
}

impl<O> TranscodeEncodeOutputExt<O> for TranscodeEncodeOutput<O>
where
    O: Output,
    O::Item: Copy + Default,
{
    /// Encodes a value with a fresh default codec and writes its units to the
    /// underlying output.
    ///
    /// Codec failures are converted to `InvalidData`; output failures are
    /// propagated unchanged. The codec unit must match the output item type.
    ///
    /// # Type Parameters
    ///
    /// - `C`: Default codec that encodes the supplied value into output units.
    ///
    /// # Parameters
    ///
    /// - `self`: Transcoding output adapter receiving the encoded units.
    /// - `value`: Value to encode and write.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` after the encoded units are accepted by the output.
    ///
    /// # Errors
    ///
    /// Returns `InvalidData` if encoding fails, or the output's error if
    /// writing fails.
    ///
    /// # Panics
    ///
    /// Panics if `C::default()` panics, or if the codec violates the encoding
    /// bounds enforced by the underlying transcoding adapter.
    #[inline(always)]
    fn write_encoded<C>(&mut self, value: C::Value) -> io::Result<()>
    where
        O: Output,
        O::Item: Copy + Default,
        C: Codec<Unit = O::Item> + Default,
        C::EncodeError: StdError + Send + Sync + 'static,
    {
        let mut codec = C::default();
        self.write_encoded_with(&mut codec, &value, |source| Error::new(ErrorKind::InvalidData, source))
    }
}