x-bow: guaranteed get and set methods, plus more documentations

Author: wishawa

x-bow/src/guarantee.rs

@@ -35,4 +35,24 @@ pub trait PathExtGuaranteed: PathExt {
     fn borrow_mut_without_notifying(&self) -> RefMut<'_, <Self as Path>::Out> {
         self.borrow_opt_mut_without_notifying().unwrap()
     }
+
+    /// Clone the data identified by this path.
+    ///
+    /// Equivalent to `path.borrow().clone()`.
+    fn get(&self) -> Self::Out
+    where
+        Self::Out: Clone,
+    {
+        self.borrow().clone()
+    }
+
+    /// Set the data identified by this path, notifying listeners.
+    ///
+    /// Equivalent to `*path.borrow_mut() = data;`
+    fn set(&self, data: Self::Out)
+    where
+        Self::Out: Sized,
+    {
+        *self.borrow_mut() = data;
+    }
 }

x-bow/src/lib.rs

@@ -34,7 +34,7 @@
 //! let stream = path.until_change();
 //!
 //! // Mutably borrow the `i32` of the path, and increment it.
-//! // This will cause the `stream` we create to fire.
+//! // This will cause the `stream` we created to fire.
 //! *path.borrow_mut() += 1;
 //! ```
 //!
@@ -68,6 +68,103 @@
 //! Types that implements [Trackable] have their corresponding `PathBuilder` type.
 //! To be `Trackable`, types should have `#[derive(Trackable)]` on them.
 //!
+//! ## Usage
+//! ### Steps
+//! 1.  Make your structs and enums trackable by putting
+//!     `#[derive(Trackable)]` and `[track(deep)]` on them.
+//!     See documentation for the [Trackable macro][derive@Trackable].
+//!     ```
+//!     # use x_bow::{Trackable, Store, PathExt, PathExtGuaranteed};
+//!     // 👇 Derive `Trackable` to allow parts of the struct to be tracked.
+//!     #[derive(Trackable)]
+//!     #[track(deep)]
+//!     struct MyStruct {
+//!         field_1: i32,
+//!         field_2: u64,
+//!         child_enum: MyEnum
+//!     }
+//!     // 👇 Derive `Trackable` to allow parts of the enum to be tracked.
+//!     #[derive(Trackable)]
+//!     #[track(deep)]
+//!     enum MyEnum {
+//!         Variant1(i32),
+//!         Variant2 {
+//!             data: String
+//!         }
+//!     }
+//!     ```
+//! 2.  Put your data in a [Store].
+//!     ```
+//!     # use x_bow::{Trackable, Store, PathExt, PathExtGuaranteed};
+//!     # #[derive(Trackable)]
+//!     # #[track(deep)]
+//!     # struct MyStruct {
+//!     #     field_1: i32,
+//!     #     field_2: u64,
+//!     #     child_enum: MyEnum
+//!     # }
+//!     #
+//!     # #[derive(Trackable)]
+//!     # #[track(deep)]
+//!     # enum MyEnum {
+//!     #     Variant1(i32),
+//!     #     Variant2 {
+//!     #         data: String
+//!     #     }
+//!     # }
+//!     let my_data = MyStruct {
+//!         field_1: 42,
+//!         field_2: 123,
+//!         child_enum: MyEnum::Variant2 { data: "Hello".to_string() }
+//!     };
+//!     let store = Store::new(my_data);
+//!     ```
+//! 3.  Make [Path]s.
+//!     ```
+//!     # use x_bow::{Trackable, Store, PathExt, PathExtGuaranteed};
+//!     # #[derive(Trackable)]
+//!     # #[track(deep)]
+//!     # struct MyStruct {
+//!     #     field_1: i32,
+//!     #     field_2: u64,
+//!     #     child_enum: MyEnum
+//!     # }
+//!     #
+//!     # #[derive(Trackable)]
+//!     # #[track(deep)]
+//!     # enum MyEnum {
+//!     #     Variant1(i32),
+//!     #     Variant2 {
+//!     #         data: String
+//!     #     }
+//!     # }
+//!     let my_data = MyStruct {
+//!         field_1: 42,
+//!         field_2: 123,
+//!         child_enum: MyEnum::Variant2 { data: "Hello".to_string() }
+//!     };
+//!     # let store = Store::new(my_data);
+//!     let path_to_field_1 = store.build_path().field_1();
+//!     let path_to_data = store.build_path().child_enum().Variant2_data();
+//!     ```
+//! 4.  Use the Paths you made.
+//!     See [PathExt] and [PathExtGuaranteed] for available APIs.
+//!
+//! ### Tracking through Vec and HashMap
+//! You can track through [Vec] using the `index(_)` method.
+//! ```
+//! # use x_bow::{Trackable, Store, PathExt, PathExtGuaranteed};
+//! let store = Store::new(vec![1, 2, 3]);
+//! let path = store.build_path().index(1); // 👈 path to the second element in the vec
+//! ```
+//! You can track through [HashMap][std::collections::HashMap] using the `key(_)` method.
+//! ```
+//! # use x_bow::{Trackable, Store, PathExt, PathExtGuaranteed};
+//! # use std::collections::HashMap;
+//! let store = Store::new(HashMap::<u32, String>::new());
+//! let path = store.build_path().key(555); // 👈 path to the String at key 555 in the hashmap.
+//! ```
+//!
 //! ## Design
 //!
 //! ### Borrowing and Paths

