From 7c9bae1867fd0df528ea80645855de00a4f4db76 Mon Sep 17 00:00:00 2001
From: Tyge Løvset <tylo@norceresearch.no>
Date: Mon, 8 Aug 2022 09:18:26 +0200
Subject: Improved carc example in docs.

---
 docs/carc_api.md | 93 ++++++++++++++++++++++++++------------------------------
 1 file changed, 43 insertions(+), 50 deletions(-)

(limited to 'docs')

diff --git a/docs/carc_api.md b/docs/carc_api.md
index 2604e13a..687e9547 100644
--- a/docs/carc_api.md
+++ b/docs/carc_api.md
@@ -65,102 +65,95 @@ bool        carc_X_value_eq(const i_val* x, const i_val* y);   // carc_X_value_c
 ## Example
 
 ```c
-// Create a stack and a list of shared pointers to maps,
-// and demonstrate sharing and cloning of maps.
+// Create two stacks with carcs to maps.
+// Demonstrate sharing and cloning of maps.
+// Show elements dropped.
 #include <stc/cstr.h>
 
 #define i_type Map
-#define i_key_str // strings
-#define i_val int
+#define i_key_str // i_key: cstr, i_keydrop: cstr_drop, etc..
+#define i_val int // year
+// override cstr_drop(p) by defining i_keydrop:
 #define i_keydrop(p) (printf("  drop name: %s\n", cstr_str(p)), cstr_drop(p))
 #include <stc/csmap.h>
 
-#define i_type Arc // (atomic) ref. counted type
+#define i_type Arc // (atomic) ref. counted pointer
 #define i_val Map
 #define i_valclone Map_clone
+// override Map_drop(p):
 #define i_valdrop(p) (printf("drop Arc:\n"), Map_drop(p))
-// no comparison of Maps needed (or available), and
-// no need for atomic ref. count in single thread:
-#define i_opt c_no_cmp|c_no_atomic
+#define i_opt c_no_cmp|c_no_atomic // make it non-atomic sharing.
 #include <stc/carc.h>
 
 #define i_type Stack
-#define i_val_arcbox Arc // note: define i_val_arcbox for carc/cbox value
+#define i_val_arcbox Arc // NB: define i_val_arcbox for carc or cbox value-type
 #include <stc/cstack.h>
 
-#define i_type List
-#define i_val_arcbox Arc // as above
-#include <stc/clist.h>
-
 int main()
 {
-    c_auto (Stack, stack)
-    c_auto (List, list)
+    c_auto (Stack, s1, s2) // RAII
     {
-        // POPULATE the stack with shared pointers to Map:
+        // POPULATE s1 with shared pointers to Map:
         Map *map;
-        map = Stack_push(&stack, Arc_make(Map_init()))->get;
-        c_forarray (Map_raw, v, {
-            {"Joey", 1990},
-            {"Mary", 1995},
-            {"Joanna", 1992},
-        }) Map_emplace(map, v->first, v->second);
-
-        map = Stack_push(&stack, Arc_make(Map_init()))->get;
-        c_forarray (Map_raw, v, {
-            {"Rosanna", 2001},
-            {"Brad", 1999},
-            {"Jack", 1980}
-        }) Map_emplace(map, v->first, v->second);
-
-        // POPULATE the list:
-        map = List_push_back(&list, Arc_make(Map_init()))->get;
-        c_forarray (Map_raw, v, {
-            {"Steve", 1979},
-            {"Rick", 1974},
-            {"Tracy", 2003}
-        }) Map_emplace(map, v->first, v->second);
+
+        map = Stack_push(&s1, Arc_make(Map_init()))->get; // push empty map to s1.
+        c_forarray (Map_raw, v, { {"Joey", 1990}, {"Mary", 1995}, {"Joanna", 1992}}) {
+            Map_emplace(map, v->first, v->second); // populate it.
+        }
+
+        map = Stack_push(&s1, Arc_make(Map_init()))->get;
+        c_forarray (Map_raw, v, { {"Rosanna", 2001}, {"Brad", 1999}, {"Jack", 1980} }) {
+            Map_emplace(map, v->first, v->second);
+        }
+
+        // POPULATE s2:
+        map = Stack_push(&s2, Arc_make(Map_init()))->get;
+        c_forarray (Map_raw, v, { {"Steve", 1979}, {"Rick", 1974}, {"Tracy", 2003} }) {
+            Map_emplace(map, v->first, v->second);
+        }
         
-        // Share two Maps from the stack with the list by cloning(=sharing) the carc:
-        List_push_back(&list, Arc_clone(stack.data[0]));
-        List_push_back(&list, Arc_clone(stack.data[1]));
+        // Share two Maps from s1 with s2 by cloning(=sharing) the carcs:
+        Stack_push(&s2, Arc_clone(s1.data[0]));
+        Stack_push(&s2, Arc_clone(s1.data[1]));
         
-        // Deep-copy (not share) a Map from the stack to the list
-        // List will contain two shared and two unshared maps.
-        map = List_push_back(&list, Arc_make(Map_clone(*stack.data[1].get)))->get;
+        // Deep-copy (does not share) a Map from s1 to s2.
+        // s2 will contain two shared and two unshared maps.
+        map = Stack_push(&s2, Arc_make(Map_clone(*s1.data[1].get)))->get;
         
         // Add one more element to the cloned map:
         Map_emplace_or_assign(map, "Cloned", 2022);
 
         // Add one more element to the shared map:
-        Map_emplace_or_assign(stack.data[1].get, "Shared", 2022);
+        Map_emplace_or_assign(s1.data[1].get, "Shared", 2022);
 
-        puts("STACKS");
-        c_foreach (i, Stack, stack) {
+        puts("S1");
+        c_foreach (i, Stack, s1) {
             c_forpair (name, year, Map, *i.ref->get)
                 printf("  %s:%d", cstr_str(_.name), *_.year);
             puts("");
         }
 
-        puts("LIST");
-        c_foreach (i, List, list) {
+        puts("S2");
+        c_foreach (i, Stack, s2) {
             c_forpair (name, year, Map, *i.ref->get)
                 printf("  %s:%d", cstr_str(_.name), *_.year);
             puts("");
         }
+        puts("");
     }
 }
 ```
 Output:
 ```
-STACKS
+S1
   Joanna:1992  Joey:1990  Mary:1995
   Brad:1999  Jack:1980  Rosanna:2001  Shared:2022
-LIST
+S2
   Rick:1974  Steve:1979  Tracy:2003
   Joanna:1992  Joey:1990  Mary:1995
   Brad:1999  Jack:1980  Rosanna:2001  Shared:2022
   Brad:1999  Cloned:2022  Jack:1980  Rosanna:2001
+
 drop Arc:
   drop name: Rick
   drop name: Tracy
-- 
cgit v1.2.3