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
135
136
137
138
139
140
141
142
143

use fdb::error::FdbError;

use std::error::Error;
use std::fmt::{self, Display};
use std::sync::Arc;

use crate::cursor::Continuation;

/// Result obtained when [`Cursor`] advances.
///
/// It represents everything that one can learn each time a [`Cursor`]
/// advances. It consists of two variants:
///
/// 1. `Ok(`[`CursorSuccess`]`<T>)` is the next object of type `T`
///    produced by the cursor. In addition to the next object, it also
///    includes a [`CursorResultContinuation`] that can be used to
///    continue the cursor after the last object is returned.
///
/// 2. `Err(`[`CursorError`]`<T>)` represents an error condition which
///    could be an [`FdbError`] or cursor termination due to in-band
///    or out-of-band cursor termination ([`NoNextReason`]). In both
///    the cases a [`CursorResultContinuation`] is included that can
///    be used to continue the cursor.
///
/// [`Cursor`]: crate::cursor::Cursor
pub type CursorResult<T> = Result<CursorSuccess<T>, CursorError>;

/// A [`Continuation`] that is present within [`CursorResult`] and
/// returned when the [`Cursor`] advances.
///
/// [`Continuation`]: crate::cursor::Continuation
/// [`Cursor`]: crate::cursor::Cursor
pub type CursorResultContinuation = Arc<dyn Continuation + Send + Sync + 'static>;

/// Track reason for in-band or out-of-band cursor termination.
#[derive(Clone, Debug)]
pub enum NoNextReason {
    /// The underlying scan, irrespective of any limit, has reached
    /// the end (in-band).
    ///
    /// If the cursor reaches return limit and exhausts the source at
    /// the same time, then return limit is returned.
    SourceExhausted(CursorResultContinuation),
    /// The limit on the number of items to return was reached (in-band).
    ///
    /// If the cursor reaches return limit and exhausts the source at
    /// the same time, then return limit is returned.
    ReturnLimitReached(CursorResultContinuation),
    /// The limit on the amount of time that a scan can take was
    /// reached (out-of-band).
    TimeLimitReached(CursorResultContinuation),
    /// The limit on the number of bytes to scan was reached (out-of-band).
    ByteLimitReached(CursorResultContinuation),
    /// The limit on the number of key-values to scan was reached (out-of-band).
    KeyValueLimitReached(CursorResultContinuation),
}

/// Object of type `T` produced by a [`Cursor`] along with a
/// [`CursorResultContinuation`].
///
/// [`Cursor`]: crate::cursor::Cursor
#[derive(Clone, Debug)]
pub struct CursorSuccess<T> {
    value: T,
    continuation: CursorResultContinuation,
}

impl<T> CursorSuccess<T> {
    /// Construct a new [`CursorSuccess`].
    pub(crate) fn new(value: T, continuation: CursorResultContinuation) -> CursorSuccess<T> {
        CursorSuccess {
            value,
            continuation,
        }
    }

    /// Map [`CursorSuccess<T>`] to [`CursorSuccess<U>`].
    pub fn map<F, U>(self, f: F) -> CursorSuccess<U>
    where
        F: FnOnce(T) -> U,
    {
        let CursorSuccess {
            value,
            continuation,
        } = self;
        CursorSuccess {
            value: f(value),
            continuation,
        }
    }

    /// Gets a reference to success value from [`CursorSuccess`].
    pub fn get_value_ref(&self) -> &T {
        &self.value
    }

    /// Gets a reference to continuation from [`CursorSuccess`].
    pub fn get_continuation_ref(&self) -> &CursorResultContinuation {
        &self.continuation
    }

    /// Extract success value from [`CursorSuccess`].
    pub fn into_value(self) -> T {
        self.value
    }

    /// Extract continuation from [`CursorSuccess`].
    pub fn into_continuation(self) -> CursorResultContinuation {
        self.continuation
    }

    /// Extract success value and continuation from [`CursorSuccess`].
    pub fn into_parts(self) -> (T, CursorResultContinuation) {
        (self.value, self.continuation)
    }
}

/// Error that occurred when advancing the [`Cursor`].
///
/// Includes a [`CursorResultContinuation`] that can be used to
/// continue the cursor.
///
/// [`Cursor`]: crate::cursor::Cursor
#[derive(Clone, Debug)]
pub enum CursorError {
    /// [`FdbError`] occurred.
    FdbError(FdbError, CursorResultContinuation),
    /// In-band or out-of-band cursor termination occurred.
    NoNextReason(NoNextReason),
}

impl Error for CursorError {}

impl Display for CursorError {
    fn fmt<'a>(&self, f: &mut fmt::Formatter<'a>) -> fmt::Result {
        write!(f, "{:?}", self)
    }
}

#[cfg(test)]
mod tests {
    // No tests here as we are just defining types.
}