Fcalva/cyclone
1
0
Fork 0
mirror of https://github.com/justinethier/cyclone.git synced 2025-05-23 20:15:05 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Finished initial set of docs

Browse source
This commit is contained in:
Justin Ethier 2016-12-09 23:20:26 -05:00
parent 3c1b068249
commit ede2c38bf3
1 changed files with 209 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

212
docs/api/srfi/1.md
View file

@ -123,6 +123,7 @@ See the [SRFI document](http://srfi.schemers.org/srfi-1/srfi-1.html) for more in
[`lset-intersection!`](#lset-intersection-1)
[`lset-difference!`](#lset-difference-1)
[`lset-xor!`](#lset-xor-1)
[`lset-diff+intersection!`](#lset-diffintersection-1)
# xcons
@ -576,6 +577,12 @@ The last element of the input list may be any value at all.
`concatenate!` is the linear-update variant of `concatenate`.
# reverse!
(reverse! list)
`reverse!` is the linear-update variant of `reverse`. It is permitted, but not required, to alter the argument's cons cells to produce the reversed list.
# fold
(fold kons knil clist1 clist2 ...)
@ -1096,43 +1103,242 @@ The iteration stops when one of the lists runs out of values; in this case, list
# delete
(delete x list)
(delete x list =)
`delete` uses the comparison procedure `=`, which defaults to `equal?`, to find all elements of list that are equal to `x`, and deletes them from list. The dynamic order in which the various applications of = are made is not specified.
The list is not disordered -- elements that appear in the result list occur in the same order as they occur in the argument list. The result may share a common tail with the argument list.
Note that fully general element deletion can be performed with the remove and remove! procedures, e.g.:
;; Delete all the even elements from LIS:
(remove even? lis)
The comparison procedure is used in this way: `(= x ei)`. That is, `x` is always the first argument, and a list element is always the second argument. The comparison procedure will be used to compare each element of list exactly once; the order in which it is applied to the various ei is not specified. Thus, one can reliably remove all the numbers greater than five from a list with `(delete 5 list <)`
# delete!
# alist-cons
(delete! x list)
(delete! x list =)
# alist-copy
`delete!` is the linear-update variant of `delete`. It is allowed, but not required, to alter the cons cells in its argument list to construct the result.
# delete-duplicates
(delete-duplicates list)
(delete-duplicates list =)
`delete-duplicates` removes duplicate elements from the `list` argument. If there are multiple equal elements in the argument list, the result list only contains the first or leftmost of these elements in the result. The order of these surviving elements is the same as in the original list -- delete-duplicates does not disorder the list (hence it is useful for "cleaning up" association lists).
The `=` parameter is used to compare the elements of the list; it defaults to `equal?`. If `x` comes before `y` in list, then the comparison is performed `(= x y)`. The comparison procedure will be used to compare each pair of elements in list no more than once; the order in which it is applied to the various pairs is not specified.
Implementations of `delete-duplicates` are allowed to share common tails between argument and result lists -- for example, if the list argument contains only unique elements, it may simply return exactly this list.
Be aware that, in general, `delete-duplicates` runs in time O(n2) for n-element lists. Uniquifying long lists can be accomplished in O(n lg n) time by sorting the list to bring equal elements together, then using a linear-time algorithm to remove equal elements. Alternatively, one can use algorithms based on element-marking, with linear-time results.
(delete-duplicates '(a b a c a b c z)) => (a b c z)
;; Clean up an alist:
(delete-duplicates '((a . 3) (b . 7) (a . 9) (c . 1))
(lambda (x y) (eq? (car x) (car y))))
=> ((a . 3) (b . 7) (c . 1))
# delete-duplicates!
(delete-duplicates! list)
(delete-duplicates! list =)
`delete-duplicates!` is the linear-update variant of `delete-duplicates`; it is allowed, but not required, to alter the cons cells in its argument list to construct the result.
# alist-cons
(alist-cons key datum alist)
Cons a new alist entry mapping `key` -> `datum` onto `alist`.
This function is equivalent to:
(lambda (key datum alist) (cons (cons key datum) alist))
# alist-copy
(alist-copy alist)
Make a fresh copy of `alist`. This means copying each pair that forms an association as well as the spine of the list, i.e.
(lambda (a) (map (lambda (elt) (cons (car elt) (cdr elt))) a))
# alist-delete
(alist-delete key alist)
(alist-delete key alist =)
`alist-delete` deletes all associations from `alist` with the given key, using key-comparison procedure `=`, which defaults to `equal?`. The dynamic order in which the various applications of = are made is not specified.
Return values may share common tails with the alist argument. The alist is not disordered -- elements that appear in the result alist occur in the same order as they occur in the argument `alist`.
The comparison procedure is used to compare the element keys ki of alist's entries to the key parameter in this way: `(= key ki)`. Thus, one can reliably remove all entries of alist whose key is greater than five with `(alist-delete 5 alist <)`
# alist-delete!
# reverse!
(alist-delete! key alist)
(alist-delete! key alist =)
`alist-delete!` is the linear-update variant of `alist-delete`. It is allowed, but not required, to alter cons cells from the alist parameter to construct the result.
# lset<=
(lset<= = list1 ...)
Returns true iff every listi is a subset of listi+1, using = for the element-equality procedure. List A is a subset of list B if every element in A is equal to some element of B. When performing an element comparison, the = procedure's first argument is an element of A; its second, an element of B.
(lset<= eq? '(a) '(a b a) '(a b c c)) => #t
(lset<= eq?) => #t ; Trivial cases
(lset<= eq? '(a)) => #t
# lset=
(lset= = list1 list2 ...)
Returns true iff every listi is set-equal to listi+1, using = for the element-equality procedure. "Set-equal" simply means that listi is a subset of listi+1, and listi+1 is a subset of listi. The = procedure's first argument is an element of listi; its second is an element of listi+1.
(lset= eq? '(b e a) '(a e b) '(e e b a)) => #t
(lset= eq?) => #t ; Trivial cases
(lset= eq? '(a)) => #t
# lset-adjoin
(lset-adjoin = list elt1 ...)
Adds the elti elements not already in the list parameter to the result list. The result shares a common tail with the list parameter. The new elements are added to the front of the list, but no guarantees are made about their order. The = parameter is an equality procedure used to determine if an elti is already a member of list. Its first argument is an element of list; its second is one of the elti.
The list parameter is always a suffix of the result -- even if the list parameter contains repeated elements, these are not reduced.
(lset-adjoin eq? '(a b c d c e) 'a 'e 'i 'o 'u) => (u o i a b c d c e)
# lset-union
(lset-union = list1 ...)
Returns the union of the lists, using = for the element-equality procedure.
The union of lists A and B is constructed as follows:
- If A is the empty list, the answer is B (or a copy of B).
- Otherwise, the result is initialised to be list A (or a copy of A).
- Proceed through the elements of list B in a left-to-right order. If b is such an element of B, compare every element r of the current result list to b: (= r b). If all comparisons fail, b is consed onto the front of the result.
However, there is no guarantee that = will be applied to every pair of arguments from A and B. In particular, if A is eq? to B, the operation may immediately terminate.
In the n-ary case, the two-argument list-union operation is simply folded across the argument lists.
(lset-union eq? '(a b c d e) '(a e i o u)) =>
(u o i a b c d e)
;; Repeated elements in LIST1 are preserved.
(lset-union eq? '(a a c) '(x a x)) => (x a a c)
;; Trivial cases
(lset-union eq?) => ()
(lset-union eq? '(a b c)) => (a b c)
# lset-intersection
(lset-intersection = list1 list2 ...)
Returns the intersection of the lists, using = for the element-equality procedure.
The intersection of lists A and B is comprised of every element of A that is = to some element of B: (= a b), for a in A, and b in B. Note this implies that an element which appears in B and multiple times in list A will also appear multiple times in the result.
The order in which elements appear in the result is the same as they appear in list1 -- that is, lset-intersection essentially filters list1, without disarranging element order. The result may share a common tail with list1.
In the n-ary case, the two-argument list-intersection operation is simply folded across the argument lists. However, the dynamic order in which the applications of = are made is not specified. The procedure may check an element of list1 for membership in every other list before proceeding to consider the next element of list1, or it may completely intersect list1 and list2 before proceeding to list3, or it may go about its work in some third order.
(lset-intersection eq? '(a b c d e) '(a e i o u)) => (a e)
;; Repeated elements in LIST1 are preserved.
(lset-intersection eq? '(a x y a) '(x a x z)) => '(a x a)
(lset-intersection eq? '(a b c)) => (a b c) ; Trivial case
# lset-difference
(lset-difference = list1 list2 ...)
Returns the difference of the lists, using = for the element-equality procedure -- all the elements of list1 that are not = to any element from one of the other listi parameters.
The = procedure's first argument is always an element of list1; its second is an element of one of the other listi. Elements that are repeated multiple times in the list1 parameter will occur multiple times in the result. The order in which elements appear in the result is the same as they appear in list1 -- that is, lset-difference essentially filters list1, without disarranging element order. The result may share a common tail with list1. The dynamic order in which the applications of = are made is not specified. The procedure may check an element of list1 for membership in every other list before proceeding to consider the next element of list1, or it may completely compute the difference of list1 and list2 before proceeding to list3, or it may go about its work in some third order.
(lset-difference eq? '(a b c d e) '(a e i o u)) => (b c d)
(lset-difference eq? '(a b c)) => (a b c) ; Trivial case
# lset-xor
(lset-xor = list1 ...)
Returns the exclusive-or of the sets, using = for the element-equality procedure. If there are exactly two lists, this is all the elements that appear in exactly one of the two lists. The operation is associative, and thus extends to the n-ary case -- the elements that appear in an odd number of the lists. The result may share a common tail with any of the listi parameters.
More precisely, for two lists A and B, A xor B is a list of
every element a of A such that there is no element b of B such that (= a b), and
every element b of B such that there is no element a of A such that (= b a).
However, an implementation is allowed to assume that = is symmetric -- that is, that
(= a b) => (= b a).
This means, for example, that if a comparison (= a b) produces true for some a in A and b in B, both a and b may be removed from inclusion in the result.
In the n-ary case, the binary-xor operation is simply folded across the lists.
(lset-xor eq? '(a b c d e) '(a e i o u)) => (d c b i o u)
;; Trivial cases.
(lset-xor eq?) => ()
(lset-xor eq? '(a b c d e)) => (a b c d e)
# lset-diff+intersection
(lset-diff+intersection = list1 list2 ...)
Returns two values -- the difference and the intersection of the lists. Is equivalent to
(values (lset-difference = list1 list2 ...)
(lset-intersection = list1
(lset-union = list2 ...)))
but can be implemented more efficiently.
The `=` procedure's first argument is an element of list1; its second is an element of one of the other listi.
Either of the answer lists may share a common tail with list1. This operation essentially partitions list1.
# lset-union!
(lset-union! = list1 ...)
This is the linear-update variant. It is allowed, but not required, to use the cons cells in their first list parameter to construct their answer.
`lset-union!` is permitted to recycle cons cells from any of its list arguments.
# lset-intersection!
(lset-intersection! = list1 list2)
This is the linear-update variant. It is allowed, but not required, to use the cons cells in their first list parameter to construct their answer.
# lset-difference!
(lset-difference! = list1 list2)
This is the linear-update variant. It is allowed, but not required, to use the cons cells in their first list parameter to construct their answer.
# lset-xor!
(lset-xor! = list1 ...)
This is the linear-update variant. It is allowed, but not required, to use the cons cells in their first list parameter to construct their answer.
# lset-diff+intersection!
(lset-diff+intersection! = list1 list2 ...)
This is the linear-update variant. It is allowed, but not required, to use the cons cells in their first list parameter to construct their answer.