dioxus_signals/read.rs
1use std::{mem::MaybeUninit, ops::Index, rc::Rc};
2
3use generational_box::AnyStorage;
4
5use crate::MappedSignal;
6
7/// A reference to a value that can be read from.
8#[allow(type_alias_bounds)]
9pub type ReadableRef<'a, T: Readable, O = <T as Readable>::Target> =
10 <T::Storage as AnyStorage>::Ref<'a, O>;
11
12/// A trait for states that can be read from like [`crate::Signal`], [`crate::GlobalSignal`], or [`crate::ReadOnlySignal`]. You may choose to accept this trait as a parameter instead of the concrete type to allow for more flexibility in your API. For example, instead of creating two functions, one that accepts a [`crate::Signal`] and one that accepts a [`crate::GlobalSignal`], you can create one function that accepts a [`Readable`] type.
13///
14/// # Example
15/// ```rust
16/// # use dioxus::prelude::*;
17/// fn double(something_readable: &impl Readable<Target = i32>) -> i32 {
18/// something_readable.cloned() * 2
19/// }
20///
21/// static COUNT: GlobalSignal<i32> = Signal::global(|| 0);
22///
23/// fn MyComponent(count: Signal<i32>) -> Element {
24/// // Since we defined the function in terms of the readable trait, we can use it with any readable type (Signal, GlobalSignal, ReadOnlySignal, etc)
25/// let doubled = use_memo(move || double(&count));
26/// let global_count_doubled = use_memo(|| double(&COUNT));
27/// rsx! {
28/// div {
29/// "Count local: {count}"
30/// "Doubled local: {doubled}"
31/// "Count global: {COUNT}"
32/// "Doubled global: {global_count_doubled}"
33/// }
34/// }
35/// }
36/// ```
37pub trait Readable {
38 /// The target type of the reference.
39 type Target: ?Sized + 'static;
40
41 /// The type of the storage this readable uses.
42 type Storage: AnyStorage;
43
44 /// Map the readable type to a new type. This lets you provide a view into a readable type without needing to clone the inner value.
45 ///
46 /// Anything that subscribes to the readable value will be rerun whenever the original value changes, even if the view does not change. If you want to memorize the view, you can use a [`crate::Memo`] instead.
47 ///
48 /// # Example
49 /// ```rust
50 /// # use dioxus::prelude::*;
51 /// fn List(list: Signal<Vec<i32>>) -> Element {
52 /// rsx! {
53 /// for index in 0..list.len() {
54 /// // We can use the `map` method to provide a view into the single item in the list that the child component will render
55 /// Item { item: list.map(move |v| &v[index]) }
56 /// }
57 /// }
58 /// }
59 ///
60 /// // The child component doesn't need to know that the mapped value is coming from a list
61 /// #[component]
62 /// fn Item(item: MappedSignal<i32>) -> Element {
63 /// rsx! {
64 /// div { "Item: {item}" }
65 /// }
66 /// }
67 /// ```
68 fn map<O>(self, f: impl Fn(&Self::Target) -> &O + 'static) -> MappedSignal<O, Self::Storage>
69 where
70 Self: Clone + Sized + 'static,
71 {
72 let mapping = Rc::new(f);
73 let try_read = Rc::new({
74 let self_ = self.clone();
75 let mapping = mapping.clone();
76 move || {
77 self_
78 .try_read_unchecked()
79 .map(|ref_| <Self::Storage as AnyStorage>::map(ref_, |r| mapping(r)))
80 }
81 })
82 as Rc<
83 dyn Fn() -> Result<ReadableRef<'static, Self, O>, generational_box::BorrowError>
84 + 'static,
85 >;
86 let try_peek = Rc::new({
87 let self_ = self.clone();
88 let mapping = mapping.clone();
89 move || {
90 self_
91 .try_peek_unchecked()
92 .map(|ref_| <Self::Storage as AnyStorage>::map(ref_, |r| mapping(r)))
93 }
94 })
95 as Rc<
96 dyn Fn() -> Result<ReadableRef<'static, Self, O>, generational_box::BorrowError>
97 + 'static,
98 >;
99 MappedSignal::new(try_read, try_peek)
100 }
101
102 /// Get the current value of the state. If this is a signal, this will subscribe the current scope to the signal.
103 /// If the value has been dropped, this will panic. Calling this on a Signal is the same as
104 /// using the signal() syntax to read and subscribe to its value
105 #[track_caller]
106 fn read(&self) -> ReadableRef<Self> {
107 self.try_read().unwrap()
108 }
109
110 /// Try to get the current value of the state. If this is a signal, this will subscribe the current scope to the signal.
111 #[track_caller]
112 fn try_read(&self) -> Result<ReadableRef<Self>, generational_box::BorrowError> {
113 self.try_read_unchecked()
114 .map(Self::Storage::downcast_lifetime_ref)
115 }
116
117 /// Get a reference to the value without checking the lifetime. This will subscribe the current scope to the signal.
118 ///
119 /// NOTE: This method is completely safe because borrow checking is done at runtime.
120 #[track_caller]
121 fn read_unchecked(&self) -> ReadableRef<'static, Self> {
122 self.try_read_unchecked().unwrap()
123 }
124
125 /// Try to get a reference to the value without checking the lifetime. This will subscribe the current scope to the signal.
126 ///
127 /// NOTE: This method is completely safe because borrow checking is done at runtime.
128 fn try_read_unchecked(
129 &self,
130 ) -> Result<ReadableRef<'static, Self>, generational_box::BorrowError>;
131
132 /// Get the current value of the state without subscribing to updates. If the value has been dropped, this will panic.
133 ///
134 /// # Example
135 /// ```rust
136 /// # use dioxus::prelude::*;
137 /// fn MyComponent(mut count: Signal<i32>) -> Element {
138 /// let mut event_source = use_signal(|| None);
139 /// let doubled = use_memo(move || {
140 /// // We want to log the value of the event_source, but we don't need to rerun the doubled value if the event_source changes (because the value of doubled doesn't depend on the event_source)
141 /// // We can read the value with peek without subscribing to updates
142 /// let source = event_source.peek();
143 /// tracing::info!("Clicked: {source:?}");
144 /// count() * 2
145 /// });
146 /// rsx! {
147 /// div { "Count: {count}" }
148 /// div { "Doubled: {doubled}" }
149 /// button {
150 /// onclick: move |_| {
151 /// event_source.set(Some("Click me button"));
152 /// count += 1;
153 /// },
154 /// "Click me"
155 /// }
156 /// button {
157 /// onclick: move |_| {
158 /// event_source.set(Some("Double me button"));
159 /// count += 1;
160 /// },
161 /// "Double me"
162 /// }
163 /// }
164 /// }
165 /// ```
166 #[track_caller]
167 fn peek(&self) -> ReadableRef<Self> {
168 Self::Storage::downcast_lifetime_ref(self.peek_unchecked())
169 }
170
171 /// Try to peek the current value of the signal without subscribing to updates. If the value has
172 /// been dropped, this will return an error.
173 #[track_caller]
174 fn try_peek(&self) -> Result<ReadableRef<Self>, generational_box::BorrowError> {
175 self.try_peek_unchecked()
176 .map(Self::Storage::downcast_lifetime_ref)
177 }
178
179 /// Get the current value of the signal without checking the lifetime. **Unlike read, this will not subscribe the current scope to the signal which can cause parts of your UI to not update.**
180 ///
181 /// If the signal has been dropped, this will panic.
182 #[track_caller]
183 fn peek_unchecked(&self) -> ReadableRef<'static, Self> {
184 self.try_peek_unchecked().unwrap()
185 }
186
187 /// Try to peek the current value of the signal without subscribing to updates. If the value has
188 /// been dropped, this will return an error.
189 ///
190 /// NOTE: This method is completely safe because borrow checking is done at runtime.
191 fn try_peek_unchecked(
192 &self,
193 ) -> Result<ReadableRef<'static, Self>, generational_box::BorrowError>;
194
195 /// Clone the inner value and return it. If the value has been dropped, this will panic.
196 #[track_caller]
197 fn cloned(&self) -> Self::Target
198 where
199 Self::Target: Clone,
200 {
201 self.read().clone()
202 }
203
204 /// Run a function with a reference to the value. If the value has been dropped, this will panic.
205 #[track_caller]
206 fn with<O>(&self, f: impl FnOnce(&Self::Target) -> O) -> O {
207 f(&*self.read())
208 }
209
210 /// Run a function with a reference to the value. If the value has been dropped, this will panic.
211 #[track_caller]
212 fn with_peek<O>(&self, f: impl FnOnce(&Self::Target) -> O) -> O {
213 f(&*self.peek())
214 }
215
216 /// Index into the inner value and return a reference to the result. If the value has been dropped or the index is invalid, this will panic.
217 #[track_caller]
218 fn index<I>(&self, index: I) -> ReadableRef<Self, <Self::Target as std::ops::Index<I>>::Output>
219 where
220 Self::Target: std::ops::Index<I>,
221 {
222 <Self::Storage as AnyStorage>::map(self.read(), |v| v.index(index))
223 }
224
225 /// SAFETY: You must call this function directly with `self` as the argument.
226 /// This function relies on the size of the object you return from the deref
227 /// being the same as the object you pass in
228 #[doc(hidden)]
229 unsafe fn deref_impl<'a>(&self) -> &'a dyn Fn() -> Self::Target
230 where
231 Self: Sized + 'a,
232 Self::Target: Clone,
233 {
234 // https://github.com/dtolnay/case-studies/tree/master/callable-types
235
236 // First we create a closure that captures something with the Same in memory layout as Self (MaybeUninit<Self>).
237 let uninit_callable = MaybeUninit::<Self>::uninit();
238 // Then move that value into the closure. We assume that the closure now has a in memory layout of Self.
239 let uninit_closure = move || Self::read(unsafe { &*uninit_callable.as_ptr() }).clone();
240
241 // Check that the size of the closure is the same as the size of Self in case the compiler changed the layout of the closure.
242 let size_of_closure = std::mem::size_of_val(&uninit_closure);
243 assert_eq!(size_of_closure, std::mem::size_of::<Self>());
244
245 // Then cast the lifetime of the closure to the lifetime of &self.
246 fn cast_lifetime<'a, T>(_a: &T, b: &'a T) -> &'a T {
247 b
248 }
249 let reference_to_closure = cast_lifetime(
250 {
251 // The real closure that we will never use.
252 &uninit_closure
253 },
254 #[allow(clippy::missing_transmute_annotations)]
255 // We transmute self into a reference to the closure. This is safe because we know that the closure has the same memory layout as Self so &Closure == &Self.
256 unsafe {
257 std::mem::transmute(self)
258 },
259 );
260
261 // Cast the closure to a trait object.
262 reference_to_closure as &_
263 }
264}
265
266/// An extension trait for Readable<Vec<T>> that provides some convenience methods.
267pub trait ReadableVecExt<T: 'static>: Readable<Target = Vec<T>> {
268 /// Returns the length of the inner vector.
269 #[track_caller]
270 fn len(&self) -> usize {
271 self.with(|v| v.len())
272 }
273
274 /// Returns true if the inner vector is empty.
275 #[track_caller]
276 fn is_empty(&self) -> bool {
277 self.with(|v| v.is_empty())
278 }
279
280 /// Get the first element of the inner vector.
281 #[track_caller]
282 fn first(&self) -> Option<ReadableRef<Self, T>> {
283 <Self::Storage as AnyStorage>::try_map(self.read(), |v| v.first())
284 }
285
286 /// Get the last element of the inner vector.
287 #[track_caller]
288 fn last(&self) -> Option<ReadableRef<Self, T>> {
289 <Self::Storage as AnyStorage>::try_map(self.read(), |v| v.last())
290 }
291
292 /// Get the element at the given index of the inner vector.
293 #[track_caller]
294 fn get(&self, index: usize) -> Option<ReadableRef<Self, T>> {
295 <Self::Storage as AnyStorage>::try_map(self.read(), |v| v.get(index))
296 }
297
298 /// Get an iterator over the values of the inner vector.
299 #[track_caller]
300 fn iter(&self) -> ReadableValueIterator<'_, Self>
301 where
302 Self: Sized,
303 {
304 ReadableValueIterator {
305 index: 0,
306 value: self,
307 }
308 }
309}
310
311/// An iterator over the values of a `Readable<Vec<T>>`.
312pub struct ReadableValueIterator<'a, R> {
313 index: usize,
314 value: &'a R,
315}
316
317impl<'a, T: 'static, R: Readable<Target = Vec<T>>> Iterator for ReadableValueIterator<'a, R> {
318 type Item = ReadableRef<'a, R, T>;
319
320 fn next(&mut self) -> Option<Self::Item> {
321 let index = self.index;
322 self.index += 1;
323 self.value.get(index)
324 }
325}
326
327impl<T, R> ReadableVecExt<T> for R
328where
329 T: 'static,
330 R: Readable<Target = Vec<T>>,
331{
332}
333
334/// An extension trait for Readable<Option<T>> that provides some convenience methods.
335pub trait ReadableOptionExt<T: 'static>: Readable<Target = Option<T>> {
336 /// Unwraps the inner value and clones it.
337 #[track_caller]
338 fn unwrap(&self) -> T
339 where
340 T: Clone,
341 {
342 self.as_ref().unwrap().clone()
343 }
344
345 /// Attempts to read the inner value of the Option.
346 #[track_caller]
347 fn as_ref(&self) -> Option<ReadableRef<Self, T>> {
348 <Self::Storage as AnyStorage>::try_map(self.read(), |v| v.as_ref())
349 }
350}
351
352impl<T, R> ReadableOptionExt<T> for R
353where
354 T: 'static,
355 R: Readable<Target = Option<T>>,
356{
357}
358
359/// An extension trait for Readable<Option<T>> that provides some convenience methods.
360pub trait ReadableResultExt<T: 'static, E: 'static>: Readable<Target = Result<T, E>> {
361 /// Unwraps the inner value and clones it.
362 #[track_caller]
363 fn unwrap(&self) -> T
364 where
365 T: Clone,
366 {
367 self.as_ref()
368 .unwrap_or_else(|_| panic!("Tried to unwrap a Result that was an error"))
369 .clone()
370 }
371
372 /// Attempts to read the inner value of the Option.
373 #[track_caller]
374 fn as_ref(&self) -> Result<ReadableRef<Self, T>, ReadableRef<Self, E>> {
375 <Self::Storage as AnyStorage>::try_map(self.read(), |v| v.as_ref().ok()).ok_or(
376 <Self::Storage as AnyStorage>::map(self.read(), |v| v.as_ref().err().unwrap()),
377 )
378 }
379}
380
381impl<T, E, R> ReadableResultExt<T, E> for R
382where
383 T: 'static,
384 E: 'static,
385 R: Readable<Target = Result<T, E>>,
386{
387}