# KV Tables

{% hint style="warning" %}
Type signatures are provisional and may contain errors.
{% endhint %}

A tab is a data-jetted map from noun to noun.

### tabSing

```
(tabSing key val)
> key : a
> val : b
> Tab a
```

Creates a singleton table with one key-value pair.

```sire
tabSing 1 2        == [1=2]
tabSing {a} {b}    == [a=(%b)]
tabSing 0 []       == [0=[]]
```

### isTab

```
(isTab x)
> x : a
> Bool
```

Checks if the given value is a table.

```sire
isTab #[]           == 1
isTab #[x=3 y=4]    == 1
isTab []            == 0
```

### tabSearchCase

```
(tabSearchCase key t d k)
> key : a
> t   : Tab a b
> d   : c
> k   : (Nat > b > c)
> c
```

Inline function that finds the index of a key within a table. Returns a continuation with the associated value.

```sire
tabSearchCase 1 #[1=3 2=4] {nf} (ix v & [ix v])    == [0 3]
tabSearchCase 2 #[1=3 2=4] {nf} (ix v & [ix v])    == [1 4]
tabSearchCase 3 #[1=3 2=4] {nf} (ix v & [ix v])    == %nf
```

### tabLen

```
(tabLen t)
> t : Tab a
> Nat
```

Returns the number of key-value pairs in a table.

```sire
tabLen #[]           == 0
tabLen #[x=0]        == 1
tabLen #[x=0 y=1]    == 2
```

### tabIdx

```
(tabIdx key t)
> key : a
> t   : Tab a
> b
```

Retrieves the value associated with a given key in a table.

```sire
tabIdx 0 #[0=8]             == 8
tabIdx %aa #(bb=8, aa=9)    == 9
tabIdx 3 #[1=4 2=5]         == 0
```

### tabKeysSet

```
(tabKeysSet t)
> t : Tab a
> Set a
```

Returns the set of keys in a table.

```sire
tabKeysSet #[1=3 2=4]    == %[1 2]
tabKeysSet #[]           == %[]
tabKeysSet #[a=1 b=2]    == %[a b]
```

### tabKeysRow

```
(tabKeysRow t)
> t : Tab a
> Row a
```

Returns the row of keys in a table.

```sire
tabKeysRow #[3=3 4=4]    == [3 4]
tabKeysRow #[]           == []
tabKeysRow #[a=1 b=2]    == [%a %b]
```

### tabKeysList

```
(tabKeysList t)
> t : Tab a
> List a
```

Returns the list of keys in a table.

```sire
tabKeysList #[3=3 4=4]    == [3 [4 0]]
tabKeysList #[]           == 0
tabKeysList #[a=1 b=2]    == [%a [%b 0]]
```

### tabHas

```
(tabHas key t)
> key : a
> t   : Tab a
> Bool
```

Checks if a key exists in a table.

```sire
tabHas %aa #(bb=8, aa=9)    == 1
tabHas %cc #(bb=8, aa=9)    == 0
tabHas 1 #[1=4 2=5]         == 1
```

### tabGet

```
(tabGet t key)
> t   : Tab a
> key : a
> b
```

Retrieves the value associated with a given key in a table.

```sire
tabGet #[1=4 2=5] 1    == 4
tabGet #[1=4 2=5] 2    == 5
tabGet #[1=4 2=5] 3    == 0
```

### tabValsRow

```
(tabValsRow t)
> t : Tab a
> Row b
```

Returns the row of values in a table.

```sire
tabValsRow #[3=3 4=4]    == [3 4]
tabValsRow #[]           == []
tabValsRow #[a=1 b=2]    == [1 2]
```

### tabValsList

```
(tabValsList t)
> t : Tab a
> List b
```

Returns the list of values in a table.

```sire
tabValsList #[3=3 4=4]    == [3 [4 0]]
tabValsList #[]           == 0
tabValsList #[a=1 b=2]    == [1 [2 0]]
```

### tabSwitch

