Update docs

8 files changed, 424 insertions, 0 deletions

diff --git a/CHANGES.md b/CHANGES.md
index 8f5704e0..95458289 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -24,6 +24,8 @@
 - Struct fields that start with underscores can be accessed again and function
   arguments that start with underscore can be passed (but only as keyword
   arguments).
+- Added `table.with(other)`, `table.without(other)`,
+  `table.intersection(other)`, and `table.difference(other)`.
 - Added a `--format` flag to the `tomo` binary that autoformats your code
   (currently unstable, do not rely on it just yet).
 - Standardized text methods for Unicode encodings:
diff --git a/api/api.md b/api/api.md
index 42f09ef4..f192c629 100644
--- a/api/api.md
+++ b/api/api.md
@@ -3623,6 +3623,29 @@ t | `&{K:V}` | The reference to the table.  | -
 >> t.clear()
 
 ```
+## Table.difference
+
+```tomo
+Table.difference : func(t: {K:V}, other: {K:V} -> {K:V})
+```
+
+Return a table whose key/value pairs correspond to keys only present in one table, but not the other.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+t | `{K:V}` | The base table.  | -
+other | `{K:V}` | The other table.  | -
+
+**Return:** A table containing the common key/value pairs whose keys only appear in one table.
+
+
+**Example:**
+```tomo
+t1 := {"A": 1; "B": 2, "C": 3}
+t2 := {"B": 2, "C":30, "D": 40}
+assert t1.difference(t2) == {"A": 1, "D": 40}
+
+```
 ## Table.get
 
 ```tomo
@@ -3715,6 +3738,29 @@ key | `K` | The key to check for presence.  | -
 = no
 
 ```
+## Table.intersection
+
+```tomo
+Table.intersection : func(t: {K:V}, other: {K:V} -> {K:V})
+```
+
+Return a table with only the matching key/value pairs that are common to both tables.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+t | `{K:V}` | The base table.  | -
+other | `{K:V}` | The other table.  | -
+
+**Return:** A table containing the common key/value pairs shared between two tables.
+
+
+**Example:**
+```tomo
+t1 := {"A": 1; "B": 2, "C": 3}
+t2 := {"B": 2, "C":30, "D": 40}
+assert t1.intersection(t2) == {"B": 2}
+
+```
 ## Table.remove
 
 ```tomo
@@ -3764,6 +3810,28 @@ t.set("C", 3)
 = {"A": 1, "B": 2, "C": 3}
 
 ```
+## Table.with
+
+```tomo
+Table.with : func(t: {K:V}, other: {K:V} -> {K:V})
+```
+
+Return a copy of a table with values added from another table
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+t | `{K:V}` | The base table.  | -
+other | `{K:V}` | The other table from which new key/value pairs will be added.  | -
+
+**Return:** The original table, but with values from the other table added.
+
+
+**Example:**
+```tomo
+t := {"A": 1; "B": 2}
+assert t.with({"B": 20, "C": 30}) == {"A": 1, "B": 20, "C": 30}
+
+```
 ## Table.with_fallback
 
 ```tomo
@@ -3791,6 +3859,30 @@ t3 = t.with_fallback(none)
 = none
 
 ```
+## Table.without
+
+```tomo
+Table.without : func(t: {K:V}, other: {K:V} -> {K:V})
+```
+
+Return a copy of a table, but without any of the exact key/value pairs found in the other table.
+
+Only exact key/value pairs will be discarded. Keys with a non-matching value will be kept.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+t | `{K:V}` | The base table.  | -
+other | `{K:V}` | The other table whose key/value pairs will be omitted.  | -
+
+**Return:** The original table, but without the key/value pairs from the other table.
+
+
+**Example:**
+```tomo
+t := {"A": 1; "B": 2, "C": 3}
+assert t.without({"B": 2, "C": 30, "D": 40}) == {"A": 1, "C": 3}
+
+```
 
 # Text
 ## Text.as_c_string
diff --git a/api/tables.md b/api/tables.md
index b4c98c57..1d8490db 100644
--- a/api/tables.md
+++ b/api/tables.md
@@ -23,6 +23,29 @@ t | `&{K:V}` | The reference to the table.  | -
 >> t.clear()
 
 ```
