add a motivating case

+ Hopefully it generalizes well, but at least it does use both lifetime
  and ownership intermixed

1 files changed, 36 insertions, 0 deletions

diff --git a/README.md b/README.md
index 5aa4777..bbb4185 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,42 @@ fwd examples/uniq.fwd > /tmp/output.cpp
 g++ -Ilib -std=c++20 /tmp/output.cpp -o /tmp/output
 ```
 
+### Motivating case(s)
+
+As an example, let's consider a hashmap. In a regular return-oriented language,
+you could have four possibilities for inserting elements (assuming move
+semantics and everything being mutable):
+```
+/* (1) owning map, owning element */
+new_map = insert(map, element);
+
+/* (2) owning map, reference element */
+new_map = insert(map, &element);
+
+/* (3) reference map, owning element */
+insert(&map, element);
+
+/* (4) reference map, reference element */
+insert(&map, &element);
+```
+
+Of these, cases (1) and (3) is safe. The ownership of `element` is transferred
+to `map`, so the `element` stays alive as long as the `map`.
+(2) and (4) are unsafe, since they depend on how the map is used after the return of the
+function.
+
+However, what if the function doesn't return, but rather passes the map on to a
+closure? The cases (1) and (3) are effectively the same, but case (2) now
+becomes safe, since `new_map` is guaranteed to be destroyed before `insert`
+returns, and `&element` is owned by someone whose lifetime is longer than
+`insert` (unless some unsafe fuckery happens). (4) is still unsafe,
+*technically* speaking it would be safe to use within the closure that it calls
+but any code outside of that is effectively impossible to reason about. It could
+theoretically be considered safe if the element is removed after the closure
+exits, so the `&map` and `&element` are linked only within the function but not
+outside it, but I'm not entirely certain how that could be codified in the
+move semantics. Besides, at that point, I'm not sure there's a significant difference
+between (2) and (4) in practical applications, but more testing is needed.
 
 ## Current state