Specify •HashMap

mlochbaum · Dec 4, 2023 · 82b15a3 · 82b15a3
1 parent 1849676
commit 82b15a3
Show file tree

Hide file tree

Showing 2 changed files with 65 additions and 0 deletions.
diff --git a/docs/spec/system.html b/docs/spec/system.html
@@ -53,6 +53,10 @@ <h1 id="specification-bqn-system-provided-values"><a class="header" href="#speci
 <td><code><span class='Value'>•ns</span></code></td>
 </tr>
 <tr>
+<td><a href="#data-structures">Data structures</a></td>
+<td><code><span class='Function'>•HashMap</span></code></td>
+</tr>
+<tr>
 <td><a href="#time">Time</a></td>
 <td><code><span class='Function'>•UnixTime</span></code>, <code><span class='Function'>•Delay</span></code>, <code><span class='Modifier'>•_timed</span></code>, …</td>
 </tr>
@@ -664,6 +668,48 @@ <h2 id="namespaces"><a class="header" href="#namespaces">Namespaces</a></h2>
 </tbody>
 </table>
 <p><code><span class='Function'>Keys</span></code> returns field names as strings, normalized in the sense that all underscores are removed and alphabetic characters are converted to lowercase. The order of the names is unspecified. <code><span class='Function'>Has</span></code> and <code><span class='Function'>Get</span></code> accept names with any spelling. <code><span class='Function'>Get</span></code> causes an error if <code><span class='Value'>𝕩</span></code> isn't the name of a field of <code><span class='Value'>𝕨</span></code>, while <code><span class='Function'>Has</span></code> causes an error only if it isn't a string, returning <code><span class='Number'>0</span></code> for any string that isn't a valid name.</p>
+<h2 id="data-structures"><a class="header" href="#data-structures">Data structures</a></h2>
+<p>The system function <code><span class='Function'>•HashMap</span></code> creates a mutable object from the list of initial keys <code><span class='Value'>𝕨</span></code> and values <code><span class='Value'>𝕩</span></code> that maintains an association mapping keys to values. It has the following fields:</p>
+<table>
+<thead>
+<tr>
+<th>Name</th>
+<th>Summary</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code><span class='Function'>Count</span></code></td>
+<td>return the number of keys present</td>
+</tr>
+<tr>
+<td><code><span class='Function'>Keys</span></code></td>
+<td>return all keys as a list in the order they were set</td>
+</tr>
+<tr>
+<td><code><span class='Function'>Values</span></code></td>
+<td>return all values corresponding to the keys</td>
+</tr>
+<tr>
+<td><code><span class='Function'>Has</span></code></td>
+<td>return <code><span class='Number'>1</span></code> if key <code><span class='Value'>𝕩</span></code> is present and <code><span class='Number'>0</span></code> otherwise</td>
+</tr>
+<tr>
+<td><code><span class='Function'>Get</span></code></td>
+<td>return value for key <code><span class='Value'>𝕩</span></code>, and <code><span class='Value'>𝕨</span></code> or error if not found</td>
+</tr>
+<tr>
+<td><code><span class='Function'>Set</span></code></td>
+<td>set value for key <code><span class='Value'>𝕨</span></code> to <code><span class='Value'>𝕩</span></code>, possibly replacing an existing value</td>
+</tr>
+<tr>
+<td><code><span class='Function'>Delete</span></code></td>
+<td>remove the entry for key <code><span class='Value'>𝕩</span></code></td>
+</tr>
+</tbody>
+</table>
+<p>Fields <code><span class='Function'>Count</span></code>, <code><span class='Function'>Keys</span></code>, and <code><span class='Function'>Values</span></code> take one argument and ignore it. <code><span class='Function'>Set</span></code> and <code><span class='Function'>Delete</span></code> return the map object itself.</p>
+<p>Any BQN value can be used as a key, and two keys are considered the same if they match (as in <code><span class='Function'>≡</span></code>). The initial key list <code><span class='Value'>𝕨</span></code> passed to <code><span class='Function'>•HashMap</span></code> can't contain duplicates, that is, the function errors if <code><span class='Function'>¬∧</span><span class='Modifier'>´</span><span class='Function'>∊</span><span class='Value'>𝕨</span></code>. This key list defines the initial ordering used by <code><span class='Function'>Keys</span></code>, which may then be modified by <code><span class='Function'>Set</span></code> and <code><span class='Function'>Delete</span></code>. When <code><span class='Function'>Set</span></code> adds a key that's not currently present, that key is added to the end of the ordering. When <code><span class='Function'>Delete</span></code> removes a key, it's removed from the ordering, and will be added to the end if set again.</p>
 <h2 id="time"><a class="header" href="#time">Time</a></h2>
 <table>
 <thead>

diff --git a/spec/system.md b/spec/system.md
@@ -19,6 +19,7 @@ All system values described in the BQN specification are optional: an implementa
 | [Platform](#platform) | `•platform`
 | [Operation properties](#operation-properties) | `•Type`, `•Glyph`, `•Source`, `•Decompose`
 | [Namespaces](#namespaces) | `•ns`
+| [Data structures](#data-structures) | `•HashMap`
 | [Time](#time) | `•UnixTime`, `•Delay`, `•_timed`, …
 | [Math](#math) | `•math`
 | [Random generation](#random-generation) | `•rand`, `•MakeRand`
@@ -316,6 +317,24 @@ The system namespace `•ns` contains functionality for working with namespaces.
 
 `Keys` returns field names as strings, normalized in the sense that all underscores are removed and alphabetic characters are converted to lowercase. The order of the names is unspecified. `Has` and `Get` accept names with any spelling. `Get` causes an error if `𝕩` isn't the name of a field of `𝕨`, while `Has` causes an error only if it isn't a string, returning `0` for any string that isn't a valid name.
 
+## Data structures
+
+The system function `•HashMap` creates a mutable object from the list of initial keys `𝕨` and values `𝕩` that maintains an association mapping keys to values. It has the following fields:
+
+| Name     | Summary
+|----------|-------------------------------
+| `Count`  | return the number of keys present
+| `Keys`   | return all keys as a list in the order they were set
+| `Values` | return all values corresponding to the keys
+| `Has`    | return `1` if key `𝕩` is present and `0` otherwise
+| `Get`    | return value for key `𝕩`, and `𝕨` or error if not found
+| `Set`    | set value for key `𝕨` to `𝕩`, possibly replacing an existing value
+| `Delete` | remove the entry for key `𝕩`
+
+Fields `Count`, `Keys`, and `Values` take one argument and ignore it. `Set` and `Delete` return the map object itself.
+
+Any BQN value can be used as a key, and two keys are considered the same if they match (as in `≡`). The initial key list `𝕨` passed to `•HashMap` can't contain duplicates, that is, the function errors if `¬∧´∊𝕨`. This key list defines the initial ordering used by `Keys`, which may then be modified by `Set` and `Delete`. When `Set` adds a key that's not currently present, that key is added to the end of the ordering. When `Delete` removes a key, it's removed from the ordering, and will be added to the end if set again.
+
 ## Time
 
 | Name          | Summary