From 5dd73a1f072dde69574da5ee9cf10ff81dd0408f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Mon, 16 Oct 2023 15:10:34 +0200
Subject: Add documentation and tests for table.

---
 doc/ref/general.texi       |  1 +
 doc/ref/general/table.texi | 38 ++++++++++++++++++++++++++++++++++++
 tests/unit/util/table.scm  | 48 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 87 insertions(+)
 create mode 100644 doc/ref/general/table.texi
 create mode 100644 tests/unit/util/table.scm

diff --git a/doc/ref/general.texi b/doc/ref/general.texi
index 0e14ee34..18b2bfc1 100644
--- a/doc/ref/general.texi
+++ b/doc/ref/general.texi
@@ -11,6 +11,7 @@ of these should be generally useful in any project.
 @include general/uuid.texi
 @include general/io.texi
 @include general/bst.texi
+@include general/table.texi
 @include general/util-path.texi
 @include general/util-config.texi
 @include general/util-exceptions.texi
diff --git a/doc/ref/general/table.texi b/doc/ref/general/table.texi
new file mode 100644
index 00000000..69bb839f
--- /dev/null
+++ b/doc/ref/general/table.texi
@@ -0,0 +1,38 @@
+@node Table
+@section Table
+
+An immutable table, where all operations on the table return a new
+table with the wanted changes carried out. All keys @emph{must} be
+symbols.
+
+@defun table
+Constructs a new empty table.
+@end defun
+
+@defun table? x
+Is @var{x} a table?
+@end defun
+
+@defun table-get table key [default=#f]
+Retrive value form table, returns @var{default} if key isn't in the
+table.
+@end defun
+
+@defun table-put table key value
+Insert new value into table, overwriting anything previously stored
+under that key. Returns a new table with the values set.
+@end defun
+
+@defun table-remove table key
+Returns a new table with @var{key} removed.
+@end defun
+
+@defun table->list table
+Return an association list with the same content as the table.
+
+The keys will be sorted.
+@end defun
+
+@defun alist->table alist
+Construct a new table from the given alist.
+@end defun
diff --git a/tests/unit/util/table.scm b/tests/unit/util/table.scm
new file mode 100644
index 00000000..564dff74
--- /dev/null
+++ b/tests/unit/util/table.scm
@@ -0,0 +1,48 @@
+(define-module (test table)
+  :use-module (srfi srfi-64)
+  :use-module (srfi srfi-88)
+  :use-module ((hnh util) :select (->))
+  :use-module (hnh util table))
+
+(test-expect-fail "Equivalent tables are equal")
+
+(define t (table))
+
+(test-assert "Empty tables are empty" (null? (table->list t)))
+
+(test-equal "Adding elements work"
+  '((a . 10) (b . 20))
+  (-> t
+      (table-put 'a 10)
+      (table-put 'b 20)
+      table->list))
+
+(test-assert "Original table is unchanged"
+  (null? (table->list t)))
+
+(test-equal "Insertion order doesn't matter, when serializing to lists"
+  (-> t
+      (table-put 'a 10)
+      (table-put 'b 20)
+      table->list)
+  (-> t
+      (table-put 'b 20)
+      (table-put 'a 10)
+      table->list))
+
+;;; TODO this doesn't work, since the trees don't rebalance
+(test-equal "Equivalent tables are equal"
+  (-> t
+      (table-put 'a 10)
+      (table-put 'b 20)
+      (table-put 'c 30))
+  (-> t
+      (table-put 'c 30)
+      (table-put 'b 20)
+      (table-put 'a 10)))
+
+;;; TODO test table-get
+;; (table-get t 'key)
+;; (table-put t 'key value)
+
+'((hnh util table))
-- 
cgit v1.2.3