Add groupings tutorial

Author: AljoschaMeyer

rustdocs/source_json/willow25.json

@@ -13,4 +13,4 @@ fn main() {
         .build().unwrap();
 
     println!("{:#?}", entry);
-}
+}

rustdocs/source_json/willow_data_model.json

@@ -12,12 +12,13 @@ fn main() {
         .payload(b"Dear reader, I've got a great idea")
         .build().unwrap();
 
+    println!("{:#?}", entry);
+
     let oops = Entry::prefilled_builder(&entry)
         .path(path!("/blog/idea"))
         .timestamp(entry.timestamp() + 10.minutes())
         .payload(b"")
         .build().unwrap();
 
-    println!("{:#?}", entry);
     println!("{:#?}", oops);
-}
+}

src/code_samples/tut_entry/01.rs

@@ -12,17 +12,18 @@ fn main() {
         .payload(b"Dear reader, I've got a great idea")
         .build().unwrap();
 
+    println!("{:#?}", entry);
+
     let oops = Entry::prefilled_builder(&entry)
         .path(path!("/blog/idea"))
         .timestamp(entry.timestamp() + 10.minutes())
         .payload(b"")
         .build().unwrap();
 
-    println!("{:#?}", entry);
     println!("{:#?}", oops);
 
     assert_eq!(entry.namespace_id(), oops.namespace_id());
     assert_ne!(entry, oops);
     assert!(oops.is_newer_than(&entry));
     assert!(entry.is_pruned_by(&oops));
-}
+}

src/code_samples/tut_entry/02.rs

@@ -1,31 +1,33 @@
-use willow_25::Range;
+use willow25::prelude::*;
 
 fn main() {
-    // Ranges
-    let open_range = Range::new_open(10);
-    let closed_range = Range::new_closed(15, 20).unwrap();
-    let closed_range2 = Range::new_closed(5, 15).unwrap();
+    let namespace_id = NamespaceId::from([0; NAMESPACE_ID_WIDTH]);
+    let subspace_id = SubspaceId::from([1; SUBSPACE_ID_WIDTH]);
 
-    println!("open_range includes 5: {:?}", open_range.includes(&5));
-    println!("open_range includes 15: {:?}", open_range.includes(&10));
+    // Create an entry for comparisons, with a timestamp of 17.
+    let entry = Entry::builder()
+        .namespace_id(namespace_id)
+        .subspace_id(subspace_id)
+        .path(path!("/"))
+        .timestamp(17)
+        .payload(b"bla")
+        .build()
+        .unwrap();
 
-    println!(
-        "open range includes closed_range: {:?}",
-        open_range.includes_range(&closed_range)
-    );
+    // Can create TimeRanges from arbitrary rust ranges of Timestamps.
+    assert!(entry.is_in(&TimeRange::from(5.into()..19.into())));
+    assert!(entry.is_in(&TimeRange::from(5.into()..)));
+    assert!(entry.is_in(&TimeRange::from(..19.into())));
+    assert!(entry.is_in(&TimeRange::from(5.into()..=17.into())));
+    assert!(entry.is_in(&TimeRange::from(..)));
+    assert!(!entry.is_in(&TimeRange::from(33.into()..)));
 
-    println!(
-        "open range includes closed_range2: {:?}",
-        open_range.includes_range(&closed_range2)
-    );
-
-    let intersection = open_range.intersection(&closed_range2);
-
-    match intersection {
-        Some(new_range) => {
-            println!("The intersection of open_range and closed_range2 is:");
-            println!("{:#?}", new_range);
-        }
-        None => panic!("There is no intersection between open_range and closed_range2?!"),
-    }
-}
+    let intersection = TimeRange::from(..19.into())
+        .intersection(&TimeRange::from(5.into()..));
+    assert_eq!(intersection, TimeRange::from(5.into()..19.into()));
+    assert!(entry.is_in(&intersection));
+    assert!(entry.is_in_intersection(
+        &TimeRange::from(..19.into()),
+        &TimeRange::from(5.into()..),
+    ));
+}

src/code_samples/tut_entry/03.rs

