2017-08-27

(sph list)

helpers for working with lists

part of sph-lib

highlights

map-slice, map-segments, iterate-three, produce, split-by-pattern, fold-multiple, list-index-value, list-sort-with-accessor, ...

import name

(sph list)

exports

any->list

procedure

signature

a ->

any -> list

description

wraps a non-list argument in a list

any->list-s

syntax

signature

a

compact

procedure

signature

a ->

list -> list

description

keep only true elements in list. removes all boolean false values

complement

procedure

signature

lists ... ->

list ... -> list

description

delete elements from the first list that are included in the other lists

complement-both

procedure

signature

a b ->

list list -> (list list)

description

delete elements in both lists that are included in both lists

complement-p

procedure

signature

= list1 rest ... ->

consecutive

procedure

signature

f a [c] ->

procedure:{any -> any/boolean} list [procedure] -> (list:matches list:rest)

description

splits the list into two lists, the first being a list of all beginning elements of "a" that consecutively matched

"f", the second being the rest.

like srfi-1 span but the result is a list and not multiple return values

contains-all?

procedure

signature

a values ->

list ... -> boolean

description

test if argument "a" contains all of the given values

contains-some?

procedure

signature

a values ->

list ... -> boolean

description

test if argument "a" contains any of the given values

contains?

procedure

signature

a value [member] ->

list any [procedure:{any list -> boolean/any}] -> boolean

description

return a boolean indicating if list "a" contains "value"

containsq?

procedure

signature

a value ->

containsv-some?

procedure

signature

a values ->

list ... -> boolean

description

test if argument "a" contains any of the given values

containsv?

procedure

signature

a value ->

convolve

procedure

signature

a b ->

list list -> list

description

returns the discrete, linear convolution of two one-dimensional sequences.

the length of the result will be (a-length + b-length - 1).

example use case: modelling the effect of a linear time-invariant system on a signal

count-value

procedure

signature

value a [equal?] ->

any list -> integer

description

count occurences of "value" in list

count-value-with-limit

procedure

signature

value a [count-limit member] ->

any list [integer procedure:{any list -> boolean/any}] -> integer

description

like count-value but with an optional parameter for a count at which to stop counting

count-with-limit

procedure

signature

pred limit a ... ->

procedure integer list ... -> integer

description

like "count" but with an optional parameter for a count at which to stop counting

define-list

syntax

signature

name a ...

delete-duplicates-sorted

procedure

signature

a [equal-f preserve-order] ->

list [procedure:{any any -> boolean} boolean] -> list

description

delete duplicates from a sorted list using a more efficient algorithm than for unsorted lists

difference

procedure

signature

lists ... ->

list ... -> list

description

result in a list of elements not included in all given lists

difference+intersection

procedure

signature

lists ... ->

list ... -> (list list)

description

results in a list with two elements, one being the symmetric-difference between the given lists and one being the intersection.

that means one list of all elements that are included in all lists, and one list of elements that are not included in all lists.

it does both calculations in one step saving resources compared to making them in separate steps.

difference+intersection-p

procedure

signature

equal-f lists ... ->

{any any -> boolean} list ... -> (list:difference list:intersection)

description

like difference+intersection but the predicate for comparing list elements can be specified

difference-p

procedure

signature

equal-f lists ... ->

{any any -> boolean} list ... -> list

description

like

drop*

procedure

signature

count a ->

description

like srfi-1 drop but with reversed argument order (like stream-drop from srfi-41) and

returns null if list contains less elements than count instead of raising an exception

each-first-middle-last

procedure

signature

first-f middle-f last-f a ... ->

procedure procedure procedure list ... ->

description

untested.

call "first-f" for the first element,

call "last-f" for the last element,

call "middle-f" for a list of all elements inbetween

each-in-index-range

procedure

signature

f start end a ... ->

procedure integer integer list ... ->

description

untested.

call f only for elements in index range between "start" and "end" inclusively

each-slice

procedure

signature

f slice-length a ->

procedure:{list ->} integer list ->

description

apply f to each slice of slice-length elements from list.

each-with-index

procedure

signature

f a ... ->

procedure:{index element ... ->} list ... ->

description

apply f to each element and its index in list a

every-map

procedure

signature

f a ... ->

procedure:{any -> any} list ... -> list/false

description

like map but results in false if any result of f is not a true value

every-or-index

procedure

signature

f a ... ->

procedure:{any ... -> boolean} list ... -> true/integer

description

true if "f" is true for all elements, otherwise the index of the element for which "f" failed

false-if-null

procedure

signature