x-bow/src/path_ext.rs

@@ -129,7 +129,7 @@ pub trait PathExt: Path {
     /// Clone the data identified by this path.
     ///
     /// Equivalent to `path.borrow_opt().as_deref().map(Clone::clone)`.
-    fn get_cloned(&self) -> Option<Self::Out>
+    fn get_opt(&self) -> Option<Self::Out>
     where
         Self::Out: Clone,
     {
@@ -138,17 +138,18 @@ pub trait PathExt: Path {
 
     /// Set the data identified by this path, notifying listeners.
     ///
-    /// Returns whether or not the data was set.
-    ///
-    /// Equivalent to `self.borrow_opt_mut().as_deref_mut().map(|s| *s = data).is_some()`.
-    fn set(&self, data: Self::Out) -> bool
+    /// If the data cannot be accessed, Err is returned with the input.
+    fn set_opt(&self, data: Self::Out) -> Result<(), Self::Out>
     where
         Self::Out: Sized,
     {
-        self.borrow_opt_mut()
-            .as_deref_mut()
-            .map(|s| *s = data)
-            .is_some()
+        match self.borrow_opt_mut().as_deref_mut() {
+            Some(state) => {
+                *state = data;
+                Ok(())
+            }
+            None => Err(data),
+        }
     }
 
     /// Get a [Stream][futures_core::Stream] that fires everytime a mutable
@@ -425,6 +426,22 @@ pub trait PathExt: Path {
     /// This is useful when you are handling the type that implements `Path`
     /// directly. Most of the time, though, you will already be working with
     /// `PathBuilder`s.
+    /// 
+    /// ```
+    /// # use x_bow::{Path, PathExt, PathExtGuaranteed, Store, Trackable, IntoPath};
+    /// fn modify_string(path: impl Path<Out = String>) {
+    ///     path.set_opt("haha".to_string()).ok();
+    /// }
+    /// #[derive(Trackable)]
+    /// struct MyStruct {
+    ///     s: String
+    /// }
+    /// let store = Store::new(MyStruct {
+    ///     s: String::from("hello world")
+    /// });
+    /// modify_string(store.build_path().s().into_path());
+    /// assert_eq!(&**store.build_path().s().borrow(), "haha");
+    /// ```
     fn build_path(self) -> <Self::Out as Trackable>::PathBuilder<Self>
     where
         Self: Sized,
@@ -435,7 +452,6 @@ pub trait PathExt: Path {
 
     /// Create a new Path from borrowing this path.
     ///
-    /// Usually, paths are owned and live for as long as the store itself.
     /// ```
     /// # use x_bow::{Trackable, Store, PathExt};
     /// # #[derive(Default, Trackable)]

x-bow/tests/get_and_set.rs

@@ -0,0 +1,26 @@
+use x_bow::{PathExtGuaranteed, Store};
+use x_bow_macros::Trackable;
+
+#[test]
+fn get_and_set() {
+    #[derive(Trackable, Debug, Default, PartialEq, Clone)]
+    #[track(deep)]
+    struct State {
+        a: String,
+        b: (Struct1, i32),
+    }
+    #[derive(Trackable, Debug, Default, PartialEq, Clone)]
+    #[track(deep)]
+    struct Struct1 {
+        c: i32,
+    }
+    let state = Store::new(State {
+        a: String::from("Hello World"),
+        b: (Struct1 { c: 5678 }, 1234),
+    });
+    assert_eq!(state.build_path().b().t1().get(), 1234);
+    assert_eq!(state.build_path().b().t0().get(), Struct1 { c: 5678 });
+    assert_eq!(state.build_path().b().t0().c().get(), 5678);
+    state.build_path().b().t0().set(Struct1 { c: 42 });
+    assert_eq!(state.build_path().b().t0().c().get(), 42);
+}