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

//! Contains the `Cursor` trait.


use futures_core::future::BoxFuture;

use crate::database::Database;
use crate::executor::Execute;
use crate::pool::Pool;
use crate::row::HasRow;
use serde::de::DeserializeOwned;

/// Represents a result set, which is generated by executing a query against the database.

///

/// A `Cursor` can be created by either [`Executor::fetch`] or [`Query::fetch`].

///

/// ```rust,ignore

/// let mut cursor = rbatis_core::query("SELECT slug, title, description FROM articles")

///     .fetch(&mut conn);

/// ```

///

/// Initially the `Cursor` is positioned before the first row. The `next` method moves the cursor

/// to the next row, and because it returns `None` when there are no more rows, it can be used

/// in a `while` loop to iterate through all returned rows.

///

/// ```rust,ignore

/// # #[derive(rbatis_core::FromRow)]

/// # struct Article<'a> {

/// #     slug: &'a str,

/// #     title: &'a str,

/// #     description: &'a str,

/// # }

/// #

/// // For each row in the result set ..

/// while let Some(row) = cursor.next().await? {

///     // .. decode a domain type from the row

///     let obj = Article::from_row(row)?;

/// }

/// ```

///

/// This trait is sealed and cannot be implemented for types outside of rbatis_core.

///

/// [`Executor::fetch`]: crate::executor::Executor::fetch

/// [`Query::fetch`]: crate::query::Query::fetch

#[must_use = "cursor must have `.next()` called to execute query"]
pub trait Cursor<'c, 'q>
where
    Self: Send + Unpin + private::Sealed,
{
    /// The `Database` this `Cursor` is implemented for.

    type Database: Database;

    #[doc(hidden)]
    fn from_pool<E>(pool: &Pool<<Self::Database as Database>::Connection>, query: E) -> Self
    where
        Self: Sized,
        E: Execute<'q, Self::Database>;

    #[doc(hidden)]
    fn from_connection<E>(
        connection: &'c mut <Self::Database as Database>::Connection,
        query: E,
    ) -> Self
    where
        Self: Sized,
        E: Execute<'q, Self::Database>;

    /// Creates a future that attempts to resolve the next row in the cursor.

    fn next<'cur>(
        &'cur mut self,
    ) -> BoxFuture<'cur, crate::Result<Option<<Self::Database as HasRow<'cur>>::Row>>>;


    /// fetch json and decode into type

    fn decode_json<T>(&mut self) -> BoxFuture<Result<T, crate::Error>>
    where  T: DeserializeOwned;

    /// fetch into an json array

    fn fetch_json(&mut self) -> BoxFuture<Result<Vec<serde_json::Value>, crate::Error>>;
}

// Prevent users from implementing the `Row` trait.

pub(crate) mod private {
    pub trait Sealed {}
}

/// Associate [`Database`] with a [`Cursor`] of a generic lifetime.

///

/// ---

///

/// The upcoming Rust feature, [Generic Associated Types], should obviate

/// the need for this trait.

///

/// [Generic Associated Types]: https://www.google.com/search?q=generic+associated+types+rust&oq=generic+associated+types+rust&aqs=chrome..69i57j0l5.3327j0j7&sourceid=chrome&ie=UTF-8

pub trait HasCursor<'c, 'q> {
    type Database: Database;

    /// The concrete `Cursor` implementation for this database.

    type Cursor: Cursor<'c, 'q, Database = Self::Database>;
}