

                                                                      alter

    FUNCTION
ALTER DESTINATIONS ITEMS                                         [Function]

    Package
    series

    DESCRIPTION

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 only be applied 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.


     SEE ALSO
     about-series
     about-generators

;Copyright 1989 by the Massachusetts Institute of Technology,
;Cambridge, Massachusetts.

;Permission to use, copy, modify, and distribute this software and its
;documentation for any purpose and without fee is hereby granted,
;provided that this copyright and permission notice appear in all
;copies and supporting documentation, and that the name of M.I.T. not
;be used in advertising or publicity pertaining to distribution of the
;software without specific, written prior permission. M.I.T. makes no
;representations about the suitability of this software for any
;purpose.  It is provided "as is" without express or implied warranty.

;    M.I.T. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
;    ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
;    M.I.T. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
;    ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
;    WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
;    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
;    SOFTWARE.



