11.45 util.list - Additional list library

Module: util.list

This module provides list utility functions which are not in srfi-1 (See section srfi-1 - List library) but generally useful.

See also gauche.collection - Collection framework and gauche.sequence - Sequence framework, for these modules also defines useful generic functions that can be used for lists.

Function: take* list k &optional fill? padding

Returns a list that consists of the first k elements in list, like SRFI-1's take, except this procedure is more tolerant. That is, if list is shorter than k, take* doesn't signals an error. Instead, it returns a copy of list by default (or the optional argument fill? is #f). If fill? is true, padding is added to the result to make its length k. The default value of padding is #f.

(take* '(a b c d) 3) ⇒ (a b c) (take* '(a b c d) 6) ⇒ (a b c d) (take* '(a b c d) 6 #t) ⇒ (a b c d #f #f) (take* '(a b c d) 6 #t 'z) ⇒ (a b c d z z)

Note: For generic subsequence extraction from any sequence, see subseq in Slicing sequence.

Function: drop* list k

Returns a list that the first k elements of list is dropped, like SRFI-1's drop, except this procedure is more tolerant. If list is shorter than k, an empty list is returned.

(drop* '(a b c d) 3) ⇒ (d) (drop* '(a b c d) 5) ⇒ ()

Function: take-right* list k &optional fill? padding

Like take*, but counts from right of list. If needed, padding is added on left of the result.

Function: drop-right* list k

Like drop*, but counts from right of list.

Function: split-at* list k &optional fill? padding

More tolerant version of SRFI-1's split-at. Returns the results of take* and drop*.

(split-at* '(a b c d) 6 #t 'z) ⇒ (a b c d z z) and ()

Function: slices list k &optional fill? padding

Splits list into the sublists (slices) where the length of each slice is k. If the length of list is not a multiple of k, the last slice is dealt in the same way as take*; that is, it is shorter than k by default, or added padding if fill? is true.

(slices '(a b c d e f g) 3) ⇒ ((a b c) (d e f) (g)) (slices '(a b c d e f g) 3 #t 'z) ⇒ ((a b c) (d e f) (g z z))

Function: intersperse item list

Inserts item between elements in the list. (The order of arguments is taken from Haskell's intersperse).

(intersperse '+ '(1 2 3)) ⇒ (1 + 2 + 3) (intersperse '+ '(1)) ⇒ (1) (intersperse '+ '()) ⇒ ()

Macro: cond-list clause …

Construct a list by conditionally adding entries. Each clause has a test and expressions. When its test yields true, the result of associated expression is used to construct the resulting list. When the test yields false, nothing is inserted.

Clause must be either one of the following form:

(test expr …)

Test is evaluated, and when it is true, expr … are evaluated, and the return value becomes a part of the result. If no expr is given, the result of test is used if it is not false.

(test => proc)

Test is evaluated, and when it is true, proc is called with the value, and the return value is used to construct the result.

(test @ expr …)

Like (test expr …), except that the result of the last expr must be a list, and it is spliced into the resulting list, like unquote-splicing.

(test => @ proc)

Like (test => proc), except that the result of proc must be a list, and and it is spliced into the resulting list, like unquote-splicing.

(let ((alist '((x 3) (y -1) (z 6)))) (cond-list ((assoc 'x alist) 'have-x) ((assoc 'w alist) 'have-w) ((assoc 'z alist) => cadr))) ⇒ (have-x 6) (let ((x 2) (y #f) (z 5)) (cond-list (x @ `(:x ,x)) (y @ `(:y ,y)) (z @ `(:z ,z)))) ⇒ (:x 2 :z 5)

Function: alist->hash-table alist &optional cmp

Creates and returns a hash table that has entries of each element in alist, using its car as the key and its cdr as the value. Cmp is a symbol specifying the comparison function of the created hash table; currently eq?, eqv?, equal? and string=? are supported.

Function: hash-table->alist hash-table

(hash-table-map h cons)

Function: rassoc key alist &optional eq-fn

Function: rassq key alist

Function: rassv key alist

Reverse associations—given key is matched to the cdr of each element in alist, instead of the car. Handy to realize bidirectional associative list. Rassoc takes an optional comparison function, whose default is equal?. Rassq and rassv uses eq? and eqv?.

Function: assoc-ref alist key &optional default eq-fn

Function: assq-ref alist key &optional default

Function: assv-ref alist key &optional default

These procedures provide the access to the assoc list symmetric with other *-ref procedures. This captures the common pattern of alist access:

(assoc-ref alist key default eq-fn) ≡ (cond ((assoc key alist eq-fn) => cdr) (else default))))

If default is omitted, #f is used.

Assoc-ref takes an optional comparison function eq-fn, whose default is equal?. Assq-ref and assv-ref uses eq? and eqv?, respectively.

Function: rassoc-ref alist key &optional default eq-fn

Function: rassq-ref alist key &optional default

Function: rassv-ref alist key &optional default

Reverse association version of assoc-ref.

(rassoc-ref alist key default eq-fn) ≡ (cond ((rassoc key alist eq-fn) => car) (else default))))

The meanings of optional arguments are the same as assoc-ref.

Function: assoc-set! alist key val &optional eq-fn

Function: assq-set! alist key val

Function: assv-set! alist key val

Returns an alist who has (key . val) pair added to the alist. If alist already has an element with key, the element's cdr is destructively modified for val. If alist doesn't have an element with key, a new pair is created and appended in front of alist; so you should use the return value to guarantee key-val pair is added.

Assoc-set! takes optional comparison function eq-fn, whose default is equal?. Assq-set! and assv-set! uses eq? and eqv?, respectively.

This document was generated by Shiro Kawai on October, 7 2008 using texi2html 1.78.