diff --git a/docs/api/scheme/cyclone/array-list.md b/docs/api/scheme/cyclone/array-list.md new file mode 100644 index 00000000..4385c099 --- /dev/null +++ b/docs/api/scheme/cyclone/array-list.md @@ -0,0 +1,150 @@ +--- +layout: main +title: API +--- + +# Array list library # + +A simple [dynamic array][1] implementation, designed to be used to support +various other structures. + +## Description ## + +The scale factor for this implementation is 2, which is used by several other +languages' standard library implementation of dynamic arrays. The backing +structure is a Scheme vector, with a minimum size of 16 to avoid early resizing +on small structures. + +## Definitions ## + +When describing a procedure's arguments, ``array-list`` denotes an array list +argument. + +## Limitations ## + +Currently does not contain a full set of operations - more will be added if +needed or requested. + +## Contents ## + +- [`array-list`](#array-list) +- [`array-list?`](#array-list1) +- [`array-list-delete!`](#array-list-delete) +- [`array-list-empty?`](#array-list-empty) +- [`array-list-insert!`](#array-list-insert) +- [`array-list-length`](#array-list-length) +- [`array-list-ref`](#array-list-ref) +- [`array-list-set!`](#array-list-set) +- [`make-array-list`](#make-array-list) + +## Constructors ## + +### array-list ### + +```(array-list obj ...)``` + +Creates a new array list containing all of ``obj``, in that order. + +**Time complexity:** *O(n)* (amortized), where *n* is ``(length obj)``. + +**Space complexity:** *O(n)* (worst-case), where *n* is ``(length obj)`` + +### make-array-list ### + +```(make-array-list k)``` + +Creates a new empty array list with a capacity of ``(max 16 k)`` elements. + +**Time complexity:** *O(n)* (worst-case), where *n* is ``k``. + +**Space complexity:** *O(n)* (worst-case), where *n* is ``k``. + +## Predicates ## + +### array-list? ### + +```(array-list? obj)``` + +Returns ``#t`` if ``obj`` is an array list, and ``#f`` otherwise. + +**Time complexity:** *O(1)* (worst-case) + +**Space complexity:** *O(1)* (worst-case) + +```(array-list-empty? array-list)``` + +Returns ``#t`` if ``array-list`` contains no items, and ``#f`` otherwise. + +**Time complexity:** *O(1)* (worst-case) + +**Space complexity:** *O(1)* (worst-case) + +## Accessors ## + +### array-list-length ### + +```(array-list-length array-list)``` + +Returns the number of items stored in ``array-list``. + +**Time complexity:** *O(1)* (worst-case) + +**Space complexity:** *O(1)* (worst-case) + +### array-list-ref ### + +```(array-list-ref array-list k)``` + +Returns the ``k``th element of ``array-list`` (zero-indexed). It is an error if +``k`` is greater than, or equal to, ``(array-list-length array-list)``. + +**Time complexity:** *O(1)* (worst-case) + +**Space complexity:** *O(1)* (worst-case) + +## Mutators ## + +### array-list-delete! ### + +```(array-list-delete! array-list)``` +```(array-list-delete! array-list k)``` + +Deletes the element at position ``k`` in ``array-list`` (zero-indexed). If ``k`` +is not provided, deletes the last element of ``array-list`` instead. Elements at +positions after ``k`` are 'slid over' to fill the 'gap' left by deleting the +element. It is an error if ``k`` is greater than, or equal to +``(array-list-length array-list)``. + +**Time complexity:** *O(n)* (worst-case), *O(1)* (amortized, when deleting last +element) + +**Space complexity:** *O(n)* (worst-case), *O(1)* (amortized) + +### array-list-insert! ### + +```(array-list-insert! array-list obj)``` +```(array-list-insert! array-list k obj)``` + +Inserts ``obj`` at position ``k`` in ``array-list`` (zero-indexed). If ``k`` is +not provided, inserts ``obj`` at the end of ``array-list``. Elements are `slid +over` away from the ``k``th position to create a 'gap' for ``obj`` if necessary. +It is an error if ``k`` is greater than ``(array-list-length array-list)``. + +**Time complexity:** *O(n)* (worst-case), *O(1)* (amortized, when inserting at +the end) + +**Space complexity:** *O(n)* (worst-case), *O(1)* (amortized) + +### array-list-set! ### + +```(array-list-set! array-list k obj)``` + +Replaces the element at position ``k`` in ``array-list`` with ``obj`` +(zero-indexed). It is an error if ``k`` is greater than, or equal to, +``(array-list-length array-list)``. + +**Time complexity:** *O(1)* (worst-case) + +**Space complexity:** *O(1)* (worst-case) + +[1]: https://en.wikipedia.org/wiki/Dynamic_array