+## Table.difference
+
+```tomo
+Table.difference : func(t: {K:V}, other: {K:V} -> {K:V})
+```
+
+Return a table whose key/value pairs correspond to keys only present in one table, but not the other.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+t | `{K:V}` | The base table.  | -
+other | `{K:V}` | The other table.  | -
+
+**Return:** A table containing the common key/value pairs whose keys only appear in one table.
+
+
+**Example:**
+```tomo
+t1 := {"A": 1; "B": 2, "C": 3}
+t2 := {"B": 2, "C":30, "D": 40}
+assert t1.difference(t2) == {"A": 1, "D": 40}
+
+```
 ## Table.get
 
 ```tomo
@@ -115,6 +138,29 @@ key | `K` | The key to check for presence.  | -
 = no
 
 ```
+## Table.intersection
+
+```tomo
+Table.intersection : func(t: {K:V}, other: {K:V} -> {K:V})
+```
+
+Return a table with only the matching key/value pairs that are common to both tables.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+t | `{K:V}` | The base table.  | -
+other | `{K:V}` | The other table.  | -
+
+**Return:** A table containing the common key/value pairs shared between two tables.
+
+
+**Example:**
+```tomo
+t1 := {"A": 1; "B": 2, "C": 3}
+t2 := {"B": 2, "C":30, "D": 40}
+assert t1.intersection(t2) == {"B": 2}
+
+```
 ## Table.remove
 
 ```tomo
@@ -164,6 +210,28 @@ t.set("C", 3)
 = {"A": 1, "B": 2, "C": 3}
 
 ```
+## Table.with
+
+```tomo
+Table.with : func(t: {K:V}, other: {K:V} -> {K:V})
+```
+
+Return a copy of a table with values added from another table
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+t | `{K:V}` | The base table.  | -
+other | `{K:V}` | The other table from which new key/value pairs will be added.  | -
+
+**Return:** The original table, but with values from the other table added.
+
+
+**Example:**
+```tomo
+t := {"A": 1; "B": 2}
+assert t.with({"B": 20, "C": 30}) == {"A": 1, "B": 20, "C": 30}
+
+```
 ## Table.with_fallback
 
 ```tomo
@@ -191,3 +259,27 @@ t3 = t.with_fallback(none)
 = none
 
 ```
+## Table.without
+
+```tomo
+Table.without : func(t: {K:V}, other: {K:V} -> {K:V})
+```
+
+Return a copy of a table, but without any of the exact key/value pairs found in the other table.
+
+Only exact key/value pairs will be discarded. Keys with a non-matching value will be kept.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+t | `{K:V}` | The base table.  | -
+other | `{K:V}` | The other table whose key/value pairs will be omitted.  | -
+
+**Return:** The original table, but without the key/value pairs from the other table.
+
+
+**Example:**
+```tomo
+t := {"A": 1; "B": 2, "C": 3}
+assert t.without({"B": 2, "C": 30, "D": 40}) == {"A": 1, "C": 3}
+
+```
diff --git a/api/tables.yaml b/api/tables.yaml
index 4b553b18..ce56c77e 100644
--- a/api/tables.yaml
+++ b/api/tables.yaml
@@ -14,6 +14,30 @@ Table.clear:
   example: |
     >> t.clear()
 
+Table.difference:
+  short: return a table using keys not present in both tables
+  description: >
+    Return a table whose key/value pairs correspond to keys only present in one
+    table, but not the other.
+  return:
+    type: '{K:V}'
+    description: >
+      A table containing the common key/value pairs whose keys only appear in
+      one table.
+  args:
+    t:
+      type: '{K:V}'
+      description: >
+        The base table.
+    other:
+      type: '{K:V}'
+      description: >
+        The other table.
+  example: |
+    t1 := {"A": 1; "B": 2, "C": 3}
+    t2 := {"B": 2, "C":30, "D": 40}
+    assert t1.difference(t2) == {"A": 1, "D": 40}
+
 Table.get:
   short: get an item from a table
   description: >
