Merge pull request #31 from orxfun/no-std-support

no-std-support

Author: orxfun

Cargo.toml

@@ -1,16 +1,16 @@
 [package]
 name = "orx-imp-vec"
-version = "2.6.0"
+version = "2.7.0"
 edition = "2021"
 authors = ["orxfun <orx.ugur.arikan@gmail.com>"]
-description = "`ImpVec`, standing for immutable push vector 👿, is a data structure which allows appending elements with a shared reference."
+description = "`ImpVec`, stands for immutable push vector 👿, is a data structure which allows appending elements with a shared reference."
 license = "MIT"
 repository = "https://github.com/orxfun/orx-imp-vec/"
 keywords = ["vec", "pinned", "bag", "container", "split"]
-categories = ["data-structures", "rust-patterns"]
+categories = ["data-structures", "rust-patterns", "no-std"]
 
 [dependencies]
-orx-pseudo-default = "1.2"
-orx-pinned-vec = "3.3"
-orx-fixed-vec = "3.3"
-orx-split-vec = "3.3"
+orx-pseudo-default = { version = "1.4", default-features = false }
+orx-pinned-vec = "3.9"
+orx-fixed-vec = "3.9"
+orx-split-vec = "3.9"

README.md

@@ -3,21 +3,201 @@
 [![orx-imp-vec crate](https://img.shields.io/crates/v/orx-imp-vec.svg)](https://crates.io/crates/orx-imp-vec)
 [![orx-imp-vec documentation](https://docs.rs/orx-imp-vec/badge.svg)](https://docs.rs/orx-imp-vec)
 
-`ImpVec`, standing for immutable push vector 👿, is a data structure which allows appending elements with a shared reference.
+`ImpVec`, stands for immutable push vector 👿, is a data structure which allows appending elements with a shared reference.
 
 Specifically, it extends vector capabilities with the following two methods:
-* `fn imp_push(&self, value: T)`
-* `fn imp_extend_from_slice(&self, slice: &[T])`
+* [`fn imp_push(&self, value: T)`](https://docs.rs/orx-imp-vec/latest/orx_imp_vec/struct.ImpVec.html#method.imp_push)
+* [`fn imp_extend_from_slice(&self, slice: &[T])`](https://docs.rs/orx-imp-vec/latest/orx_imp_vec/struct.ImpVec.html#method.imp_extend_from_slice)
 
 Note that both of these methods can be called with `&self` rather than `&mut self`.
 
-# Motivation
+## Motivation
 
-Appending to a vector with a shared reference sounds unconventional, and it is. However, if we consider our vector as a bag of or a container of things rather than having a collective meaning; then, appending element or elements to the end of the vector:
-* does not mutate any of already added elements, and hence,
-* **it is not different than creating a new element in the scope**.
+Appending to a vector with a shared reference sounds unconventional, and it is.
 
-# Safety
+From another perspective, however, appending an element to the end of the vector does not mutate any of already added elements or change their positions. It can be argued that *it is not different than creating a new element within the scope*. This statement will be clear with the following example.
+
+The challenge is to define a type-safe, recursive and expressive expression builder. In our toy example, an expression can either be a symbol, or addition or subtraction of two expressions. The final desired ergonomic solution is as follows:
+
+```rust ignore
+let scope = Scope::default();
+
+// instantiate some symbols
+let x = scope.symbol("x");
+let y = scope.symbol("y");
+assert_eq!(&x.to_string(), "x");
+assert_eq!(&y.to_string(), "y");
+
+// apply binary operations to create new symbols
+let p = x + y;
+assert_eq!(&p.to_string(), "x + y");
+
+let q = x - y;
+assert_eq!(&q.to_string(), "x - y");
+
+// and further binary operations
+let t = p + q;
+assert_eq!(&t.to_string(), "x + y + x - y");
+
+// we only use 'scope' to create symbols
+// but in the background, all expressions are collected in our scope
+let all_expressions: Vec<_> = scope.expressions.iter().map(|x| x.to_string()).collect();
+assert_eq!(
+    all_expressions,
+    ["x", "y", "x + y", "x - y", "x + y + x - y"]
+);
+```
+
+This at first seemed **impossible in safe rust** for way too many reasons. However, it is conveniently possible using an `ImpVec`. You may run the example in [expressions.rs](https://github.com/orxfun/orx-imp-vec/blob/main/examples/expressions.rs) by `cargo run --example expressions`, or see the details of the implementation below.
+
+<details>
+<summary style="font-weight:bold;">Complete Implementation</summary>
+
+```rust
+use orx_imp_vec::*;
+use std::{
+    fmt::Display,
+    ops::{Add, Sub},
+};
+
+/// A scope for expressions.
+#[derive(Default)]
+struct Scope<'a> {
+    expressions: ImpVec<Expr<'a>>,
+}
+
+impl<'a> Scope<'a> {
+    /// Bottom of the expressions recursion, the symbol primitive
+    fn symbol(&'a self, name: &'static str) -> ExprInScope<'a> {
+        let expr = Expr::Symbol(name);
+        self.expressions.imp_push(expr);
+        ExprInScope {
+            scope: self,
+            expr: &self.expressions[self.expressions.len() - 1],
+        }
+    }
+}
+
+/// A recursive expression with three demo variants
+enum Expr<'a> {
+    Symbol(&'static str),
+    Addition(&'a Expr<'a>, &'a Expr<'a>),
+    Subtraction(&'a Expr<'a>, &'a Expr<'a>),
+}
+
+impl<'a> Display for Expr<'a> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Expr::Symbol(x) => write!(f, "{}", x),
+            Expr::Addition(x, y) => write!(f, "{} + {}", x, y),
+            Expr::Subtraction(x, y) => write!(f, "{} - {}", x, y),
+        }
+    }
+}
+
+/// Expression in a scope:
+/// * it knows what it is
+/// * it knows which scope it belongs to
+///
+/// It can implement Copy which turns out to be extremely important!
+#[derive(Clone, Copy)]
+struct ExprInScope<'a> {
+    scope: &'a Scope<'a>,
+    expr: &'a Expr<'a>,
+}
+
+impl<'a> ExprInScope<'a> {
+    /// Recall, it knows that scope it belongs to,
+    /// and can check it in O(1)
+    fn belongs_to_same_scope(&self, other: Self) -> bool {
+        let self_scope = self.scope as *const Scope;
+        let other_scope = other.scope as *const Scope;
+        self_scope == other_scope
+    }
+}
+impl<'a> Display for ExprInScope<'a> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.expr)
+    }
+}
+
+impl<'a> Add for ExprInScope<'a> {
+    type Output = ExprInScope<'a>;
+
+    /// We can create an expression by adding two expressions
+    ///
+    /// Where do we store the new expression?
+    ///
+    /// Of course, in the scope that both expressions belong to.
+    /// And we can do so by `imp_push`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the lhs & rhs do not belong to the same scope.
+    fn add(self, rhs: Self) -> Self::Output {
+        assert!(self.belongs_to_same_scope(rhs));
+        let expressions = &self.scope.expressions;
+        let expr = Expr::Addition(self.expr, rhs.expr);
+        expressions.imp_push(expr);
+        ExprInScope {
+            scope: self.scope,
+            expr: &expressions[expressions.len() - 1],
+        }
+    }
+}
+
+impl<'a> Sub for ExprInScope<'a> {
+    type Output = ExprInScope<'a>;
+
+    /// Similarly, we can create an expression by subtracting two expressions
+    /// 
+    /// # Panics
+    ///
+    /// Panics if the lhs & rhs do not belong to the same scope.
+    fn sub(self, rhs: Self) -> Self::Output {
+        assert!(self.belongs_to_same_scope(rhs));
+        let expressions = &self.scope.expressions;
+        let expr = Expr::Subtraction(self.expr, rhs.expr);
+        expressions.imp_push(expr);
+        ExprInScope {
+            scope: self.scope,
+            expr: &expressions[expressions.len() - 1],
+        }
+    }
+}
+
+let scope = Scope::default();
+
+// instantiate some symbols
+let x = scope.symbol("x");
+let y = scope.symbol("y");
+assert_eq!(&x.to_string(), "x");
+assert_eq!(&y.to_string(), "y");
+
+// apply binary operations to create new symbols
+let p = x + y;
+assert_eq!(&p.to_string(), "x + y");
+
+let q = x - y;
+assert_eq!(&q.to_string(), "x - y");
+
+// and further binary operations
+let t = p + q;
+assert_eq!(&t.to_string(), "x + y + x - y");
+
+// we only use 'scope' to create symbols
+// but in the background, all expressions are collected in our scope
+let all_expressions: Vec<_> = scope.expressions.iter().map(|x| x.to_string()).collect();
+assert_eq!(
+    all_expressions,
+    ["x", "y", "x + y", "x - y", "x + y + x - y"]
+);
+```
+
+</details>
+
+
+## Safety
 
 It is natural to expect that appending elements to a vector does not affect already added elements. However, this is usually not the case due to underlying memory management. For instance, `std::vec::Vec` may move already added elements to different memory locations to maintain the contagious layout of the vector. 
 
@@ -37,10 +217,10 @@ vec.push(4);
 // assert_eq!(ref_to_first, &0);
 ```
 
-This beloved feature of the borrow checker of rust is not required and used for `imp_push` and `imp_extend_from_slice` methods of `ImpVec` since these methods do not require a `&mut self` reference. Therefore, the following code compiles and runs perfectly safely.
+This beloved feature of the borrow checker of rust is not required for `imp_push` and `imp_extend_from_slice` methods of `ImpVec` since these methods do not require a `&mut self` reference. Therefore, the following code compiles and runs perfectly safely.
 
 ```rust
-use orx_imp_vec::prelude::*;
+use orx_imp_vec::*;
 
 let mut vec = ImpVec::new();
 vec.extend_from_slice(&[0, 1, 2, 3]);

examples/bag_of_things.rs

@@ -0,0 +1,80 @@
+use orx_imp_vec::*;
+
+#[derive(Default)]
+struct Bag {
+    things: ImpVec<Thing>,
+}
+
+impl Bag {
+    fn push_thing(&self, name: &str) -> ThingInBag {
+        self.things.imp_push(Thing {
+            name: name.to_string(),
+        });
+        ThingInBag {
+            bag: self,
+            thing: &self.things[self.things.len() - 1],
+        }
+    }
+
+    fn things(&self) -> Vec<&str> {
+        self.things.iter().map(|x| x.name.as_str()).collect()
+    }
+}
+
+struct Thing {
+    name: String,
+}
+
+#[derive(Clone, Copy)]
+struct ThingInBag<'a> {
+    thing: &'a Thing,
+    bag: &'a Bag,
+}
+impl<'a> ThingInBag<'a> {
+    fn push_thing_in_same_bag(&self, name: &str) -> ThingInBag {
+        self.bag.push_thing(name)
+    }
+
+    fn is_in_bag(&self, bag: &Bag) -> bool {
+        let self_bag = self.bag as *const Bag;
+        let other_bag = bag as *const Bag;
+        self_bag == other_bag
+    }
+}
+impl<'a> PartialEq for ThingInBag<'a> {
+    fn eq(&self, other: &Self) -> bool {
+        let same_bag = self.bag as *const Bag == other.bag as *const Bag;
+        let same_thing = self.thing as *const Thing == other.thing as *const Thing;
+        same_bag && same_thing
+    }
+}
+
+fn main() {
+    // create a bag
+    let bag = Bag::default();
+
+    // add things and collect things in bag
+    let pen = bag.push_thing("pen");
+    let cup = bag.push_thing("cup");
+    assert_eq!(bag.things(), ["pen", "cup"]);
+
+    // add new things to bag using existing things in bag
+    pen.push_thing_in_same_bag("pencil");
+    cup.push_thing_in_same_bag("cupcake");
+    assert_eq!(bag.things(), ["pen", "cup", "pencil", "cupcake"]);
+
+    // create another bag
+    let other_bag = Bag::default();
+    let key = other_bag.push_thing("key");
+    let other_pen = other_bag.push_thing("pen");
+
+    // check if things belong to the same bag in constant time
+    assert_eq!(pen.is_in_bag(&bag), true);
+    assert_eq!(pen.is_in_bag(&other_bag), false);
+
+    assert_eq!(key.is_in_bag(&bag), false);
+    assert_eq!(key.is_in_bag(&other_bag), true);
+
+    // use referential equality to compare if two things are the same
+    assert!(pen != other_pen);
+}