Lists

The Lists module provides comprehensive list manipulation and processing functions for the SCM programming language. This module includes:

List operations: Basic operations like counting (count), accessing elements (nth), and type checking (list?)
List construction: Building lists with append, cons, and unique operations (append_unique, merge_unique)
List deconstruction: Extracting parts with car (head), cdr (tail), and filtering operations
Functional programming: Higher-order functions like map, filter, reduce, and produce for advanced list processing
List utilities: Searching (has?, contains?), merging, zipping, and flattening operations
List generation: Creating sequences and ranges with produce and produceN functions

These functions provide the essential tools for working with lists as the primary data structure in functional programming with SCM.

← Back to Full SCM API documentation

list

constructs a list from its arguments

Allowed number of parameters: 0–10000

Parameters

items (any): items to put into the list (variadic)

Returns

list

count

counts the number of elements in the list

Allowed number of parameters: 1–1

Parameters

list (list): base list

Returns

int

nth

get the nth item of a list

Allowed number of parameters: 2–2

Parameters

list (list): base list
index (number): index beginning from 0

Returns

any

slice

extract a sublist from start (inclusive) to end (exclusive). (slice list start end) returns elements list[start..end).

Allowed number of parameters: 3–3

Parameters

list (list): base list
start (number): start index (inclusive)
end (number): end index (exclusive)

Returns

list

reverse

returns a new list with elements in reversed order.

Allowed number of parameters: 1–1

Parameters

list (list): list to reverse

Returns

list

append

appends items to a list and return the extended list. The original list stays unharmed.

Allowed number of parameters: 1–10000

Parameters

list (list): base list
item... (any): items to add (variadic)

Returns

list

append_unique

appends items to a list but only if they are new. The original list stays unharmed.

Allowed number of parameters: 1–10000

Parameters

list (list): base list
item... (any): items to add (variadic)

Returns

list

cons

constructs a list from a head and a tail list

Allowed number of parameters: 2–2

Parameters

car (any): new head element
cdr (list): tail that is appended after car

Returns

list

car

extracts the head of a list

Allowed number of parameters: 1–1

Parameters

list (list): list

Returns

any

cdr

extracts the tail of a list The tail of a list is a list with all items except the head.

Allowed number of parameters: 1–1

Parameters

list (list): list

Returns

list

cadr

extracts the second element of a list. Equivalent to (car (cdr x)).

Allowed number of parameters: 1–1

Parameters

list (list): list

Returns

any

zip

swaps the dimension of a list of lists. If one parameter is given, it is a list of lists that is flattened. If multiple parameters are given, they are treated as the components that will be zipped into the sub list

Allowed number of parameters: 0–10000

Parameters

list (any): list of lists of items (variadic)

Returns

list

merge

flattens a list of lists into a list containing all the subitems. If one parameter is given, it is a list of lists that is flattened. If multiple parameters are given, they are treated as lists that will be merged into one

Allowed number of parameters: 0–10000

Parameters

list (any): list of lists of items (variadic)

Returns

list

merge_unique

flattens a list of lists into a list containing all the subitems. Duplicates are filtered out.

Allowed number of parameters: 0–10000

Parameters

list (list): list of lists of items (variadic)

Returns

list

has?

checks if a list has a certain item (equal?)

Allowed number of parameters: 2–2

Parameters

haystack (list): list to search in
needle (any): item to search for

Returns

bool

filter

returns a list that only contains elements that pass the filter function

Allowed number of parameters: 2–2

Parameters

list (list): list that has to be filtered
condition (func(item:any) -> bool): filter condition func(item)->bool

Returns

list

find

returns the first list element that passes the condition function, or nil/default if none matches

Allowed number of parameters: 2–3

Parameters

list (list): list to search
condition (func(item:any) -> bool): predicate func(any)->bool that is applied until the first match
default (any): optional default value if nothing matches (optional)

Returns

any

map

returns a list that contains the results of a map function that is applied to the list

Allowed number of parameters: 2–2

Parameters

list (list): list that has to be mapped
map (func(item:any) -> any): map function func(any)->any that is applied to each item

Returns

list

parallel_map

like map, but applies fn to each element in parallel using a worker pool limited to runtime.NumCPU()

Allowed number of parameters: 2–2

Parameters

list (list): list to map over in parallel
fn (func(item:any) -> any): function applied to each element

Returns

list

parallel_map_mut

like parallel_map, but signals the optimizer that fn may have side effects

Allowed number of parameters: 2–2

Parameters

list (list): list to map over in parallel
fn (func(item:any) -> any): function with side effects applied to each element

Returns

list

mapIndex

returns a list that contains the results of a map function that is applied to the list

Allowed number of parameters: 2–2

Parameters

list (list): list that has to be mapped
map (func(index:int, item:any) -> any): map function func(i, any)->any that is applied to each item

Returns

list

reduce

returns a list that contains the result of a map function

Allowed number of parameters: 2–3

Parameters

list (list): list that has to be reduced
reduce (func(acc:any, item:any) -> any): reduce function func(any any)->any where the first parameter is the accumulator, the second is a list item
neutral (any): (optional) initial value of the accumulator, defaults to nil (optional)

Returns

any

produce

returns a list that contains produced items - it works like for(state = startstate, condition(state), state = iterator(state)) {yield state}

Allowed number of parameters: 3–3

Parameters

startstate (any): start state to begin with
condition (func(state:any) -> bool): func that returns true whether the state will be inserted into the result or the loop is stopped
iterator (func(state:any) -> any): func that produces the next state

Returns

list

produceN

returns a list with numbers from 0..n-1, optionally mapped through a function

Allowed number of parameters: 1–2

Parameters

n (number): number of elements to produce
fn (func(index:int) -> any): (optional) map function applied to each index (optional)

Returns

list

parallelN

returns a list with numbers from 0..n-1 mapped in parallel through a function

Allowed number of parameters: 2–2

Parameters

n (number): number of elements to produce
fn (func(index:int) -> any): map function applied to each index in parallel

Returns

list

list?

checks if a value is a list

Allowed number of parameters: 1–1

Parameters

value (any): value to check

Returns

bool

contains?

checks if a value is in a list; uses the equal?? operator

Allowed number of parameters: 2–2

Parameters

list (list): list to check
value (any): value to check

Returns

bool

sql_in

tests SQL IN-list membership and returns nil when NULL makes the result UNKNOWN

Allowed number of parameters: 2–2

Parameters

values (list): SQL IN-list values
value (any): value to find

Returns

bool