From c338c3f08c6a13242e975dd344bad63a3cec9eee Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Sun, 18 Aug 2024 20:00:21 -0400
Subject: Update docs

---
 api/sets.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 53 insertions(+), 3 deletions(-)

(limited to 'api/sets.md')

diff --git a/api/sets.md b/api/sets.md
index 7bcd4805..6dcc9ca9 100644
--- a/api/sets.md
+++ b/api/sets.md
@@ -10,11 +10,61 @@ b := {20, 30}
 = {20}
 ```
 
-Here’s the Markdown documentation for set functions:
+## Syntax
 
----
+Sets are written using `{}` curly braces with comma-separated items:
+
+```tomo
+nums := {10, 20, 30}
+```
+
+Empty sets must specify the item type explicitly:
+
+```tomo
+empty := {:Int}
+```
+
+For type annotations, a set that holds items with type `T` is written as `{T}`.
+
+### Comprehensions
+
+Similar to arrays, sets can use comprehensions:
+
+```tomo
+set := {10*i for i in 10}
+set2 := {10*i for i in 10 if i mod 2 == 0}
+set3 := {-10, 10*i for i in 10}
+```
+
+## Accessing Items
+
+Sets internally store their items in an array, which you can access with the
+`.items` field. This is a constant-time operation that produces an immutable
+view:
+
+```tomo
+set := {10, 20, 30}
+>> set.items
+= [10, 20, 30]
+```
+
+## Iteration
+
+You can iterate over the items in a table like this:
+
+```tomo
+for item in set:
+    ...
+
+for i, item in set:
+    ...
+```
+
+Set iteration operates over the value of the set when the loop began, so
+modifying the set during iteration is safe and will not result in the loop
+iterating over any of the new values.
 
-## Set Functions
+## Set Methods
 
 ### `has`
 
-- 
cgit v1.2.3