Coverage Report

Created: 2025-05-07 06:59

/rust/registry/src/index.crates.io-6f17d22bba15001f/futures-util-0.3.31/src/io/window.rs
Line
Count
Source (jump to first uncovered line)
1
use std::ops::{Bound, Range, RangeBounds};
2
3
/// An owned window around an underlying buffer.
4
///
5
/// Normally slices work great for considering sub-portions of a buffer, but
6
/// unfortunately a slice is a *borrowed* type in Rust which has an associated
7
/// lifetime. When working with future and async I/O these lifetimes are not
8
/// always appropriate, and are sometimes difficult to store in tasks. This
9
/// type strives to fill this gap by providing an "owned slice" around an
10
/// underlying buffer of bytes.
11
///
12
/// A `Window<T>` wraps an underlying buffer, `T`, and has configurable
13
/// start/end indexes to alter the behavior of the `AsRef<[u8]>` implementation
14
/// that this type carries.
15
///
16
/// This type can be particularly useful when working with the `write_all`
17
/// combinator in this crate. Data can be sliced via `Window`, consumed by
18
/// `write_all`, and then earned back once the write operation finishes through
19
/// the `into_inner` method on this type.
20
#[derive(Debug)]
21
pub struct Window<T> {
22
    inner: T,
23
    range: Range<usize>,
24
}
25
26
impl<T: AsRef<[u8]>> Window<T> {
27
    /// Creates a new window around the buffer `t` defaulting to the entire
28
    /// slice.
29
    ///
30
    /// Further methods can be called on the returned `Window<T>` to alter the
31
    /// window into the data provided.
32
0
    pub fn new(t: T) -> Self {
33
0
        Self { range: 0..t.as_ref().len(), inner: t }
34
0
    }
35
36
    /// Gets a shared reference to the underlying buffer inside of this
37
    /// `Window`.
38
0
    pub fn get_ref(&self) -> &T {
39
0
        &self.inner
40
0
    }
41
42
    /// Gets a mutable reference to the underlying buffer inside of this
43
    /// `Window`.
44
0
    pub fn get_mut(&mut self) -> &mut T {
45
0
        &mut self.inner
46
0
    }
47
48
    /// Consumes this `Window`, returning the underlying buffer.
49
0
    pub fn into_inner(self) -> T {
50
0
        self.inner
51
0
    }
52
53
    /// Returns the starting index of this window into the underlying buffer
54
    /// `T`.
55
0
    pub fn start(&self) -> usize {
56
0
        self.range.start
57
0
    }
58
59
    /// Returns the end index of this window into the underlying buffer
60
    /// `T`.
61
0
    pub fn end(&self) -> usize {
62
0
        self.range.end
63
0
    }
64
65
    /// Changes the range of this window to the range specified.
66
    ///
67
    /// # Panics
68
    ///
69
    /// This method will panic if `range` is out of bounds for the underlying
70
    /// slice or if [`start_bound()`] of `range` comes after the [`end_bound()`].
71
    ///
72
    /// [`start_bound()`]: std::ops::RangeBounds::start_bound
73
    /// [`end_bound()`]: std::ops::RangeBounds::end_bound
74
0
    pub fn set<R: RangeBounds<usize>>(&mut self, range: R) {
75
0
        let start = match range.start_bound() {
76
0
            Bound::Included(n) => *n,
77
0
            Bound::Excluded(n) => *n + 1,
78
0
            Bound::Unbounded => 0,
79
        };
80
0
        let end = match range.end_bound() {
81
0
            Bound::Included(n) => *n + 1,
82
0
            Bound::Excluded(n) => *n,
83
0
            Bound::Unbounded => self.inner.as_ref().len(),
84
        };
85
86
0
        assert!(end <= self.inner.as_ref().len());
87
0
        assert!(start <= end);
88
89
0
        self.range.start = start;
90
0
        self.range.end = end;
91
0
    }
92
}
93
94
impl<T: AsRef<[u8]>> AsRef<[u8]> for Window<T> {
95
0
    fn as_ref(&self) -> &[u8] {
96
0
        &self.inner.as_ref()[self.range.start..self.range.end]
97
0
    }
98
}
99
100
impl<T: AsMut<[u8]>> AsMut<[u8]> for Window<T> {
101
0
    fn as_mut(&mut self) -> &mut [u8] {
102
0
        &mut self.inner.as_mut()[self.range.start..self.range.end]
103
0
    }
104
}