From 61ab6eef25d3b255834156d615bf1ad112e1a3c3 Mon Sep 17 00:00:00 2001
From: Colin Leach <colin.leach@omcast.net>
Date: Sat, 12 Oct 2024 14:49:50 -0700
Subject: [PATCH 1/2] WIP draft of sets concept

---
 concepts.wip/sets/.meta/config.json |   7 ++
 concepts.wip/sets/about.md          | 115 ++++++++++++++++++++++++++++
 concepts.wip/sets/introduction.md   |   1 +
 concepts.wip/sets/links.json        |   6 ++
 4 files changed, 129 insertions(+)
 create mode 100644 concepts.wip/sets/.meta/config.json
 create mode 100644 concepts.wip/sets/about.md
 create mode 100644 concepts.wip/sets/introduction.md
 create mode 100644 concepts.wip/sets/links.json

diff --git a/concepts.wip/sets/.meta/config.json b/concepts.wip/sets/.meta/config.json
new file mode 100644
index 00000000..e4885339
--- /dev/null
+++ b/concepts.wip/sets/.meta/config.json
@@ -0,0 +1,7 @@
+{
+  "authors": [
+    "colinleach"
+  ],
+  "contributors": [],
+  "blurb": "A Set in Julia is an unordered collection of unique entries, with fast algorithms for contains, union, intersection and difference operations."
+}
diff --git a/concepts.wip/sets/about.md b/concepts.wip/sets/about.md
new file mode 100644
index 00000000..30a7c05b
--- /dev/null
+++ b/concepts.wip/sets/about.md
@@ -0,0 +1,115 @@
+# About
+
+A [`Set`][set] is a collection of items with the following properties:
+
+- Unordered.
+- Entries are unique, so attempts to add duplicates are silently ignored.
+- Supports many of the operations common with mathematical sets.
+
+Create them with the `Set()` constructor, using any iterator as the parameter.
+
+```julia-repl
+julia> s1 = Set(1:4)
+Set{Int64} with 4 elements:
+  4
+  2
+  3
+  1
+```
+
+Add new elements with `push!()` (the same as with arrays), and remove them with `delete!()`.
+
+```julia-repl
+julia> push!(s1, 5)
+Set{Int64} with 5 elements:
+  5
+  4
+  2
+  3
+  1
+
+# Duplicates are ignored
+julia> push!(s1, 3)
+Set{Int64} with 5 elements:
+  5
+  4
+  2
+  3
+  1
+
+julia> delete!(s1, 5)
+Set{Int64} with 4 elements:
+  4
+  2
+  3
+  1
+
+julia> length(s1)  # length counts entries, despite the non-sequential type
+4
+```
+
+## Set operations
+
+As with several other collection types, check membership with the `in` or `∈` operator (use `\in` then tab for the symbol).
+
+```julia-repl
+julia> 3 ∈ s1
+true
+```
+
+The following operations on pairs of Sets are supported (shortcuts to the operator symbol are shown in parentheses).
+
+- `union(A, B)` or `A ∪ B` (`\cup`): all entries in A or B or both.
+- `intersect(A, B)` or `A ∩ B` (`\cap`): all entries common to both A _and_ B.
+- `setdiff(A, B)` (no symbol): entries in A but not in B.
+- `symdiff(A, B)` (no symbol): entries in either A or B but not both.
+- `issubset(A, B)` or `A ⊆ B` (`\subseteq`) or `B ⊇ A` (`\supseteq`): `true` if all entries in A are also in B.
+- `issetequal(A, B)` (no symbol): `true` if A and B contain exactly the same entries.
+- `isdisjoint(A, B)` (no symbol): `true` if A and B contain no entries in common (so intersect is empty).
+
+```julia-repl
+s1 = Set(1:4)
+s2 = Set(3:6)
+
+julia> s1 ∪ s2  # union
+Set{Int64} with 6 elements:
+  5
+  4
+  6
+  2
+  3
+  1
+
+julia> s1 ∩ s2  # intersect
+Set{Int64} with 2 elements:
+  4
+  3
+  
+julia> setdiff(s1, s2)
+Set{Int64} with 2 elements:
+  2
+  1
+
+julia> symdiff(s1, s2)
+Set{Int64} with 4 elements:
+  5
+  6
+  2
+  1
+  
+julia> s1 ⊇ s2  # issubset
+false
+```
+
+There are also mutating versions of many of these, with `!` added to the function name.
+See the [manual][set] for a full list of functions.
+
+
+[set]: https://docs.julialang.org/en/v1/base/collections/#Set-Like-Collections
+[union]: https://docs.julialang.org/en/v1/base/collections/#Base.union
+[intersect]: https://docs.julialang.org/en/v1/base/collections/#Base.intersect
+[setdiff]: https://docs.julialang.org/en/v1/base/collections/#Base.setdiff
+[symdiff]: https://docs.julialang.org/en/v1/base/collections/#Base.symdiff
+[issubset]: https://docs.julialang.org/en/v1/base/collections/#Base.issubset
+[issetequal]: https://docs.julialang.org/en/v1/base/collections/#Base.issetequal
+[isdisjoint]: https://docs.julialang.org/en/v1/base/collections/#Base.isdisjoint
diff --git a/concepts.wip/sets/introduction.md b/concepts.wip/sets/introduction.md
new file mode 100644
index 00000000..e10b99d0
--- /dev/null
+++ b/concepts.wip/sets/introduction.md
@@ -0,0 +1 @@
+# Introduction
diff --git a/concepts.wip/sets/links.json b/concepts.wip/sets/links.json
new file mode 100644
index 00000000..759dcb29
--- /dev/null
+++ b/concepts.wip/sets/links.json
@@ -0,0 +1,6 @@
+[
+  {
+    "url": "https://docs.julialang.org/en/v1/base/collections/#Set-Like-Collections",
+    "description": "Manual section on Sets and related collections."
+  }
+]

From 2e86fdc489e8be23847a26d3071acfa1ddc8690c Mon Sep 17 00:00:00 2001
From: Colin Leach <colin.leach@omcast.net>
Date: Sun, 13 Oct 2024 08:07:50 -0700
Subject: [PATCH 2/2] removed italics

---
 concepts.wip/sets/about.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/concepts.wip/sets/about.md b/concepts.wip/sets/about.md
index 30a7c05b..a49b0c61 100644
--- a/concepts.wip/sets/about.md
+++ b/concepts.wip/sets/about.md
@@ -60,7 +60,7 @@ true
 The following operations on pairs of Sets are supported (shortcuts to the operator symbol are shown in parentheses).
 
 - `union(A, B)` or `A ∪ B` (`\cup`): all entries in A or B or both.
-- `intersect(A, B)` or `A ∩ B` (`\cap`): all entries common to both A _and_ B.
+- `intersect(A, B)` or `A ∩ B` (`\cap`): all entries common to both A and B.
 - `setdiff(A, B)` (no symbol): entries in A but not in B.
 - `symdiff(A, B)` (no symbol): entries in either A or B but not both.
 - `issubset(A, B)` or `A ⊆ B` (`\subseteq`) or `B ⊇ A` (`\supseteq`): `true` if all entries in A are also in B.