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

This package exports a few array utility functions.


License:

    AGPL3

    Copyright Pascal J. Bourguignon 2005 - 2018

    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)
(positions-of-subsequence subsequence vector &key from-end test test-not start1 end1 start2 end2 count key)
function

RETURN:     A list of cons cells containing the start and end of the
            occurences of (subseq SUBSEQUENCE START1 END1) in the
            VECTOR between START2 and END2.

            The occurences are defined by the SUBSEQUENCE, START1,
            START2, TEST, TEST-NOT, KEY, START2, END2, as in SEARCH,
            and the FROM-END and COUNT parameters as in DELETE.

(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.