array utils
1.3.0A few utilities for working with arrays.
About ArrayUtils
A miniature toolkit that contains some useful shifting/popping/pushing functions for arrays and vectors. This exists mostly because I've used these functions in multiple places already, so splitting it off into its own thing is a good idea. Originally from Plump.
System Information
Definition Index

ARRAYUTILS
 ORG.SHIRAKUMO.ARRAYUTILS
No documentation provided.
EXTERNAL FUNCTION ARRAYSHIFT
 ARRAY
 &KEY
 N
 FROM
 TO
 ADJUST
 FILL
 CONTENTS
Shifts a subset of array elements in either direction for a specified amount. Optionally also extends the array and fills empty space with a given element. N  The amount to be moved. If positive, things are shifted to the right. If negative, things are shifted to the left. FROM  The left point of the region to move, inclusive. TO  The right point of the region to move, exclusive. ADJUST  Whether to adjust the fill pointer and the array bounds. The array is only adjusted if N is positive and the range of TO+N would exceed the ARRAY length, or if N is negative and TO equals the length of the ARRAY FILL  If provided, empty spaces created by the move will be filled with this element. CONTENTS  If provided, uses the contents to fill the new space. If N is greater than the length of this sequence, FILL is used to fill the rest of the space if it is provided. If not, an error is signalled. No matter whether N is negative or positive, the content is filled in from left to right in the order it is given.

EXTERNAL FUNCTION ENSUREARRAYSIZE
 ARRAY
 NEWSPACE
No documentation provided. 
EXTERNAL FUNCTION NSLICE
 VECTOR
 &OPTIONAL
 START
 END
 STEP
Modifies the vector to a subvector of itself. START  If positive: the inclusive starting index of the slice If negative: the inclusive starting index of the slice from the end of the vector If NULL: same as zero END  If positive: the exclusive ending index of the slice If negative: the exclusive ending index of the slice from the end of the vector. If NULL: same as the length of the vector STEP  If above zero: the step size between elements of the slice If NULL: same as one Note that this always modifies the passed vector, and adjusts the fill pointer, if one is present. See NSLICE See SLICE*

EXTERNAL FUNCTION SLICE
 VECTOR
 &OPTIONAL
 START
 END
 STEP
Creates a subvector of the given vector. START  If positive: the inclusive starting index of the slice If negative: the inclusive starting index of the slice from the end of the vector If NULL: same as zero END  If positive: the exclusive ending index of the slice If negative: the exclusive ending index of the slice from the end of the vector. If NULL: same as the length of the vector STEP  If above zero: the step size between elements of the slice If NULL: same as one Note that this always creates a fresh copy of the vector, preserving the element type and other properties. See NSLICE See SLICE*

EXTERNAL FUNCTION SLICE*
 VECTOR
 &OPTIONAL
 START
 END
Creates a subvector of the given vector. START  If positive: the inclusive starting index of the slice If negative: the inclusive starting index of the slice from the end of the vector If NULL: same as zero END  If positive: the exclusive ending index of the slice If negative: the exclusive ending index of the slice from the end of the vector. If NULL: same as the length of the vector Note that this creates a displaced vector pointing to the original vector. It thus shares the data with the original vector, and does not support a STEP size other than 1. See SLICE See NSLICE

EXTERNAL FUNCTION VECTORAPPEND
 VECTOR
 SEQUENCE
 &OPTIONAL
 POSITION
Appends all elements of the sequence at position of the vector and returns it. This is potentially very costly as all elements after the given position need to be shifted back as per ARRAYSHIFT.

EXTERNAL FUNCTION VECTORPOPELEMENT
 VECTOR
 ELEMENT
Pops the element from the vector and returns it if it was contained. This is potentially very costly as all elements after the given position need to be shifted back as per ARRAYSHIFT. If the array has an elementtype of T, the element moved beyond the fill pointer is set to NIL to avoid a memory leak. See VECTORPOPPOSITION See VECTORPOPELEMENT*

EXTERNAL FUNCTION VECTORPOPELEMENT*
 VECTOR
 ELEMENT
Pops the element from the vector and returns it if it was contained. This is faster than VECTORPOPELEMENT, but does not preserve the order of elements in the vector. If the array has an elementtype of T, the element moved beyond the fill pointer is set to NIL to avoid a memory leak. See VECTORPOPPOSITION* See VECTORPOPELEMENT

EXTERNAL FUNCTION VECTORPOPFRONT
 VECTOR
Pops the first element off the vector and returns it. This operation is very costly and takes O(n) time as each element needs to be shifted as per ARRAYSHIFT. See VECTORPOPFRONT* See VECTORPOPPOSITION

EXTERNAL FUNCTION VECTORPOPFRONT*
 VECTOR
Pops the first element off the vector and returns it. This is faster than VECTORPOPFRONT, but does not preserve the order of elements in the vector. See VECTORPOPFRONT See VECTORPOPPOSITION

EXTERNAL FUNCTION VECTORPOPPOSITION
 VECTOR
 POSITION
Pops the element at the given position of the vector and returns it. This is potentially very costly as all elements after the given position need to be shifted back as per ARRAYSHIFT. If the array has an elementtype of T, the element moved beyond the fill pointer is set to NIL to avoid a memory leak. See VECTORPOPPOSITION*

EXTERNAL FUNCTION VECTORPOPPOSITION*
 VECTOR
 POSITION
Pops the element at the given position of the vector and returns it. This is faster than VECTORPOPPOSITION, but does not preserve the order of elements in the vector. If the array has an elementtype of T, the element moved beyond the fill pointer is set to NIL to avoid a memory leak. See VECTORPOPPOSITION

EXTERNAL FUNCTION VECTORPUSHEXTENDFRONT
 ELEMENT
 VECTOR
Pushes the element onto the front of the vector and extends if necessary. This operation is very costly and takes O(n) time as each element needs to be shifted as per ARRAYSHIFT. See VECTORPUSHEXTENDPOSITION

EXTERNAL FUNCTION VECTORPUSHEXTENDNEW
 ELEMENT
 VECTOR
 &KEY
 KEY
 TEST
 TESTNOT
Pushes the element onto the back of the vector and extends if necessary, if it is not already part of the vector. If TEST is passed, it is used to compare the elements. Defaults to EQL If TESTNOT is passed, its complement is used to compare the element. If KEY is passed, it is used to extract the element comparison key for both ELEMENT and each element in VECTOR. Returns the existing element in VECTOR or the new ELEMENT if it was inserted at the end. See CL:VECTORPUSHEXTEND

EXTERNAL FUNCTION VECTORPUSHEXTENDPOSITION
 ELEMENT
 VECTOR
 POSITION
Pushes the element into the specified position and shifts everything to the right to make space. This is potentially very costly as all elements after the given position need to be shifted as per ARRAYSHIFT.