@@ -1,86 +1,66 @@
-use willow_25::{Area, Entry, NamespaceId25, Path, PayloadDigest25, Range, SubspaceId25};
-use willow_data_model::grouping::AreaSubspace;
+use willow25::prelude::*;
 
 fn main() {
-    // Ranges
-    let open_range = Range::new_open(10);
-    let closed_range = Range::new_closed(15, 20).unwrap();
-    let closed_range2 = Range::new_closed(5, 15).unwrap();
-
-    println!("open_range includes 5: {:?}", open_range.includes(&5));
-    println!("open_range includes 15: {:?}", open_range.includes(&10));
-
-    println!(
-        "open range includes closed_range: {:?}",
-        open_range.includes_range(&closed_range)
-    );
-
-    println!(
-        "open range includes closed_range2: {:?}",
-        open_range.includes_range(&closed_range2)
-    );
-
-    let intersection = open_range.intersection(&closed_range2);
-
-    match intersection {
-        Some(new_range) => {
-            println!("The intersection of open_range and closed_range2 is:");
-            println!("{:#?}", new_range);
-        }
-        None => panic!("There is no intersection between open_range and closed_range2?!"),
-    }
-
-    // Areas
-
-    let (alfie_subspace, _key) = SubspaceId25::new();
-    let (betty_subspace, _key) = SubspaceId25::new();
-    let blog_path = Path::from_slices(&["blog"]).unwrap();
-
-    let late_time_range = Range::new_closed(500, 1000).unwrap();
-
-    let any_late_blog_area = Area::new(AreaSubspace::Any, blog_path, late_time_range);
-
-    let alfie_early_blog_entry = Entry::new(
-        NamespaceId25::new_communal(),
-        alfie_subspace.clone(),
-        Path::from_slices(&["blog", "breakfast"]).unwrap(),
-        100,
-        0,
-        PayloadDigest25::default(),
-    );
-
-    let betty_late_blog_entry = Entry::new(
-        NamespaceId25::new_communal(),
-        betty_subspace.clone(),
-        Path::from_slices(&["blog", "dinner"]).unwrap(),
-        800,
-        0,
-        PayloadDigest25::default(),
-    );
-
-    println!(
-        "any_late_blog_area includes alfie_early_blog_entry: {:?}",
-        any_late_blog_area.includes_entry(&alfie_early_blog_entry)
-    );
-
-    println!(
-        "any_late_blog_area includes betty_late_blog_entry: {:?}",
-        any_late_blog_area.includes_entry(&betty_late_blog_entry)
-    );
-
-    let alfie_everything_area = Area::new(
-        AreaSubspace::Id(alfie_subspace),
-        Path::new_empty(),
-        Range::new_open(0),
-    );
-
-    println!(
-        "alfie_everything_area includes alfie_early_blog_entry: {:?}",
-        alfie_everything_area.includes_entry(&alfie_early_blog_entry)
-    );
-
-    println!(
-        "alfie_everything_area includes betty_late_blog_entry: {:?}",
-        alfie_everything_area.includes_entry(&betty_late_blog_entry)
-    );
-}
+    let namespace_id = NamespaceId::from([0; NAMESPACE_ID_WIDTH]);
+    let subspace_id = SubspaceId::from([1; SUBSPACE_ID_WIDTH]);
+
+    // Create an entry for comparisons, with a timestamp of 17.
+    let entry = Entry::builder()
+        .namespace_id(namespace_id.clone())
+        .subspace_id(subspace_id)
+        .path(path!("/"))
+        .timestamp(17)
+        .payload(b"bla")
+        .build()
+        .unwrap();
+
+    // Can create TimeRanges from arbitrary rust ranges of Timestamps.
+    assert!(entry.is_in(&TimeRange::from(5.into()..19.into())));
+    assert!(entry.is_in(&TimeRange::from(5.into()..)));
+    assert!(entry.is_in(&TimeRange::from(..19.into())));
+    assert!(entry.is_in(&TimeRange::from(5.into()..=17.into())));
+    assert!(entry.is_in(&TimeRange::from(..)));
+    assert!(!entry.is_in(&TimeRange::from(33.into()..)));
+
+    let intersection = TimeRange::from(..19.into())
+        .intersection(&TimeRange::from(5.into()..));
+    assert_eq!(intersection, TimeRange::from(5.into()..19.into()));
+    assert!(entry.is_in(&intersection));
+    assert!(entry.is_in_intersection(
+        &TimeRange::from(..19.into()),
+        &TimeRange::from(5.into()..),
+    ));
+
+    // Area
+    let alfie_subspace = SubspaceId::from([17; SUBSPACE_ID_WIDTH]);
+    let betty_subspace = SubspaceId::from([64; SUBSPACE_ID_WIDTH]);
+
+    let alfie_early_blog_entry = Entry::builder()
+        .namespace_id(namespace_id.clone())
+        .subspace_id(alfie_subspace.clone())
+        .path(path!("/blog/breakfast"))
+        .timestamp(100)
+        .payload(b"I made the most delicious pancakes today.")
+        .build()
+        .unwrap();
+
+    let betty_late_blog_entry = Entry::builder()
+        .namespace_id(namespace_id.clone())
+        .subspace_id(betty_subspace.clone())
+        .path(path!("/blog/dinner"))
+        .timestamp(800)
+        .payload(b"Salmon is great when you're low on time.")
+        .build()
+        .unwrap();
+
+    let late_time_range = TimeRange::from(500.into()..1000.into());
+    let any_late_blog_area = Area::new(None, path!("/blog"), late_time_range);
+
+    assert!(betty_late_blog_entry.is_in(&any_late_blog_area));
+    assert!(!alfie_early_blog_entry.is_in(&any_late_blog_area));
+
+    let alfie_all_area = Area::new(Some(alfie_subspace), path!("/blog"), TimeRange::full());
+
+    assert!(!betty_late_blog_entry.is_in(&alfie_all_area));
+    assert!(alfie_early_blog_entry.is_in(&alfie_all_area));
+}

src/code_samples/tut_grouping/01.rs

@@ -10,4 +10,4 @@ fn main() {
     let ideas_path = path.append_component(component1).unwrap();
     let ideas_game_path = ideas_path.append_component(component2).unwrap();
     println!("A path with two components: {:?}", ideas_game_path);
-}
+}