gotham/state/
from_state.rs

1use crate::state::{State, StateData};
2
3/// A trait for accessing data that is stored in `State`.
4///
5/// This provides the easier `T::try_borrow_from(&state)` API (for example), as an alternative to
6/// `state.try_borrow::<T>()`.
7pub trait FromState: StateData + Sized {
8    /// Tries to borrow a value from the `State` storage.
9    ///
10    /// # Examples
11    ///
12    /// ```rust
13    /// # extern crate gotham;
14    /// # #[macro_use]
15    /// # extern crate gotham_derive;
16    /// #
17    /// # use gotham::state::{FromState, State};
18    /// #
19    /// # fn main() {
20    /// #[derive(StateData, Eq, PartialEq, Debug)]
21    /// struct MyStruct {
22    ///     val: &'static str,
23    /// }
24    ///
25    /// # State::with_new(|state| {
26    /// state.put(MyStruct {
27    ///     val: "This is the value!",
28    /// });
29    ///
30    /// match MyStruct::try_borrow_from(&state) {
31    ///     Some(&MyStruct { val }) => assert_eq!(val, "This is the value!"),
32    ///     _ => panic!("expected `MyStruct` to be present"),
33    /// }
34    /// # });
35    /// # }
36    /// ```
37    fn try_borrow_from(state: &State) -> Option<&Self>;
38
39    /// Borrows a value from the `State` storage.
40    ///
41    /// # Panics
42    ///
43    /// If `Self` is not present in `State`.
44    ///
45    /// # Examples
46    ///
47    /// ```rust
48    /// # extern crate gotham;
49    /// # #[macro_use]
50    /// # extern crate gotham_derive;
51    /// #
52    /// # use gotham::state::{FromState, State};
53    /// #
54    /// # fn main() {
55    /// #[derive(StateData, Eq, PartialEq, Debug)]
56    /// struct MyStruct {
57    ///     val: &'static str,
58    /// }
59    ///
60    /// # State::with_new(|state| {
61    /// state.put(MyStruct {
62    ///     val: "This is the value!",
63    /// });
64    ///
65    /// let my_struct = MyStruct::borrow_from(&state);
66    /// assert_eq!(my_struct.val, "This is the value!");
67    /// # });
68    /// # }
69    /// ```
70    fn borrow_from(state: &State) -> &Self;
71
72    /// Tries to mutably borrow a value from the `State` storage.
73    ///
74    /// # Examples
75    ///
76    /// ```rust
77    /// # extern crate gotham;
78    /// # #[macro_use]
79    /// # extern crate gotham_derive;
80    /// #
81    /// # use gotham::state::{FromState, State};
82    /// #
83    /// # fn main() {
84    /// #[derive(StateData, Eq, PartialEq, Debug)]
85    /// struct MyStruct {
86    ///     val: &'static str,
87    /// }
88    ///
89    /// # State::with_new(|mut state| {
90    /// state.put(MyStruct {
91    ///     val: "This is the value!",
92    /// });
93    ///
94    /// match MyStruct::try_borrow_mut_from(&mut state) {
95    ///     Some(&mut MyStruct { ref mut val }) => *val = "This is the new value!",
96    ///     _ => panic!("expected `MyStruct` to be present"),
97    /// }
98    /// #
99    /// # assert_eq!(MyStruct::borrow_from(&state).val, "This is the new value!");
100    /// # });
101    /// # }
102    /// ```
103    fn try_borrow_mut_from(state: &mut State) -> Option<&mut Self>;
104
105    /// Mutably borrows a value from the `State` storage.
106    ///
107    /// # Panics
108    ///
109    /// If `Self` is not present in `State`.
110    ///
111    /// # Examples
112    ///
113    /// ```rust
114    /// # extern crate gotham;
115    /// # #[macro_use]
116    /// # extern crate gotham_derive;
117    /// #
118    /// # use gotham::state::{FromState, State};
119    /// #
120    /// # fn main() {
121    /// #[derive(StateData, Eq, PartialEq, Debug)]
122    /// struct MyStruct {
123    ///     val: &'static str,
124    /// }
125    ///
126    /// # State::with_new(|mut state| {
127    /// state.put(MyStruct {
128    ///     val: "This is the value!",
129    /// });
130    ///
131    /// # {
132    /// let my_struct = MyStruct::borrow_mut_from(&mut state);
133    /// my_struct.val = "This is the new value!";
134    /// # }
135    /// # assert_eq!(MyStruct::borrow_from(&state).val, "This is the new value!");
136    /// # });
137    /// # }
138    /// ```
139    fn borrow_mut_from(state: &mut State) -> &mut Self;
140
141    /// Tries to move a value out of the `State` storage and return ownership.
142    ///
143    /// # Examples
144    ///
145    /// ```rust
146    /// # extern crate gotham;
147    /// # #[macro_use]
148    /// # extern crate gotham_derive;
149    /// #
150    /// # use gotham::state::{FromState, State};
151    /// #
152    /// # fn main() {
153    /// #[derive(StateData, Eq, PartialEq, Debug)]
154    /// struct MyStruct {
155    ///     val: &'static str,
156    /// }
157    ///
158    /// # State::with_new(|mut state| {
159    /// state.put(MyStruct {
160    ///     val: "This is the value!",
161    /// });
162    ///
163    /// match MyStruct::try_take_from(&mut state) {
164    ///     Some(MyStruct { val }) => assert_eq!(val, "This is the value!"),
165    ///     _ => panic!("expected `MyStruct` to be present"),
166    /// }
167    /// # });
168    /// # }
169    /// ```
170    fn try_take_from(state: &mut State) -> Option<Self>;
171
172    /// Moves a value out of the `State` storage and returns ownership.
173    ///
174    /// # Panics
175    ///
176    /// If `Self` is not present in `State`.
177    ///
178    /// # Examples
179    ///
180    /// ```rust
181    /// # extern crate gotham;
182    /// # #[macro_use]
183    /// # extern crate gotham_derive;
184    /// #
185    /// # use gotham::state::{FromState, State};
186    /// #
187    /// # fn main() {
188    /// #[derive(StateData, Eq, PartialEq, Debug)]
189    /// struct MyStruct {
190    ///     val: &'static str,
191    /// }
192    ///
193    /// # State::with_new(|mut state| {
194    /// state.put(MyStruct {
195    ///     val: "This is the value!",
196    /// });
197    ///
198    /// let my_struct = MyStruct::take_from(&mut state);
199    /// assert_eq!(my_struct.val, "This is the value!");
200    /// # });
201    /// # }
202    /// ```
203    fn take_from(state: &mut State) -> Self;
204}
205
206impl<T> FromState for T
207where
208    T: StateData,
209{
210    fn try_borrow_from(state: &State) -> Option<&Self> {
211        state.try_borrow()
212    }
213
214    fn borrow_from(state: &State) -> &Self {
215        state.borrow()
216    }
217
218    fn try_borrow_mut_from(state: &mut State) -> Option<&mut Self> {
219        state.try_borrow_mut()
220    }
221
222    fn borrow_mut_from(state: &mut State) -> &mut Self {
223        state.borrow_mut()
224    }
225
226    fn try_take_from(state: &mut State) -> Option<Self> {
227        state.try_take()
228    }
229
230    fn take_from(state: &mut State) -> Self {
231        state.take()
232    }
233}
gotham/state/from_state.rs

gotham/state/
from_state.rs