```
(tabSwitch key d t)
> key : a
> d   : b
> t   : Tab b
> b
```

Looks up a key in a table, returning a default value if not found.

```sire
tabSwitch 1 {not found} #[1=3 2=4]    == 3
tabSwitch 2 {not found} #[1=3 2=4]    == 4
tabSwitch 3 {not found} #[1=3 2=4]    == 0
```

### tabFromPairs

```
(tabFromPairs xs)
> xs : Row (a, b)
> Tab a
```

Creates a table from a row of key-value pairs.

```sire
tabFromPairs [[3 8] [5 9]]           == [3=8 5=9]
tabFromPairs [[5 9] [3 8]]           == [3=8 5=9]
tabFromPairs [[3 7] [3 8] [5 9]]     == [3=8 5=9]
```

### tabFromAscPairs

```
(tabFromAscPairs xs)
> xs : Row (a, b)
> Tab a
```

Creates a table from an ascending row of key-value pairs.

```sire
tabFromAscPairs [[1 4] [2 5] [3 6]]    == [1=4 2=5 3=6]
tabFromAscPairs []                     == []
tabFromAscPairs [[a 1] [b 2]]          == [a=1 b=2]
```

### tabToPairs

```
(tabToPairs t)
> t : Tab a
> Row (a, b)
```

Converts a table to a row of key-value pairs.

```sire
tabToPairs #[1=4 2=5 3=6]    == [[1 4] [2 5] [3 6]]
tabToPairs #[]               == []
tabToPairs #[a=1 b=2]        == [[a 1] [b 2]]
```

### tabToPairList

```
(tabToPairList t)
> t : Tab a
> List (a, b)
```

Converts a table to a list of key-value pairs.

```sire
tabToPairList #[3=8 5=9]    == [[3 8] [[5 9] 0]]
tabToPairList #[]           == 0
tabToPairList #[a=1]        == [[%a 1] 0]
```

### tabToList

```
(tabToList t)
> t : Tab a
> List (a, b)
```

Converts a table to a list of key-value pairs.

```sire
tabToList #[3=8 5=9]    == [[3 8] [5 9] 0]
tabToList #[]           == 0
tabToList #[a=1 b=2]    == [[%a 1] [%b 2] 0]
```

### tabPut

```
(tabPut t key val)
> t   : Tab a
> key : a
> val : b
> Tab a
```

Inserts or updates a key-value pair in a table.

```sire
tabPut #[1=3 2=4] 1 5    == [1=5 2=4]
tabPut #[1=3 2=4] 3 5    == [1=3 2=4 3=5]
tabPut #[] 1 5           == [1=5]
```

### tabFromPairsList

```
(tabFromPairsList xs)
> xs : List (a, b)
> Tab a
```

Creates a table from a list of key-value pairs.

```sire
tabFromPairsList ~[[3 8] [5 9]]      == [3=8 5=9]
tabFromPairsList 0                   == []
tabFromPairsList ~[[%a 1] [%b 2]]    == [a=1 b=2]
```

### tabIns

```
(tabIns key val t)
> key : a
> val : b
> t   : Tab a
> Tab a
```

Inserts a key-value pair into a table.

```sire
tabIns 3 3 #[3=4]    == [3=3]
tabIns 4 4 #[3=4]    == [3=4 4=4]
tabIns 0 0 #[]       == [0=0]
```

### tabIsEmpty

```
(tabIsEmpty t)
> t : Tab a
> Bool
```

Checks if a table is empty.

```sire
tabIsEmpty #[]           == 1
tabIsEmpty #[1=2]        == 0
tabIsEmpty #[a=1 b=2]    == 0
```

### tabDel

```
(tabDel key t)
> key : a
> t   : Tab a
> Tab a
```

Deletes a key-value pair from a table.

```sire
tabDel 1 #[1=3 2=4]     == [2=4]
tabDel 3 #[1=3 2=4]     == [1=3 2=4]
tabDel %a #[a=1 b=2]    == [b=2]
```

