array utils

About Array-Utils

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

• ARRAY-UTILS

  • ORG.SHIRAKUMO.ARRAY-UTILS

  No documentation provided.

  • EXTERNAL FUNCTION

    ARRAY-SHIFT

    • ARRAY
    • &KEY
    • N
    • FROM
    • TO
    • ADJUST
    • FILL
    • CONTENTS

    Source

    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

    ENSURE-ARRAY-SIZE

    • ARRAY
    • NEW-SPACE

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    NSLICE

    • VECTOR
    • &OPTIONAL
    • START
    • END
    • STEP

    Source

    Modifies the vector to a sub-vector 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

    Source

    Creates a sub-vector 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

    Source

    Creates a sub-vector 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

    VECTOR-APPEND

    • VECTOR
    • SEQUENCE
    • &OPTIONAL
    • POSITION

    Source

    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 ARRAY-SHIFT.

  • EXTERNAL FUNCTION

    VECTOR-POP-ELEMENT

    • VECTOR
    • ELEMENT

    Source

    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 ARRAY-SHIFT.
    
    If the array has an element-type of T, the element moved beyond the fill
    pointer is set to NIL to avoid a memory leak.
    
    See VECTOR-POP-POSITION
    See VECTOR-POP-ELEMENT*

  • EXTERNAL FUNCTION

    VECTOR-POP-ELEMENT*

    • VECTOR
    • ELEMENT

    Source

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

  • EXTERNAL FUNCTION

    VECTOR-POP-FRONT

    • VECTOR

    Source

    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 ARRAY-SHIFT.
    
    See VECTOR-POP-FRONT*
    See VECTOR-POP-POSITION

  • EXTERNAL FUNCTION

    VECTOR-POP-FRONT*

    • VECTOR

    Source

    Pops the first element off the vector and returns it.
    This is faster than VECTOR-POP-FRONT, but does not preserve the order of elements
    in the vector.
    
    See VECTOR-POP-FRONT
    See VECTOR-POP-POSITION

  • EXTERNAL FUNCTION

    VECTOR-POP-POSITION

    • VECTOR
    • POSITION

    Source

    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 ARRAY-SHIFT.
    
    If the array has an element-type of T, the element moved beyond the fill
    pointer is set to NIL to avoid a memory leak.
    
    See VECTOR-POP-POSITION*

  • EXTERNAL FUNCTION

    VECTOR-POP-POSITION*

    • VECTOR
    • POSITION

    Source

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

  • EXTERNAL FUNCTION

    VECTOR-PUSH-EXTEND-FRONT

    • ELEMENT
    • VECTOR

    Source

    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 ARRAY-SHIFT.
    
    See VECTOR-PUSH-EXTEND-POSITION

  • EXTERNAL FUNCTION

    VECTOR-PUSH-EXTEND-NEW

    • ELEMENT
    • VECTOR
    • &KEY
    • KEY
    • TEST
    • TEST-NOT

    Source

    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 TEST-NOT 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:VECTOR-PUSH-EXTEND

  • EXTERNAL FUNCTION

    VECTOR-PUSH-EXTEND-POSITION

    • ELEMENT
    • VECTOR
    • POSITION

    Source

    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 ARRAY-SHIFT.