Associative Lists / Dictionaries: Difference between revisions
Jump to navigation
Jump to search
(Created page with "= Associative Lists / Dictionaries = The '''Associative Lists / Dictionaries''' module provides key-value data structure operations for the SCM programming language. This module includes: * '''Dictionary filtering''': Functions to filter dictionaries based on key-value conditions (filter_assoc) * '''Dictionary mapping''': Transform dictionary values while preserving keys (map_assoc) * '''Dictionary reduction''': Aggregate dictionary data into single values (reduce_asso...") |
No edit summary |
||
| Line 19: | Line 19: | ||
'''Allowed number of parameters:''' 2–2 | '''Allowed number of parameters:''' 2–2 | ||
<span id="parameters"></span> | |||
=== Parameters === | |||
* '''dict''' (<code>list</code>): dictionary that has to be filtered | * '''dict''' (<code>list</code>): dictionary that has to be filtered | ||
* '''condition''' (<code>func</code>): filter function func(string any)- | * '''condition''' (<code>func(key:string, value:any) -> bool</code>): filter function func(string any)->bool where the first parameter is the key, the second is the value | ||
<span id="returns"></span> | |||
=== Returns === | |||
<code>list</code> | |||
== find_assoc == | |||
returns the first key/value pair that passes the condition function, or nil/default if none matches | |||
'''Allowed number of parameters:''' 2–3 | |||
<span id="parameters-1"></span> | |||
=== Parameters === | |||
* '''dict''' (<code>list</code>): dictionary to search | |||
* '''condition''' (<code>func(key:string, value:any) -> bool</code>): predicate func(string any)->bool that is applied until the first match | |||
* '''default''' (<code>any</code>): optional default value if nothing matches ''(optional)'' | |||
<span id="returns-1"></span> | |||
=== Returns === | |||
<code>any</code> | |||
== map_assoc == | == map_assoc == | ||
returns a mapped dictionary according to a map function | returns a mapped dictionary according to a map function Keys will stay the same but values are mapped. | ||
'''Allowed number of parameters:''' 2–2 | '''Allowed number of parameters:''' 2–2 | ||
<span id="parameters-2"></span> | |||
=== Parameters === | |||
* '''dict''' (<code>list</code>): dictionary that has to be mapped | * '''dict''' (<code>list</code>): dictionary that has to be mapped | ||
* '''map''' (<code>func</code>): map function func(string any)- | * '''map''' (<code>func(key:string, value:any) -> any</code>): map function func(string any)->any where the first parameter is the key, the second is the value. It must return the new value. | ||
<span id="returns-2"></span> | |||
=== Returns === | |||
<code>list</code> | |||
== reduce_assoc == | == reduce_assoc == | ||
| Line 43: | Line 71: | ||
'''Allowed number of parameters:''' 3–3 | '''Allowed number of parameters:''' 3–3 | ||
<span id="parameters-3"></span> | |||
=== Parameters === | |||
* '''dict''' (<code>list</code>): dictionary that has to be reduced | * '''dict''' (<code>list</code>): dictionary that has to be reduced | ||
* '''reduce''' (<code>func</code>): reduce function func(any string any)- | * '''reduce''' (<code>func(acc:any, key:any, value:any) -> any</code>): reduce function func(any string any)->any where the first parameter is the accumulator, second is key, third is value. It must return the new accumulator. | ||
* '''neutral''' (<code>any</code>): initial value for the accumulator | * '''neutral''' (<code>any</code>): initial value for the accumulator | ||
<span id="returns-3"></span> | |||
=== Returns === | |||
<code>any</code> | |||
== make_structural_index == | |||
Builds an immutable structural-expression index. It eagerly hashes every key and every node under roots, then returns a parallel-safe lookup function that maps an equal expression to its zero-based key position or nil. | |||
'''Allowed number of parameters:''' 2–2 | |||
<span id="parameters-4"></span> | |||
=== Parameters === | |||
* '''keys''' (<code>list</code>): immutable structural expressions to index | |||
* '''roots''' (<code>list</code>): immutable expression roots whose descendant hashes are precomputed | |||
<span id="returns-4"></span> | |||
=== Returns === | |||
<code>func(expression:any) -> int|nil</code> | |||
== make_structural_catalog == | |||
Creates an atomic compile-local structural catalog. Look up with (catalog key), insert with (catalog key value), or freeze with (catalog) for parallel-safe read-only lookup. | |||
'''Allowed number of parameters:''' 0–1 | |||
<span id="parameters-5"></span> | |||
=== Parameters === | |||
* '''mode''' (<code>bool|symbol</code>): true forces collisions for tests; ast selects type-stable compiler equality ''(optional)'' | |||
<span id="returns-5"></span> | |||
=== Returns === | |||
<code>func</code> | |||
<span id="has_assoc"></span> | |||
== has_assoc? == | == has_assoc? == | ||
| Line 56: | Line 123: | ||
'''Allowed number of parameters:''' 2–2 | '''Allowed number of parameters:''' 2–2 | ||
<span id="parameters-6"></span> | |||
=== Parameters === | |||
* '''dict''' (<code>list</code>): dictionary that has to be checked | * '''dict''' (<code>list</code>): dictionary that has to be checked | ||
* '''key''' (<code>string</code>): key to test | * '''key''' (<code>string</code>): key to test | ||
'''Returns:''' <code> | <span id="returns-6"></span> | ||
=== Returns === | |||
<code>bool</code> | |||
== get_assoc == | |||
gets a value from a dictionary by key, returns nil if not found | |||
'''Allowed number of parameters:''' 2–3 | |||
<span id="parameters-7"></span> | |||
=== Parameters === | |||
* '''dict''' (<code>list</code>): dictionary to look up | |||
* '''key''' (<code>any</code>): key to look up | |||
* '''default''' (<code>any</code>): optional default value if key not found ''(optional)'' | |||
<span id="returns-7"></span> | |||
=== Returns === | |||
<code>any</code> | |||
== get_assoc_pairlist == | |||
gets a value from a list of key/value rows without flattening the rows | |||
'''Allowed number of parameters:''' 3–3 | |||
<span id="parameters-8"></span> | |||
=== Parameters === | |||
* '''rows''' (<code>list</code>): list whose rows contain a key followed by one or more values | |||
* '''key''' (<code>any</code>): key compared with the first item of each row | |||
* '''default''' (<code>any</code>): value returned when no row contains the key | |||
<span id="returns-8"></span> | |||
=== Returns === | |||
<code>any</code> | |||
== extract_assoc == | == extract_assoc == | ||
| Line 68: | Line 176: | ||
'''Allowed number of parameters:''' 2–2 | '''Allowed number of parameters:''' 2–2 | ||
<span id="parameters-9"></span> | |||
=== Parameters === | |||
* '''dict''' (<code>list</code>): dictionary that has to be checked | * '''dict''' (<code>list</code>): dictionary that has to be checked | ||
* '''map''' (<code>func</code>): func( | * '''map''' (<code>func(key:string, value:any) -> any</code>): func(key, value)->any that extracts one element per key-value pair | ||
<span id="returns-9"></span> | |||
=== Returns === | |||
<code>list</code> | |||
== set_assoc == | == set_assoc == | ||
returns a dictionary where a single value has been changed. | returns a new dictionary where a single value has been changed. The original dictionary is not modified. | ||
'''Allowed number of parameters:''' 3–4 | '''Allowed number of parameters:''' 3–4 | ||
<span id="parameters-10"></span> | |||
* '''dict''' (<code>list</code>): input dictionary | === Parameters === | ||
* '''dict''' (<code>list</code>): input dictionary | |||
* '''key''' (<code>string</code>): key that has to be set | * '''key''' (<code>string</code>): key that has to be set | ||
* '''value''' (<code>any</code>): new value to set | * '''value''' (<code>any</code>): new value to set | ||
* '''merge''' (<code>func</code>): (optional) func(any any)- | * '''merge''' (<code>func(old:any, new:any) -> any</code>): (optional) func(any any)->any that is called when a value is overwritten. The first parameter is the old value, the second is the new value. It must return the merged value that shall be physically stored in the new dictionary. ''(optional)'' | ||
<span id="returns-10"></span> | |||
=== Returns === | |||
<code>list</code> | |||
== merge_assoc == | == merge_assoc == | ||
| Line 94: | Line 212: | ||
'''Allowed number of parameters:''' 2–3 | '''Allowed number of parameters:''' 2–3 | ||
<span id="parameters-11"></span> | |||
=== Parameters === | |||
* '''dict1''' (<code>list</code>): first input dictionary that has to be changed. You must not use this value again. | * '''dict1''' (<code>list</code>): first input dictionary that has to be changed. You must not use this value again. | ||
* '''dict2''' (<code>list</code>): input dictionary that contains the new values that have to be added | * '''dict2''' (<code>list</code>): input dictionary that contains the new values that have to be added | ||
* '''merge''' (<code>func</code>): (optional) func(any any)- | * '''merge''' (<code>func(old:any, new:any) -> any</code>): (optional) func(any any)->any that is called when a value is overwritten. The first parameter is the old value, the second is the new value from dict2. It must return the merged value that shall be pysically stored in the new dictionary. ''(optional)'' | ||
<span id="returns-11"></span> | |||
=== Returns === | |||
<code>list</code> | |||
== sort == | |||
returns a sorted copy of a list using a comparator (lambda (a b) truthy/falsy) | |||
'''Allowed number of parameters:''' 2–2 | |||
<span id="parameters-12"></span> | |||
=== Parameters === | |||
* '''list''' (<code>list</code>): | |||
* '''comparator''' (<code>func(any, any) -> bool</code>): | |||
<span id="returns-12"></span> | |||
=== Returns === | |||
<code>list</code> | |||
== sort_mut == | |||
sorts a list in-place using a comparator (lambda (a b) truthy/falsy) | |||
'''Allowed number of parameters:''' 2–2 | |||
<span id="parameters-13"></span> | |||
=== Parameters === | |||
* '''list''' (<code>list</code>): | |||
* '''comparator''' (<code>func(any, any) -> bool</code>): | |||
<span id="returns-13"></span> | |||
=== Returns === | |||
<code>list</code> | |||
== mapkey_assoc == | |||
returns a mapped dictionary according to a map function Values stay the same but keys are mapped. | |||
'''Allowed number of parameters:''' 2–2 | |||
<span id="parameters-14"></span> | |||
=== Parameters === | |||
* '''dict''' (<code>list</code>): dictionary whose keys have to be mapped | |||
* '''map''' (<code>func(key:string, value:any) -> any</code>): map function func(key, value)->key where the first parameter is the old key, the second is the value. It must return the new key. | |||
<span id="returns-14"></span> | |||
=== Returns === | |||
<code>list</code> | |||
Revision as of 08:10, 27 August 2026
Associative Lists / Dictionaries
The Associative Lists / Dictionaries module provides key-value data structure operations for the SCM programming language. This module includes:
- Dictionary filtering: Functions to filter dictionaries based on key-value conditions (filter_assoc)
- Dictionary mapping: Transform dictionary values while preserving keys (map_assoc)
- Dictionary reduction: Aggregate dictionary data into single values (reduce_assoc)
- Dictionary queries: Check for key existence and extract data (has_assoc?, extract_assoc)
- Dictionary modification: Set individual values and merge dictionaries (set_assoc, merge_assoc)
These functions provide essential tools for working with associative data structures, enabling efficient key-value operations and dictionary manipulation in SCM programs.
← Back to Full SCM API documentation
filter_assoc
returns a filtered dictionary according to a filter function
Allowed number of parameters: 2–2
Parameters
- dict (
list): dictionary that has to be filtered - condition (
func(key:string, value:any) -> bool): filter function func(string any)->bool where the first parameter is the key, the second is the value
Returns
list
find_assoc
returns the first key/value pair that passes the condition function, or nil/default if none matches
Allowed number of parameters: 2–3
Parameters
- dict (
list): dictionary to search - condition (
func(key:string, value:any) -> bool): predicate func(string any)->bool that is applied until the first match - default (
any): optional default value if nothing matches (optional)
Returns
any
map_assoc
returns a mapped dictionary according to a map function Keys will stay the same but values are mapped.
Allowed number of parameters: 2–2
Parameters
- dict (
list): dictionary that has to be mapped - map (
func(key:string, value:any) -> any): map function func(string any)->any where the first parameter is the key, the second is the value. It must return the new value.
Returns
list
reduce_assoc
reduces a dictionary according to a reduce function
Allowed number of parameters: 3–3
Parameters
- dict (
list): dictionary that has to be reduced - reduce (
func(acc:any, key:any, value:any) -> any): reduce function func(any string any)->any where the first parameter is the accumulator, second is key, third is value. It must return the new accumulator. - neutral (
any): initial value for the accumulator
Returns
any
make_structural_index
Builds an immutable structural-expression index. It eagerly hashes every key and every node under roots, then returns a parallel-safe lookup function that maps an equal expression to its zero-based key position or nil.
Allowed number of parameters: 2–2
Parameters
- keys (
list): immutable structural expressions to index - roots (
list): immutable expression roots whose descendant hashes are precomputed
Returns
func(expression:any) -> int|nil
make_structural_catalog
Creates an atomic compile-local structural catalog. Look up with (catalog key), insert with (catalog key value), or freeze with (catalog) for parallel-safe read-only lookup.
Allowed number of parameters: 0–1
Parameters
- mode (
bool|symbol): true forces collisions for tests; ast selects type-stable compiler equality (optional)
Returns
func
has_assoc?
checks if a dictionary has a key present
Allowed number of parameters: 2–2
Parameters
- dict (
list): dictionary that has to be checked - key (
string): key to test
Returns
bool
get_assoc
gets a value from a dictionary by key, returns nil if not found
Allowed number of parameters: 2–3
Parameters
- dict (
list): dictionary to look up - key (
any): key to look up - default (
any): optional default value if key not found (optional)
Returns
any
get_assoc_pairlist
gets a value from a list of key/value rows without flattening the rows
Allowed number of parameters: 3–3
Parameters
- rows (
list): list whose rows contain a key followed by one or more values - key (
any): key compared with the first item of each row - default (
any): value returned when no row contains the key
Returns
any
extract_assoc
applies a function (key value) on the dictionary and returns the results as a flat list
Allowed number of parameters: 2–2
Parameters
- dict (
list): dictionary that has to be checked - map (
func(key:string, value:any) -> any): func(key, value)->any that extracts one element per key-value pair
Returns
list
set_assoc
returns a new dictionary where a single value has been changed. The original dictionary is not modified.
Allowed number of parameters: 3–4
Parameters
- dict (
list): input dictionary - key (
string): key that has to be set - value (
any): new value to set - merge (
func(old:any, new:any) -> any): (optional) func(any any)->any that is called when a value is overwritten. The first parameter is the old value, the second is the new value. It must return the merged value that shall be physically stored in the new dictionary. (optional)
Returns
list
merge_assoc
returns a dictionary where all keys from dict1 and all keys from dict2 are present. If a key is present in both inputs, the second one will be dominant so the first value will be overwritten unless you provide a merge function
Allowed number of parameters: 2–3
Parameters
- dict1 (
list): first input dictionary that has to be changed. You must not use this value again. - dict2 (
list): input dictionary that contains the new values that have to be added - merge (
func(old:any, new:any) -> any): (optional) func(any any)->any that is called when a value is overwritten. The first parameter is the old value, the second is the new value from dict2. It must return the merged value that shall be pysically stored in the new dictionary. (optional)
Returns
list
sort
returns a sorted copy of a list using a comparator (lambda (a b) truthy/falsy)
Allowed number of parameters: 2–2
Parameters
- list (
list): - comparator (
func(any, any) -> bool):
Returns
list
sort_mut
sorts a list in-place using a comparator (lambda (a b) truthy/falsy)
Allowed number of parameters: 2–2
Parameters
- list (
list): - comparator (
func(any, any) -> bool):
Returns
list
mapkey_assoc
returns a mapped dictionary according to a map function Values stay the same but keys are mapped.
Allowed number of parameters: 2–2
Parameters
- dict (
list): dictionary whose keys have to be mapped - map (
func(key:string, value:any) -> any): map function func(key, value)->key where the first parameter is the old key, the second is the value. It must return the new key.
Returns
list