From 21f62ccc4408f99aea39c8221c98f53401f0eb43 Mon Sep 17 00:00:00 2001
From: Kristian Larsson <kristian@spritelink.net>
Date: Sat, 23 Sep 2023 16:40:17 +0200
Subject: [PATCH] AbE: improve sets & tuples docs

---
 docs/acton-by-example/src/primitives/sets.md  | 28 +++++++++++++------
 .../acton-by-example/src/primitives/tuples.md | 26 +++++++++++------
 2 files changed, 38 insertions(+), 16 deletions(-)

diff --git a/docs/acton-by-example/src/primitives/sets.md b/docs/acton-by-example/src/primitives/sets.md
index 19dea36a8..6adca7e4c 100644
--- a/docs/acton-by-example/src/primitives/sets.md
+++ b/docs/acton-by-example/src/primitives/sets.md
@@ -3,11 +3,19 @@
 Source:
 ```python
 actor main(env):
-    # Duplicate entries
-    s = {"foo", "foo"}
+    s = {"foo", "bar"}
+    print("Set content:", s)
+    if "foo" in s:
+        print("'foo' is in the set")
+    if "a" not in s:
+        print("'a' is not in the set")
+    # Adding an item that is already in the set does nothing
+    s.add("foo")
     print("Set without duplicate 'foo':", s)
-    s.add("bar")
-    print("Set after adding 'bar':", s)
+    s.add("a")
+    print("Set after adding 'a':", s)
+    if "a" in s:
+        print("'a' is in the set now")
     print("Entries in set:", len(s))
     s.discard("foo")
     print("Set after discarding 'foo':", s)
@@ -23,8 +31,12 @@ actonc sets.act
 
 Output:
 ```sh
-Set without duplicate 'foo': {"foo"}
-Set after adding 'bar': {"bar", "foo"}
-Entries in set: 2
-Set after discarding 'foo': {"bar"}
+Set content: {'bar', 'foo'}
+'foo' is in the set
+'a' is not in the set
+Set without duplicate 'foo': {'bar', 'foo'}
+Set after adding 'a': {'bar', 'a', 'foo'}
+'a' is in the set now
+Entries in set: 3
+Set after discarding 'foo': {'bar', 'a'}
 ```
diff --git a/docs/acton-by-example/src/primitives/tuples.md b/docs/acton-by-example/src/primitives/tuples.md
index 299d66fe6..76426534f 100644
--- a/docs/acton-by-example/src/primitives/tuples.md
+++ b/docs/acton-by-example/src/primitives/tuples.md
@@ -5,19 +5,28 @@ Source:
 actor main(env):
     # Items in a tuple can be of different types
     t = ("foo", 42)
-    # Items are accessed liked attributes on a object (this is so we can find 
-    # out type of items at compile time), not like the index in a list.
+    # Fields are accessed by their index and using field / attribute selection style:
     print(t)
     print(t.0)
     print(t.1)
     
-    # Named tuples
+    # Tuples can use named fields
     nt = (a="bar", b=1337)
     print(nt)
     print(nt.a)
     print(nt.b)
+    
+    r = foo()
+    # TODO: bool() should not be necessary
+    if bool(r.b):
+        print(r.c)
 
     await async env.exit(0)
+    
+def foo() -> (a: str, b: bool, c: int):
+    """A function that returns a tuple with fields name a and b
+    """
+    return (a = "hello", b=True, c=123)
 ```
 
 Compile and run:
@@ -28,15 +37,16 @@ actonc sets.act
 
 Output:
 ```sh
-("foo", 42)
+('foo', 42)
 foo
 42
-("bar", 1337)
+('bar', 1337)
 bar
 1337
+123
 ```
 
-- tuples allow storing multiple items in one variable
-- tuples are fixed length, unlike lists which can be appended and shortened
 - fields in a tuple can be of different types
-- named tuples are similar to records in other languages
+- tuples have a fixed fields
+- tuples with named fields is like an anonymous data class, i.e. the data type itself has no name
+- tuples with named fields can be used like a simple record type