qubit-io 0.12.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

// =============================================================================
//    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::{
    BufferedInput,
    Input,
    Seekable,
    SeekableInput,
};

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

    /// The original input was wrapped in [`BufferedInput`].
    Buffered(BufferedInput<I>),
}

impl<I> Input for EnsuredBufferedInput<I>
where
    I: Input,
    I::Item: Copy + Default,
{
    type Item = I::Item;

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

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

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

    /// Reads items until the indexed output range is full or EOF is reached.
    #[inline(always)]
    unsafe fn read_fully_unchecked(
        &mut self,
        output: &mut [Self::Item],
        index: usize,
        count: usize,
    ) -> Result<usize> {
        match self {
            Self::AlreadyBuffered(input) => {
                // SAFETY: Forwarded from the trait caller.
                unsafe { input.read_fully_unchecked(output, index, count) }
            }
            Self::Buffered(input) => {
                // SAFETY: Forwarded from the trait caller.
                unsafe { input.read_fully_unchecked(output, index, count) }
            }
        }
    }

    /// Reads items into the full output slice until it is full or EOF is
    /// reached.
    #[inline(always)]
    fn read_fully(&mut self, output: &mut [Self::Item]) -> Result<usize> {
        match self {
            Self::AlreadyBuffered(input) => input.read_fully(output),
            Self::Buffered(input) => input.read_fully(output),
        }
    }
}

impl<I> Seekable for EnsuredBufferedInput<I>
where
    I: SeekableInput,
    <I as Input>::Item: Copy + Default,
{
    type Item = <I as Input>::Item;

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