@@ -110,6 +134,29 @@ Table.has:
     >> {"A": 1, "B": 2}.has("xxx")
     = no
 
+Table.intersection:
+  short: return a table with common key/value pairs from two tables
+  description: >
+    Return a table with only the matching key/value pairs that are common to
+    both tables.
+  return:
+    type: '{K:V}'
+    description: >
+      A table containing the common key/value pairs shared between two tables.
+  args:
+    t:
+      type: '{K:V}'
+      description: >
+        The base table.
+    other:
+      type: '{K:V}'
+      description: >
+        The other table.
+  example: |
+    t1 := {"A": 1; "B": 2, "C": 3}
+    t2 := {"B": 2, "C":30, "D": 40}
+    assert t1.intersection(t2) == {"B": 2}
+
 Table.remove:
   short: remove a table entry
   description: >
@@ -160,6 +207,52 @@ Table.set:
     >> t
     = {"A": 1, "B": 2, "C": 3}
 
+Table.with:
+  short: return a table with values added from another table
+  description: >
+    Return a copy of a table with values added from another table
+  return:
+    type: '{K:V}'
+    description: >
+      The original table, but with values from the other table added.
+  args:
+    t:
+      type: '{K:V}'
+      description: >
+        The base table.
+    other:
+      type: '{K:V}'
+      description: >
+        The other table from which new key/value pairs will be added.
+  example: |
+    t := {"A": 1; "B": 2}
+    assert t.with({"B": 20, "C": 30}) == {"A": 1, "B": 20, "C": 30}
+
+Table.without:
+  short: return a table without key/value pairs in another table
+  description: >
+    Return a copy of a table, but without any of the exact key/value pairs
+    found in the other table.
+  note: >
+    Only exact key/value pairs will be discarded. Keys with a non-matching
+    value will be kept.
+  return:
+    type: '{K:V}'
+    description: >
+      The original table, but without the key/value pairs from the other table.
+  args:
+    t:
+      type: '{K:V}'
+      description: >
+        The base table.
+    other:
+      type: '{K:V}'
+      description: >
+        The other table whose key/value pairs will be omitted.
+  example: |
+    t := {"A": 1; "B": 2, "C": 3}
+    assert t.without({"B": 2, "C": 30, "D": 40}) == {"A": 1, "C": 3}
+
 Table.with_fallback:
   short: return a table with a new fallback
   description: >