### tabPop

```
(tabPop t)
> t : Tab a
> (a, b, Tab a)
```

Removes and returns the first key-value pair from a table along with the remaining table.

```sire
tabPop #[1=3 2=4]        == [1 3 [2=4]]
tabPop #[a=1]            == [%a 1 #[]]
tabPop #[a=1 b=2 c=3]    == [%a 1 [b=2 c=3]]
```

### tabSplitAt

```
(tabSplitAt i t)
> i : Nat
> t : Tab a
> (Tab a, Tab a)
```

Splits a table into two tables at a given index.

```sire
tabSplitAt 1 #[1=3 2=4 3=5]    == [[1=3] [2=4 3=5]]
tabSplitAt 0 #[1=3 2=4]        == [#[] [1=3 2=4]]
tabSplitAt 2 #[a=1 b=2 c=3]    == [[a=1 b=2] [c=3]]
```

### tabSplitLT

```
(tabSplitLT k t)
> k : a
> t : Tab a
> (Tab a, Tab a)
```

Splits a table into two tables based on a key.

```sire
tabSplitLT 2 #[1=3 2=4 3=5]     == [[1=3] [2=4 3=5]]
tabSplitLT 0 #[1=3 2=4]         == [#[] [1=3 2=4]]
tabSplitLT %b #[a=1 b=2 c=3]    == [[a=1] [b=2 c=3]]
```

### tabAlter

```
(tabAlter f key t)
> f   : (Maybe a > Maybe b)
> key : a
> t   : Tab a
> Tab a
```

Applies a function to the value associated with a key, potentially inserting or deleting the key-value pair.

```sire
tabAlter (v & SOME (inc v)) 1 #[1=3 2=4]    == [1=1 2=4]
tabAlter (v & NONE) 1 #[1=3 2=4]            == [2=4]
tabAlter (v & SOME 5) 3 #[1=3 2=4]          == [1=3 2=4 3=5]
```

### tabMapWithKey

```
(tabMapWithKey f t)
> f : (a > a > a)
> t : Tab a
> Tab a
```

Applies a function to each key-value pair in a table.

```sire
tabMapWithKey (k v & add k v) #[1=3 2=4]    == [1=4 2=6]
tabMapWithKey (k v & [k v]) #[a=1 b=2]      == [a=[%a 1] b=[%b 2]]
tabMapWithKey (k v & inc v) #[]             == #[]
```

### tabMap

```
(tabMap f t)
> f : (a > a)
> t : Tab a
> Tab a
```

Applies a function to each value in a table.

```sire
tabMap inc #[1=3 2=4]       == [1=4 2=5]
tabMap (mul 2) #[a=1 b=2]   == [a=2 b=4]
tabMap id #[]               == #[]
```

### tabUnionWith

```
(tabUnionWith f t1 t2)
> f  : (a > a > a)
> t1 : Tab a
> t2 : Tab a
> Tab a
```

Merges two tables, using a function to resolve conflicts.

```sire
tabUnionWith add #[1=1 2=2] #[2=20 3=30]                                        == [1=1 2=22 3=30]
tabUnionWith const #[a=1 b=2] #[b=20 c=30]                                      == [a=1 b=2 c=30]
tabUnionWith (x y & LEFT [x y]) #[1=(RIGHT 10)] #[1=(RIGHT 11) 2=(RIGHT 12)]    == [1=(LEFT [10 11]) 2=(RIGHT 12)]
```

### tabUnion

```
(tabUnion t1 t2)
> t1 : Tab a
> t2 : Tab a
> Tab a
```

Merges two tables, with left-biased conflict resolution.

```sire
tabUnion #[1=1 2=2] #[2=20 3=30]    == [1=1 2=2 3=30]
tabUnion #[a=1 b=2] #[b=20 c=30]    == [a=1 b=2 c=30]
tabUnion #[] #[1=10 2=20]           == [1=10 2=20]
```

### tabWeld

