qubit-io 0.13.0

Byte-stream buffering and std::io utilities for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

use std::io::{
    Result,
    SeekFrom,
};

use crate::{
    BufferedOutput,
    Output,
    Seekable,
    SeekableOutput,
};

/// Output value that is guaranteed to report itself as buffered.
///
/// This enum is returned by [`BufferedOutput::ensure`]. It keeps an output that
/// already buffers items as-is, and wraps an unbuffered output in
/// [`BufferedOutput`]. Operations delegate to the selected branch.
pub enum EnsuredBufferedOutput<O>
where
    O: Output,
    O::Item: Copy + Default,
{
    /// The original output already reported itself as buffered.
    AlreadyBuffered(O),

    /// The original output was wrapped in [`BufferedOutput`].
    Buffered(BufferedOutput<O>),
}

impl<O> Output for EnsuredBufferedOutput<O>
where
    O: Output,
    O::Item: Copy + Default,
{
    type Item = O::Item;

    /// Reports that this output is buffered.
    #[inline(always)]
    fn is_buffered(&self) -> bool {
        true
    }

    /// Writes items through the selected output branch.
    #[inline(always)]
    unsafe fn write_unchecked(
        &mut self,
        input: &[Self::Item],
        index: usize,
        count: usize,
    ) -> Result<usize> {
        match self {
            Self::AlreadyBuffered(output) => {
                // SAFETY: Forwarded from the trait caller.
                unsafe { output.write_unchecked(input, index, count) }
            }
            Self::Buffered(output) => {
                // SAFETY: Forwarded from the trait caller.
                unsafe { output.write_unchecked(input, index, count) }
            }
        }
    }

    /// Writes items from the full input slice.
    #[inline(always)]
    fn write(&mut self, input: &[Self::Item]) -> Result<usize> {
        match self {
            Self::AlreadyBuffered(output) => output.write(input),
            Self::Buffered(output) => output.write(input),
        }
    }

    /// Writes all items from an indexed input range.
    #[inline(always)]
    unsafe fn write_fully_unchecked(
        &mut self,
        input: &[Self::Item],
        index: usize,
        count: usize,
    ) -> Result<()> {
        match self {
            Self::AlreadyBuffered(output) => {
                // SAFETY: Forwarded from the trait caller.
                unsafe { output.write_fully_unchecked(input, index, count) }
            }
            Self::Buffered(output) => {
                // SAFETY: Forwarded from the trait caller.
                unsafe { output.write_fully_unchecked(input, index, count) }
            }
        }
    }

    /// Writes all items from the full input slice.
    #[inline(always)]
    fn write_fully(&mut self, input: &[Self::Item]) -> Result<()> {
        match self {
            Self::AlreadyBuffered(output) => output.write_fully(input),
            Self::Buffered(output) => output.write_fully(input),
        }
    }

    /// Flushes pending items through the selected output branch.
    #[inline(always)]
    fn flush(&mut self) -> Result<()> {
        match self {
            Self::AlreadyBuffered(output) => output.flush(),
            Self::Buffered(output) => output.flush(),
        }
    }
}

impl<O> Seekable for EnsuredBufferedOutput<O>
where
    O: SeekableOutput,
    <O as Output>::Item: Copy + Default,
{
    type Unit = <O as Output>::Item;

    /// Seeks in item offsets through the selected output branch.
    #[inline(always)]
    fn seek_to(&mut self, position: SeekFrom) -> Result<u64> {
        match self {
            Self::AlreadyBuffered(output) => output.seek_to(position),
            Self::Buffered(output) => output.seek_to(position),
        }
    }
}