a ->

filter-append-map

procedure

signature

f lists ... ->

description

apply filter-map and then apply append on the result

filter-not

procedure

signature

f a ->

{any -> boolean} list -> list

description

like filter but keeps only values where the result of f is false.

same as (filter (compose not f) list)

filter-produce

procedure

signature

f a ... ->

description

procedure list ...

apply "f" to each ordered combination of elements from lists, cartesian product, and return true results in a list.

supports multiple lists and treats non-list arguments as the single element of a list.

example:

(produce f (1 2) (4 5) 6)

is equivalent to

(list (f 1 4 6) (f 1 5 6) (f 2 4 6) (f 2 5 6))

first-if-single

procedure

signature

a ->

list -> any/list

description

give the first element of a list if the list has only one element, otherwise give the list

first-intersection

procedure

signature

a b ->

list list -> any

description

give the first found element that is included in both lists

first-intersection-p

procedure

signature

equal-f a b ->

{any any -> boolean} list list -> any

description

like first-intersection but the procedure for comparing elements can be specified

first-or-false

procedure

signature

a ->

list -> any/false

description

give the first element of a list if it is not null, otherwise false

first-or-null

procedure

signature

a ->

description

results in the first element of a list if it is not null, otherwise null

flat?

procedure

signature

a ->

list -> boolean

description

true if the list does not contain a list

flatten

procedure

signature

a ->

list -> (non-list ...)

description

replace sublists with their content, resulting in a list that does not contain lists

fold-integers

procedure

signature

count init f ->

integer {integer -> any} -> list

description

fold over integers from 0 to count - 1

fold-multiple

procedure

signature

f a custom-state-values ... ->

procedure:{any:list-element any:state-value ... -> (any:state-value)} list any:state-value ... -> list:state-values

description

like fold but with multiple state values. the state values are updated by returning a list from a call to "f".

apply "f" to each element of "a" and the state-value elements that were given to

fold-multiple or subsequently the updated state-values from the previous call to "f"

fold-multiple-right

procedure

signature

f a r ... ->

procedure list any ... -> any

description

like fold-multiple but works through the list elements from last to first

fold-multiple-with-continue

procedure

signature

f a custom-state-values ... ->

description

procedure:{any:element procedure:continue:{list:next-pair any:state-value ...} any:state-value ... -> any} list any:state-value ... -> list

fold-segments

procedure

signature

f size init a ->

{any:state element ... -> any:state} integer any:state list -> any

description

fold over each overlapping segment with length "size".

example:

(fold-segments f 2 #t (list 4 5 6 7))

is equivalent to

(f 4 5) (f 5 6) (f 6 7)

fold-slice

procedure

signature

slice-length f init a ->

integer procedure:{any:state any:element ... -> any} any list -> any:state

description

call f with each slice-length number of consecutive elements of a

fold-span

procedure

signature

filter-f f a ->

procedure:{any -> any/false} procedure:{list -> any} list -> any

description

fold over each list of elements that consecutively matched filter-f (utilising the "span" procedure)

fold-unless

procedure

signature

f stop? default init a ... ->

{any ... -> any} {any -> boolean/any} any any list ... -> any

description

like fold, but returns "default" if "stop?" is true

fold-unless-check-init

procedure

signature

f stop? default init a ... ->

fold-until

procedure

signature

f init stop? a ->

procedure any procedure:{any -> boolean} list -> any

description

end folding if "stop?" is true

group-consecutive

procedure

signature

filter-f a ->

{any -> boolean} list -> list

description

wrap multiple elements that consecutively match "filter-f" in a list

group-split-at-matches

procedure

signature

start-group? a ->

procedure:{any -> boolean} list -> (list ...)

description

wrap consecutive elements in lists with "start-group?" starting new lists.

example

(group-inline-prefixed integer? (list "a" "b" 1 "c" "d" 2 "e"))

->

(("a" "b") (1 "c" "d") (2 "e"))

improper-list-split-at-last

procedure

signature

a ->

pair:improper-list -> (list any:non-pair)

(1 2 . 3) -> ((1 2) 3)

insert-second

procedure

signature

e a ->

any list -> list

description

insert "e" as the second element into list "a"

integer->list

procedure

signature

a ->

any -> any/list

description

wrap the argument in a list, but only if it is an integer. otherwise give the argument

interleave

procedure

signature

a value ->

list any -> list

description

inserts value in front of each element in "a" except the first element.

example: (interleave (list 1 2 3) 4) -> (1 4 2 4 3)

intersection

procedure

signature

lists ... ->

list ... -> list

description

result in a list of all elements which are contained in all given lists

intersection-p

procedure

signature

equal-f rest ... ->

procedure:{any any -> boolean} list ... -> list

description

like "intersection" but the predicate for comparing the list elements can be specified

iterate-three

procedure

signature

f a states ... ->

procedure:{list:prev any:current list:next any:state ... -> any:state ...} list any:state-init ... -> list:state

description

calls "f" for each list element, a list of unmodified previous list elements, a list of the following list elements

and an arbitrary count of custom values that are updated to the result of the call to "f"

iterate-three-with-stop+end

procedure

signature

stop? end map-f a states ... ->

{list any list any ... -> boolean} {list any list any ... -> list:state-values}:after-stop? {list any list any ... -> list:state-values} list any ... -> any

description

like "iterate-three" but takes two additional procedures - one for stopping the iteration after a "map-f" result, and one that is called for the last element or when "stop?" is true

length-greater-one?

procedure

signature

a ->

list -> boolean

description

true if list length is greater than one. possibly faster than (> (length a) 1).

has-multiple-elements?

length-one?

procedure

signature

a ->

list -> boolean

description

test if list length equals one. possibly faster than (= (length a) 1).

list-bind

syntax

signature

a lambda-formals body ...

list-deselect

procedure

signature

a indices ->

list (integer ...) -> list

description

return a new, possibly smaller, list consisting of values not at specified indices

list-distribute

procedure

signature

a indices default ->

list (integer ...) any -> list

description

creates a new list with values from list a at positions indices. the value for "no-element" is set at indices

not included in the list indices. the length of indices must equal the length of a, and indices should not have duplicates.

list-distribute-sorted

procedure

signature

a indices default ->

description

like list-distribute but faster. works only correctly for indices lists that are sorted ascending

list-index-value

procedure

signature

a value [equal-f] ->

description

get the index of value in list

list-indices

procedure

signature

f a ->

procedure:{any -> boolean} list -> (integer ...)

description

create a list of all indices for which f results in true

list-let

syntax

signature

a lambda-formals body ...

list-page

procedure

signature

a entry-count number lookahead c ->

list integer integer integer procedure:{list boolean:last-page? -> any} -> any

description

pass a list of "entry-count" elements at an offset of (* number entry-count),

eventually including "lookahead" number of elements if they are the last elements,

and a boolean indicating if it is the last page to continuation procedure "c"

list-prefix?

procedure

signature

a prefix ... ->

list any ... -> boolean

description

true if the given "prefix" elements exist in order at the beginning of list.

examples:

(list-prefix? (list 3 2 4) 3 1) -> #f

(list-prefix? (list 3 2 4) 3 2) -> #t

list-q

syntax

signature

a ...

list-qq

syntax

signature

a ...

list-replace-last

procedure

signature

a replacement ->

list any/procedure:{any -> any} -> list

description

replace the last element in a list.

if replacement is a procedure, it is called with the last element and if the procedure result is a list then the result is appended

list-replace-last-n

procedure

signature

n a replacement ->

list integer any/procedure:{any ... -> any/list} -> list

description

if replacement is a procedure, it is called with the last "n" elements and if the procedure result is a list then the result is appended

list-select

procedure

signature

a indices ->

list (integer ...) -> list

description

return a new list consisting of values at indices

list-set-add

procedure

signature

= list rest ... ->

description

Add to LIST any of the elements of REST not already in the list.

These elements are `cons'ed onto the start of LIST (so the return shares

a common tail with LIST), but the order they're added is unspecified.

The given `=' procedure is used for comparing elements, called

as `(@var{=} listelem elem)', i.e., the second argument is one of the

given REST parameters.

list-set-equal?

procedure

signature

a ... ->

list ... -> boolean

description

true if all elements of the given lists appear in all others.

uses "equal?" for element equality comparison

list-set-eqv?

procedure

signature

a ... ->

list ... -> boolean

description

like "list-set-equal?" but uses "eq?" for element equality comparison

list-set-match-condition?

procedure

signature

a ->

any -> boolean

description

true if "a" is a list-set-match condition

list-set-match-contains?

procedure

signature

a condition ->

list list -> boolean

description

test for value inclusion in list by a possibly nested condition list like ([or/and/not] value/match-condition-tree ...).

example:

(list-set-match-contains? (list 1 2 3) (quote (and 2 3 (or 4 1 5) (not 8)))) -> #t

list-set-match-iterate

procedure

signature

match-one? condition ->

procedure:{any -> boolean} list -> false/any:last-sub-condition-result

description

evaluate a possibly nested condition list like for "list-set-match-contains?".

checking if "match-one?" is true for condition values in their relative condition relationships (for example or, and or not).

if any call to match-one? in a required context (for example "and") is false, false is returned.

"match-one?" is called for each individual element of the "condition" list that is not a condition name prefix symbol,

and its boolean results are automatically used for the condition.

condition: ([or/and/not] value/condition ...)

list-set-subset?

procedure

signature

= rest ... ->

list-sort-by-list

procedure

signature

order a [accessor] ->

list list -> list

description

sort a list so the elements correspond to the order of elements in list "order".

elements not contained in "order" are moved to the end of the result list.

examples:

(list-sort-by-list (list 3 2 4) (list 4 2 3)) -> (3 2 4)

(list-sort-by-list (list 3 2 4) (list 4 5 2 3)) -> (3 2 4 5)

list-sort-with-accessor

procedure

signature

less? accessor a ->

procedure:{any any -> boolean} procedure:{any:list-element -> any} list -> list

description

sort list by calling accessor for each argument before comparison. only the order of elements changes, the individual elements are not changed

list-suffix?

procedure

signature

a suffix ... ->

list any ... -> boolean

description

true if the given "suffix" elements exist in order at the end of list.

see also "list-prefix?"

list-tail-ref

procedure

signature

a b ->

map-apply

procedure

signature

f a ... ->

procedure:{any ... -> any} (list ...) ... -> list

description

like map but the procedure is applied with elements of "a" as arguments.

instead of calling f like (f (list 1 2)) like "map" would do, f is called like (f 1 2)

example

(map-apply f (list (list 1 2) (list 3 4)))

map-c

procedure

signature

f lists ... ->

procedure:{procedure:{any:new-element -> any}:continue any:element ... -> any:last-result} list ... -> list

description

map over list with a procedure that when called with the current map result continues the mapping.

if the procedure is not called, the result of the current call will become the tail of the result list.

maps only the length of the shortest list if multiple lists are given

example

(map-c (l (c a) (if (> 3 a) (c (+ 1 a)) (list))) (list 1 2 3 4 5))

->

(2 3 4)

map-consecutive

procedure

signature

filter-f f a ->

{any -> boolean} {any any ... -> any} list -> list

description

"f" is called for and with every list of elements that consecutively matched "filter-f". at least two elements at a time

map-first

procedure

signature

f a ->

procedure list -> list

description

call "f" for the first element of list and replace the first element in the list with the result of "f".

replace-first

map-fold

procedure

signature

f a init ... ->

procedure list any ... -> list any ...

description

procedure:{(list-element state ...) -> list-element state ...}

combination of map and fold.

call f with each list element and state values, which are set to init for the first call.

each call to f must return a list of: the mapped result element and one

element for the each new value of states.

example: (map-fold (l (a index) (list (+ a index) (+ 1 index))) (list 1 2 3) 0)

map-integers

procedure

signature

count f ->

integer {integer -> any} -> list

description

map over integers from 0 to count - 1

map-map

procedure

signature

f a ... ->

procedure (list ...) ... -> list

description

given a list of lists, maps over the elements of lists.

like (map (l (a) (map f a) a))

map-one

procedure

signature

predicate f a ->

{any -> any}:predicate {any:element -> any} list -> list

description

apply f only to the first element that matches predicate.

all elements that do not match are mapped with the "identity" function

map-segments

procedure

signature

len f a ->

procedure:{any ... -> any} integer list -> list

description

map over each overlapping segment of length len

map-selected

procedure

signature

select? f a ... ->

procedure procedure list ... -> list

description

apply f only to elements for which "select?" is true. non-matched items are included in the result list.

if multiple lists are given, it works like "map" except that the elements from the multiple lists for one call that are not selected are saved as a list.

map-some/map-only

map-slice

procedure

signature

slice-length f a ->

integer procedure:{any ... -> any} list -> list

description

call "f" with each "slice-length" number of consecutive elements of "a"

map-span

procedure

signature

filter-f f a ->

procedure:{any -> any/false} procedure:{any any ... -> any} list -> list

description

apply "f" to each list of elements that consecutively matched "filter-f"

map-unless

procedure

signature

f stop? default a ... ->

procedure stop? list -> list/boolean:false

{any -> any} {any -> boolean} list -> list/boolean

description

map unless "stop?" is true for a mapping-result. return an empty list or "default" if "stop?" was true

map-with-index

procedure

signature

f a ... ->

procedure:{integer:index any:element ... -> any} list ... -> list

pair->list

procedure

signature

a ->

pair -> list

pair-bind

syntax

signature

a (b c) body ...

pair-fold-multiple

procedure

signature

f a init ... ->

{pair any -> any} list any ... -> any

description

like fold-multiple but applying f to the pairs of list

pair-map

procedure

signature

f a ->

procedure list -> list

description

like map but not the list elements are passed to "f" but the pairs of the list.

for example (1 2 3) is just another notation for the pair notation (1 . (2 . (3 . ())))

instead of mapping (1 2 3) pair-map maps ((1 2 3) (2 3) (3))

pair-reverse

procedure

signature

a ->

pair -> pair

description

reverse the order of values in a pair.

example: (pair-reverse (pair 1 2)) -> (2 . 1)

pattern-match-min-length

procedure

signature

a ->

list -> integer

description

takes a flat list with symbols and ellipses and counts the required parts of a pattern with

symbols interpreted as matching any element and ellipses to match zero or many occurences of the previous element

produce

procedure

signature

f a ... ->

procedure:{any ... -> any} list ... -> list

description

apply "f" to each ordered combination of elements from all lists, the cartesian product,

and return the results in a list.

for example (produce f (1 2) (4 5) (6)) is equivalent to ((f 1 4 6) (f 1 5 6) (f 2 4 6) (f 2 5 6))

produce-controlled

procedure

signature

f mappers lists ... ->

{any ... -> any} (procedure:{procedure:{any -> any} list -> list} ...) any/list ... -> list

description

experimental.

apply "f" to each ordered combination of elements from one or multiple lists, the cartesian product,

and return the results in a list.

the combinations passed to "f" are obtained by nested application of the procedures in the second argument list.

there should be as many lists as mappers.

accepts multiple lists, multiple mappers and non-list arguments.

example:

(produce-controlled f (f-1 f-2 f-3) (1 2) (4 5) (6 7))

is equivalent to

(f-1 (lambda (e-1) (f-2 (lambda (e-2) (f-3 (lambda (e-3) (f e-1 e-2 e-3)) (6 7))) (4 5))) (1 2))

produce-unless

procedure

signature

f stop? default a b ->

{any any -> any} {any -> boolean} any list list -> false/any

description

produce two lists unless "stop?" is true for a production-result. if stop? is true, result in false

replace

procedure

signature

a select? replacement ->

list procedure any -> list

replace-at-once

procedure

signature

match? f a ->

procedure:{any -> boolean} procedure:{list:matched-elements -> list:replacements} list:source -> list

description

all elements matching "match?" are collected in a list and passed to "f".

the result of "f" is then used to replace the matched elements in source in order

replace-value

procedure

signature

a search-value replacement [equal-f] ->

list any any [procedure:{any any -> boolean}] -> list

simplify

procedure

signature

a ->

any/list -> list/pair/any

list with one element -> element

list with two non-pair elements -> pair

simplify-list

procedure

signature

a ->

list -> list

description

examples:

(((1 2))) -> (1 2)

(((1 2) (3))) -> ((1 2) (3))

removes extra nesting

sph-list-description

variable

splice

procedure

signature

predicate a ->

{list -> boolean} list -> list

description

splice elements that are lists and match predicate

splice-last-list

procedure

signature

a ->

list -> list

description

if the last element is a list, append it to the previous elements.

example: (splice-last-list (1 2 (3 4))) -> (1 2 3 4)

split-at-last

procedure

signature

a ->

list -> (list list)

split-at-value

procedure

signature

a search-value [inclusiveness] ->

list any [symbol:exclusive/inclusive] -> (list:left list:right)

split-by-pattern

procedure

signature

pattern a ->

(symbol symbol/ellipsis:... ...) list -> (list:matches list:rest)

description

basic, fast pattern matcher that only supports variables and possibly multiple ellipses.

binds values of list "a" to variables in pattern if pattern matches.

the result is a list with two values: one for the match and one for the unmatched rest.

if pattern did not match, then both values are false.

unlike other pattern matchers, "pattern" is a list and not syntax and so can be passed as a variable

tail-or-null

procedure

signature

a ->

list -> list

take*

procedure

signature

count a ->

description

like srfi-1 take but with reversed argument order (like stream-take from srfi-41) and

returns null if list contains less elements than count instead of raising an exception

true->list

procedure

signature

a ->

any -> list/false

description

wraps a true non-list argument in a list

true->list-s

syntax

signature

a

union

procedure

signature

a ... ->


tags: programming guile documentation library scheme sph-lib list sph-list