Common Lisp the Language
2nd Edition
Series that come from scanning data structures such as lists and vectors
are closely linked to these structures. The function
alter can be used to modify the underlying data structure with
reference to the series derived from it. (Conversely
it is possible to
modify a series by destructively modifying the data structure it is derived
from. However
given the lazy evaluation nature of series
the effects of
such modifications can be very hard to predict. As a result
this kind of
modification is inadvisable.)
[Function]
alter destinations items
alter changes the series destinations so that it contains the elements in the series items. More importantly in the manner of setf the data structure that underlies destinations is changed so that if the series destinations were to be regenerated the new values would be obtained. The alteration process stops as soon as either input runs out of elements. The value nil is always returned. In the example below each negative element in a list is replaced with its square.
(let* ((data (list 1 -2 3 4 -5 6)) (x (choose-if #'minusp (scan data)))) (alter x (#M* x x)) data) => (1 4 3 4 25 6)
alter can be applied only to series that are alterable. scan scan-alist scan-multiple scan-plist and scan-lists-of-lists-fringe produce alterable series. However the alterability of the output of scan-lists-of-lists-fringe is incomplete. If scan-lists-of-lists-fringe is applied to an object that is a leaf altering the output series does not change the object.
In general the output of a transducer is alterable as long as the elements of the output come directly from the elements of an input that is alterable. In particular the outputs of choose choose-if split split-if cotruncate until until-if and subseries are alterable as long as the corresponding inputs are alterable.
[Function]
to-alter items alter-fn &rest args
Given a series items to-alter returns an alterable series A containing the same elements. The argument alter-fn is a function. The remaining arguments are all series. Let these series be S1 ... Sn. If there are n arguments after alter-fn alter-fn must accept n+1 inputs. If (alter A B) is later encountered the expression (map-fn t alter-fn B S1 ... Sn) is implicitly evaluated. For each element in B alter-fn should make appropriate changes in the data structure underlying A.
As an example consider the following definition of a series function that scans the elements of a list. Alteration is performed by changing cons cells in the list being scanned.
(defun scan-list (list) (declare (optimizable-series-function)) (let ((sublists (scan-sublists list))) (to-alter (#Mcar sublists) #'(lambda (new parent) (setf (car parent) new)) sublists)))