```
(tabWeld t1 t2)
> t1 : Tab a
> t2 : Tab a
> Tab a
```

Alias for tabUnion. Merges two tables, with left-biased conflict resolution.

```sire
tabWeld #[1=1 2=2] #[2=20 3=30]    == [1=1 2=2 3=30]
tabWeld #[a=1 b=2] #[b=20 c=30]    == [a=1 b=2 c=30]
tabWeld #[] #[1=10 2=20]           == [1=10 2=20]
```

### tabCatRow

```
(tabCatRow xs)
> xs : Row (Tab a)
> Tab a
```

Merges a row of tables into a single table, with left-biased conflict resolution.

```sire
tabCatRow [#[1=1] #[2=2] #[3=3]]           == [1=1 2=2 3=3]
tabCatRow [#[a=1 b=2] #[b=20 c=30] #[]]    == [a=1 b=2 c=30]
tabCatRow []                               == #[]
```

### tabLookup

```
(tabLookup key t)
> key : a
> t   : Tab a
> Maybe a
```

Looks up a key in a table, returning a Maybe value.

```sire
tabLookup 1 #[1=3 2=4]    == (0 3) ; SOME
tabLookup 2 #[1=3 2=4]    == (0 4) ; SOME
tabLookup 3 #[1=3 2=4]    == 0 ; NONE
```

### tabMinKey

```
(tabMinKey t)
> t : Tab a
> a
```

Returns the smallest key in a table.

```sire
tabMinKey #[3=30 1=10 2=20]    == 1
tabMinKey #[a=1 b=2 c=3]       == %a
tabMinKey #[z=26]              == %z
```

### tabFoldlWithKey

```
(tabFoldlWithKey f acc t)
> f   : (a > b)
> acc : b
> t   : Tab a
> b
```

Folds over a table, applying a function to each key-value pair and an accumulator.

```sire
tabFoldlWithKey (acc k v & add acc (mul k v)) 0 #[1=3 2=4]    == 11
tabFoldlWithKey (acc k v & weld acc [k v]) [] #[a=1 b=2]      == [%a 1 %b 2]
tabFoldlWithKey (acc k v & inc acc) 0 #[]                     == 0
```

### tabElemIdx

```
(tabElemIdx i t)
> i : Nat
> t : Tab a
> Row a
```

Returns the index of a key-value pair in a table, treating it as an array.

```sire
tabElemIdx 0 #[a=1 b=2 c=3]    == [%a 1]
tabElemIdx 1 #[a=1 b=2 c=3]    == [%b 2]
tabElemIdx 3 #[a=1 b=2 c=3]    == 0
```

### emptyTab

```
emptyTab
> Tab a
```

An empty table constant.

```sire
emptyTab                    == #[]
tabIsEmpty emptyTab         == 1
tabUnion emptyTab #[1=2]    == [1=2]
```

### tabInsWith

```
(tabInsWith f key val t)
> f   : (a > a > b)
> key : a
> val : b
> t   : Tab a
> Tab a
```

Inserts a key-value pair into a table, using a function to combine values if the key already exists.

```sire
tabInsWith add 1 6 #[1=3 2=4]          == [1=9 2=4]
tabInsWith const 1 6 #[1=3 2=4]        == [1=6 2=4]
tabInsWith (x y & [x y]) 3 6 #[1=3]    == [1=3 3=6]
```

### tabFilterWithKey

```
(tabFilterWithKey f t)
> f : (a > b > Bool)
> t : Tab a
> Tab a
```

Filters a table based on a predicate function applied to each key-value pair.

```sire
tabFilterWithKey (k v & even k) #[1=1 2=2 3=3 4=4]     == [2=2 4=4]
tabFilterWithKey (k v & eql k v) #[a=1 b=2 c=3]        == #[]
tabFilterWithKey (k v & gth v 2) #[a=1 b=2 c=3 d=4]    == [c=3 d=4]
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://opfn.gitbook.io/pallas/sire-reference/wip-standard-library/kv-tables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.