update some docs

Author: devries

src/internal/disjoint_set.gleam

@@ -1,10 +1,13 @@
 import gleam/dict
 import gleam/list
+import gleam/pair
 
 pub opaque type DisjointSet(a) {
   DisjointSet(parents: dict.Dict(a, a), sizes: dict.Dict(a, Int))
 }
 
+/// Create a disjoint set from a list of items. Initially all items are
+/// separate sets.
 pub fn from_list(items: List(a)) -> DisjointSet(a) {
   let #(parents, sizes) =
     list.fold(items, #(dict.new(), dict.new()), fn(acc, item) {
@@ -13,6 +16,9 @@ pub fn from_list(items: List(a)) -> DisjointSet(a) {
   DisjointSet(parents:, sizes:)
 }
 
+/// Find the set to which an item belogs. This will return an updated
+/// copy of the disjoint set with some path optimization and the root
+/// element defining the set.
 pub fn find(dj: DisjointSet(a), item: a) -> Result(#(DisjointSet(a), a), Nil) {
   case dict.get(dj.parents, item) {
     Ok(parent) -> {
@@ -22,13 +28,13 @@ pub fn find(dj: DisjointSet(a), item: a) -> Result(#(DisjointSet(a), a), Nil) {
           // Path compression to make each item point to a single representative set parent
           case find(dj, parent) {
             Error(_) -> Error(Nil)
-            Ok(#(dj, rep_parent)) -> {
+            Ok(#(dj, root)) -> {
               let updated_dj =
                 DisjointSet(
-                  parents: dict.insert(dj.parents, item, rep_parent),
+                  parents: dict.insert(dj.parents, item, root),
                   sizes: dj.sizes,
                 )
-              Ok(#(updated_dj, rep_parent))
+              Ok(#(updated_dj, root))
             }
           }
         }
@@ -38,6 +44,10 @@ pub fn find(dj: DisjointSet(a), item: a) -> Result(#(DisjointSet(a), a), Nil) {
   }
 }
 
+/// Create a union set from the set containing the element x
+/// and the set containing the element y. If they are already
+/// in the same set nothing happens. This returns an updated
+/// disjoint set.
 pub fn union(dj: DisjointSet(a), x: a, y: a) -> Result(DisjointSet(a), Nil) {
   case find(dj, x) {
     Error(Nil) -> Error(Nil)
@@ -67,13 +77,15 @@ pub fn union(dj: DisjointSet(a), x: a, y: a) -> Result(DisjointSet(a), Nil) {
   }
 }
 
+/// Find the size of the set which contains item.
 pub fn size(dj: DisjointSet(a), item: a) -> Result(Int, Nil) {
   case find(dj, item) {
     Error(Nil) -> Error(Nil)
     Ok(#(dj, rep_parent)) -> dict.get(dj.sizes, rep_parent)
   }
 }
 
+// I am thinking about just providing all sets
 pub fn to_list(dj: DisjointSet(a), item: a) -> Result(List(a), Nil) {
   case find(dj, item) {
     Error(Nil) -> Error(Nil)
@@ -91,11 +103,7 @@ pub fn to_list(dj: DisjointSet(a), item: a) -> Result(List(a), Nil) {
 }
 
 pub fn setlist(dj: DisjointSet(a)) -> List(a) {
-  dict.keys(dj.parents)
-  |> list.filter(fn(item) {
-    case find(dj, item) {
-      Ok(#(_, p)) if p == item -> True
-      _ -> False
-    }
-  })
+  dict.to_list(dj.parents)
+  |> list.filter(fn(pair) { pair.0 == pair.1 })
+  |> list.map(pair.first)
 }

src/internal/memoize.gleam

@@ -1,19 +1,20 @@
+//// Memoization in Gleam threw me for a loop, but an actor can hold
+//// the information I need. Below are the building blocks of an
+//// actor that holds a dict with a stone number and generations as
+//// a key, and the total count of stones will be descended from it
+//// after than many generations.
+
 import gleam/dict.{type Dict}
 import gleam/erlang/process.{type Subject}
 import gleam/otp/actor
 
-// Memoization in Gleam threw me for a loop, but an actor can hold
-// the information I need. Below are the building blocks of an
-// actor that holds a dict with a stone number and generations as
-// a key, and the total count of stones will be descended from it
-// after than many generations.
-
 pub type Message(a, b) {
   Put(key: a, value: b)
   Get(reply_with: Subject(Result(b, Nil)), key: a)
   Shutdown
 }
 
+/// A memoization cache. The state is held in an actor.
 pub type Cache(a, b) =
   Subject(Message(a, b))
 
@@ -28,12 +29,16 @@ pub fn handle_message(current: Dict(a, b), message: Message(a, b)) {
   }
 }
 
-// To check a cache first for a result first, before the rest of the function
-// runs add
-//    use <- cache_check(cache, #(param1, param2, ...))
-// It will look up those parameters in the cache and return a value if found.
-// otherwise it continues with the function and records the response for those
-// parameters.
+/// To check a cache first for a result first, before the rest of the function
+/// runs add
+///
+/// ```gleam
+/// use <- cache_check(cache, #(param1, param2, ...))
+/// ```
+/// 
+/// It will look up those parameters in the cache and return a value if found.
+/// otherwise it continues with the function and records the response for those
+/// parameters.
 pub fn cache_check(cache: Cache(a, b), key: a, callback: fn() -> b) -> b {
   let cache_result = process.call(cache, 100, Get(_, key))
 
@@ -60,10 +65,14 @@ pub fn cache_shutdown(cache: Cache(a, b)) {
   process.send(cache, Shutdown)
 }
 
-// To initialize a cache for the rest of a function, add
-//     use cache <- with_cache()
-// to the function. The rest of the function is a callback
-// with an actor holding the cache.
+/// To initialize a cache for the rest of a function, add
+///
+/// ```gleam
+/// use cache <- with_cache()
+/// ```
+/// 
+/// to the function. The rest of the function is a callback
+/// with an actor holding the cache.
 pub fn with_cache(callback: fn(Cache(a, b)) -> c) -> c {
   let cache = cache_init()