Package COM.INFORMATIMAGO.COMMON-LISP.CESARUM.ARRAY

This package exports a few array utility functions.
    

License:

    AGPL3
    
    Copyright Pascal J. Bourguignon 2005 - 2012
    
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
    
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.
    
    You should have received a copy of the GNU Affero General Public License
    along with this program.
    If not, see <http://www.gnu.org/licenses/>

(array-equal-p a1 a2)
function
RETURN: A1 and A2 have the same dimensions (or the same length in
case of vectors) and their elements in the same position are = if
numbers, or equal otherwise.
(array-to-list array)
function
RETURN:     A list (of list)* containing the elements of the array.

EXAMPLE:    (array-to-list #3A(((1 2 3) (4 5 6)) ((a b c) (d e f))))
            --> (((1 2 3) (4 5 6)) ((a b c) (d e f)))
(copy-array array &key copy-fill-pointer copy-adjustable copy-displacement)
function
RETURN:             A copy of the ARRAY.
ARRAY:              An array.
COPY-FILL-POINTER:  Indicate whether the copy must have the same
                    FILL-POINTER as the ARRAY.
COPY-ADJUSTABLE:    Indicate whether the copy must be an adjustable
                    array when the ARRAY is adjustable.
COPY-DISPLACEMENT:  Indicate whether the copy must be an array
                    displaced to the same array as the ARRAY.
(displaced-vector array &optional start end fill-pointer)
function
DO:         When array is a vector, same as SUBSEQ but with a displaced array.

            When the rank of array is different from 1, then creates
            a displaced vector onto ARRAY.   In that case the optional
            arguments are ignored.

RETURN:     A new displaced vector.
SEE ALSO:   COM.INFORMATIMAGO.COMMON-LISP.CESARUM.UTILITY:NSUBSEQ
(nudge-displaced-vector displaced-vector &key start start+ start- end end+ end- length length+ length- fill-pointer)
function
DO:             Changes the displacement of the DISPLACED-VECTOR.
START:          Indicates the new absolute displacement offset.
START+:         Indicates an increment of the displacement offset.
START-:         Indicates a decrement of the displacement offset.
END:            Indicates the new absolute end of the DISPLACED-VECTOR.
END+:           Indicates an increment of the DISPLACED-VECTOR end.
END-:           Indicates a decrement of the DISPLACED-VECTOR end.
LENGTH:         Indicates the new absolute length of the DISPLACED-VECTOR.
LENGTH+:        Indicates an increment of the length of the DISPLACED-VECTOR.
LENGTH-:        Indicates a decrement of the length of the DISPLACED-VECTOR.
FILL-POINTER:   Indicates the new fill pointer for the DISPLACED-VECTOR.
NOTES:          START, START+ and START- are mutually exclusive.
                END, END+, END-, LENGTH, LENGTH+ and LENGTH- are mutually exclusive.
                START and END are expressed as indices in the displaced-to array.
RETURN:         The adjusted array.

EXAMPLE:        (let* ((s #(a door a window a big hole and a bucket))
                            (v (displaced-vector s 0 3 t)))
                       (show v)
                       (show (nudge-displaced-vector v :end+   1))
                       (show (nudge-displaced-vector v :fill-pointer 2))
                       (show (nudge-displaced-vector v :start+ 3 :end+ 3))
                       (show (nudge-displaced-vector v :start- 1 :end- 1))
                       (show (nudge-displaced-vector v :fill-pointer 1)))
                prints:
                    v = #(a door a)
                    (nudge-displaced-vector v :end+ 1) = #(a door a)
                    (nudge-displaced-vector v :fill-pointer 2) = #(a door)
                    (nudge-displaced-vector v :start+ 3 :end+ 3) = #(window a)
                    (nudge-displaced-vector v :start- 1 :end- 1) = #(a window)
                    (nudge-displaced-vector v :fill-pointer 1) = #(a)
                    #(a)
(positions item vector &key from-end test test-not start end count key)
function
RETURN:     A list of indices of the occurences of ITEM in the VECTOR.
            The occurences are defined by the ITEM, TEST, TEST-NOT,
            KEY, START, END, FROM-END and COUNT parameters as in
            DELETE.

EXAMPLE:    (positions 'a #(a door a window a big hole and a bucket) :start 1)
            ==> (2 4 8)
(vector-butlast vector)
function
RETURN: A displaced, adjustable array, with fill-pointer, covering all the elements of the VECTOR but the last.
(vector-delete item vector &rest keys &key from-end test test-not start end count key)
function
DO:         Delete occurences of ITEM from the VECTOR.  The occurences
            are defined by the ITEM, TEST, TEST-NOT, KEY, START, END,
            FROM-END and COUNT parameters as in DELETE.

            The deletion is performed by moving the elements down, and
            updating the fill-pointer of the VECTOR.  If the VECTOR
            doesn't have a fill-pointer, then DELETE is called
            instead.

RETURN:     VECTOR if it has a fill-pointer, or the result of DELETE
            otherwise.

EXAMPLE:    (let ((v (make-array 10
                            :initial-contents #(a door a window a big hole and a bucket)
                            :fill-pointer t)))
                       (list v (vector-delete 'a v :count 3) (fill-pointer v)))
            --> (#1=#(door window big hole and a bucket) #1# 7)
(vector-emptyp vector)
function
RETURN:  Whether the vector is empty.
(vector-first vector)
function
RETURN: The first element of the vector, or 0 values if empty.
(vector-last vector)
function
RETURN: The last element of the vector, or 0 values if empty.
(vector-rest vector)
function
RETURN: A displaced, adjustable array, with fill-pointer,  covering all the elements of the VECTOR but the first.