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

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
use std::io::{
    Result,
    Seek,
    SeekFrom,
};

/// Guard that restores a seekable stream to its original position.
///
/// `PositionGuard` captures the stream position when it is created and seeks
/// back to that position when the guard is dropped, unless
/// [`PositionGuard::restore`] or [`PositionGuard::dismiss`] has already
/// completed. Drop-time restoration errors are ignored because [`Drop::drop`]
/// cannot return a [`Result`]; call [`PositionGuard::restore`] when the error
/// must be observed. A failed drop-time restore does not panic and is not
/// logged by this type.
///
/// # Examples
/// ```
/// use std::io::{
///     Cursor,
///     Seek,
///     SeekFrom,
/// };
///
/// use qubit_io::PositionGuard;
///
/// let mut stream = Cursor::new(b"abcdef".to_vec());
/// stream.seek(SeekFrom::Start(2))?;
///
/// {
///     let mut guard = PositionGuard::new(&mut stream)?;
///     guard.inner_mut().seek(SeekFrom::End(0))?;
/// }
///
/// assert_eq!(2, stream.position());
/// # Ok::<(), std::io::Error>(())
/// ```
pub struct PositionGuard<'a, S>
where
    S: Seek + ?Sized,
{
    stream: &'a mut S,
    position: u64,
    done: bool,
}

impl<'a, S> PositionGuard<'a, S>
where
    S: Seek + ?Sized,
{
    /// Captures the current position of `stream`.
    ///
    /// # Parameters
    /// - `stream`: Seekable stream to guard.
    ///
    /// # Returns
    /// A guard that will restore the captured position on drop.
    ///
    /// # Errors
    /// Returns the error reported by [`Seek::stream_position`] when the current
    /// position cannot be read.
    #[inline]
    pub fn new(stream: &'a mut S) -> Result<Self> {
        let position = stream.stream_position()?;
        Ok(Self {
            stream,
            position,
            done: false,
        })
    }

    /// Returns the captured stream position.
    ///
    /// # Returns
    /// The position captured when this guard was created.
    #[inline]
    pub fn position(&self) -> u64 {
        self.position
    }

    /// Returns a mutable reference to the guarded stream.
    ///
    /// # Returns
    /// The guarded stream reference.
    #[inline]
    pub fn inner_mut(&mut self) -> &mut S {
        self.stream
    }

    /// Restores the captured position immediately.
    ///
    /// After a successful restore, drop-time restoration is disabled. If
    /// restoring fails, drop will still make a best-effort restore attempt.
    ///
    /// # Errors
    /// Returns the error reported by [`Seek::seek`] when the stream cannot seek
    /// back to the captured position.
    pub fn restore(&mut self) -> Result<()> {
        self.stream.seek(SeekFrom::Start(self.position)).map(|_| {
            self.done = true;
        })
    }

    /// Disables drop-time restoration without moving the stream.
    ///
    /// This is useful when the caller intentionally wants to keep the stream at
    /// its current position.
    #[inline]
    pub fn dismiss(mut self) {
        self.done = true;
    }
}

impl<S> Drop for PositionGuard<'_, S>
where
    S: Seek + ?Sized,
{
    fn drop(&mut self) {
        if !self.done {
            drop(self.stream.seek(SeekFrom::Start(self.position)));
        }
    }
}