diff --git a/man/man3/tomo-Table.difference.3 b/man/man3/tomo-Table.difference.3
new file mode 100644
index 00000000..8f123834
--- /dev/null
+++ b/man/man3/tomo-Table.difference.3
@@ -0,0 +1,36 @@
+'\" t
+.\" Copyright (c) 2025 Bruce Hill
+.\" All rights reserved.
+.\"
+.TH Table.difference 3 2025-09-21 "Tomo man-pages"
+.SH NAME
+Table.difference \- return a table using keys not present in both tables
+.SH LIBRARY
+Tomo Standard Library
+.SH SYNOPSIS
+.nf
+.BI Table.difference\ :\ func(t:\ {K:V},\ other:\ {K:V}\ ->\ {K:V})
+.fi
+.SH DESCRIPTION
+Return a table whose key/value pairs correspond to keys only present in one table, but not the other.
+
+
+.SH ARGUMENTS
+
+.TS
+allbox;
+lb lb lbx lb
+l l l l.
+Name	Type	Description	Default
+t	{K:V}	The base table. 	-
+other	{K:V}	The other table. 	-
+.TE
+.SH RETURN
+A table containing the common key/value pairs whose keys only appear in one table.
+
+.SH EXAMPLES
+.EX
+t1 := {"A": 1; "B": 2, "C": 3}
+t2 := {"B": 2, "C":30, "D": 40}
+assert t1.difference(t2) == {"A": 1, "D": 40}
+.EE
diff --git a/man/man3/tomo-Table.intersection.3 b/man/man3/tomo-Table.intersection.3
new file mode 100644
index 00000000..64a2e32c
--- /dev/null
+++ b/man/man3/tomo-Table.intersection.3
@@ -0,0 +1,36 @@
+'\" t
+.\" Copyright (c) 2025 Bruce Hill
+.\" All rights reserved.
+.\"
+.TH Table.intersection 3 2025-09-21 "Tomo man-pages"
+.SH NAME
+Table.intersection \- return a table with common key/value pairs from two tables
+.SH LIBRARY
+Tomo Standard Library
+.SH SYNOPSIS
+.nf
+.BI Table.intersection\ :\ func(t:\ {K:V},\ other:\ {K:V}\ ->\ {K:V})
+.fi
+.SH DESCRIPTION
+Return a table with only the matching key/value pairs that are common to both tables.
+
+
+.SH ARGUMENTS
+
+.TS
+allbox;
+lb lb lbx lb
+l l l l.
+Name	Type	Description	Default
+t	{K:V}	The base table. 	-
+other	{K:V}	The other table. 	-
+.TE
+.SH RETURN
+A table containing the common key/value pairs shared between two tables.
+
+.SH EXAMPLES
+.EX
+t1 := {"A": 1; "B": 2, "C": 3}
+t2 := {"B": 2, "C":30, "D": 40}
+assert t1.intersection(t2) == {"B": 2}
+.EE
diff --git a/man/man3/tomo-Table.with.3 b/man/man3/tomo-Table.with.3
new file mode 100644
index 00000000..988fb888
--- /dev/null
+++ b/man/man3/tomo-Table.with.3
@@ -0,0 +1,35 @@
+'\" t
+.\" Copyright (c) 2025 Bruce Hill
+.\" All rights reserved.
+.\"
+.TH Table.with 3 2025-09-21 "Tomo man-pages"
+.SH NAME
+Table.with \- return a table with values added from another table
+.SH LIBRARY
+Tomo Standard Library
+.SH SYNOPSIS
+.nf
+.BI Table.with\ :\ func(t:\ {K:V},\ other:\ {K:V}\ ->\ {K:V})
+.fi
+.SH DESCRIPTION
+Return a copy of a table with values added from another table
+
+
+.SH ARGUMENTS
+
+.TS
+allbox;
+lb lb lbx lb
+l l l l.
+Name	Type	Description	Default
+t	{K:V}	The base table. 	-
+other	{K:V}	The other table from which new key/value pairs will be added. 	-
+.TE
+.SH RETURN
+The original table, but with values from the other table added.
+
+.SH EXAMPLES
+.EX
+t := {"A": 1; "B": 2}
+assert t.with({"B": 20, "C": 30}) == {"A": 1, "B": 20, "C": 30}
+.EE
diff --git a/man/man3/tomo-Table.without.3 b/man/man3/tomo-Table.without.3
new file mode 100644
index 00000000..7244dac6
--- /dev/null
+++ b/man/man3/tomo-Table.without.3
@@ -0,0 +1,38 @@
+'\" t
+.\" Copyright (c) 2025 Bruce Hill
+.\" All rights reserved.
+.\"
+.TH Table.without 3 2025-09-21 "Tomo man-pages"
+.SH NAME
+Table.without \- return a table without key/value pairs in another table
+.SH LIBRARY
+Tomo Standard Library
+.SH SYNOPSIS
+.nf
+.BI Table.without\ :\ func(t:\ {K:V},\ other:\ {K:V}\ ->\ {K:V})
+.fi
+.SH DESCRIPTION
+Return a copy of a table, but without any of the exact key/value pairs found in the other table.
+
+
+.SH ARGUMENTS
+
+.TS
+allbox;
+lb lb lbx lb
+l l l l.
+Name	Type	Description	Default
+t	{K:V}	The base table. 	-
+other	{K:V}	The other table whose key/value pairs will be omitted. 	-
+.TE
+.SH RETURN
+The original table, but without the key/value pairs from the other table.
+
+.SH NOTES
+Only exact key/value pairs will be discarded. Keys with a non-matching value will be kept.
+
+.SH EXAMPLES
+.EX
+t := {"A": 1; "B": 2, "C": 3}
+assert t.without({"B": 2, "C": 30, "D": 40}) == {"A": 1, "C": 3}
+.EE