.. include:: ../../global.rst

.. _`array type`:

Array Type
==========

Arrays are integer indexed collections of references to values.

The supplied index, :samp:`{index}`, can be negative in which case the
calculated index is :samp:`{array-length} + {index}`.

Reader Form
-----------

Arrays of simple types can be constructed with the reader form

    :samp:`#[ [{value} ...] ]`

degenerating to ``#[]``.

Any :samp:`{value}` will not be evaluated, only simple type
construction (numbers, strings, symbols etc.) will occur.


Array Predicates
----------------


.. _`array?`:

.. idio:function:: array? o


   test if `o` is an array				
   						
   :param o: object to test			
   :return: ``#t`` if `o` is an array, ``#f`` otherwise	


Array Constructors
------------------


.. _`make-array`:

.. idio:function:: make-array size [default]


   create an array with an initial allocation size of `size`
   						
   :param size: initial array size			
   :type size: integer				
   :param default: default array element value, defaults to ``#f``	
   :type default: value, optional			
   :return: the new array				
   :rtype: array					


.. _`copy-array`:

.. idio:function:: copy-array orig [depth [extra]]


   copy array `orig` and add an optional `extra` elements	
   							
   :param orig: initial array				
   :type orig: array					
   :param depth: ``'shallow`` or ``'deep`` (default)	
   :type depth: symbol, optional				
   :param extra: how many extra elements, defaults to 0 (zero)	
   :type extra: integer, optional				
   :return: the new array					
   :rtype: array						


.. _`list->array`:

.. idio:function:: list->array l


   convert list `l` to an array			
   						
   :param l: list to be converted			
   :type l: list					
   :return: array					
   :rtype: array					


.. _`array`:

.. idio:function:: array [x]


   
   construct an array from `x`
   
   :param x: elements for the array
   :type x: list
   :return: array constructed from the elements of `x`
   :rtype: array
   
   this simply calls :ref:`list->array <list->array>`


Array Attributes
----------------


.. _`array-length`:

.. idio:function:: array-length a


   return the used length of `a`			
   						
   :param a: the array				
   :type a: array					
   :return: the length of the array		
   :rtype: integer					
   						
   The used length is the highest accessed index plus one


.. _`array-ref`:

.. idio:function:: array-ref a index


   return the value at `index` of `a`		
   						
   :param a: the array				
   :type a: array					
   :param index: index				
   :type index: integer				
   :return: the value at index of the array	
   :rtype: integer					
   :raises: ^rt-array-bounds-error			


.. _`array-set!`:

.. idio:function:: array-set! a index v


   set the `index` of `a` to `v`			
   						
   :param a: the array				
   :type a: array					
   :param index: index				
   :type index: integer				
   :param v: value 				
   :type v: any	 				
   :return: ``#<unspec>``				
   :raises: ^rt-array-bounds-error			


Array Functions
---------------


.. _`array-push!`:

.. idio:function:: array-push! a v


   append `v` to `a`				
   						
   :param a: the array				
   :type a: array					
   :param v: value 				
   :type v: any	 				
   :return: ``#<unspec>``				
   :raises: ^rt-array-bounds-error			
   						
   Treats `a` as a stack and appends `v` to the end


.. _`array-pop!`:

.. idio:function:: array-pop! a


   pop the last value off `a`			
   						
   :param a: the array				
   :type a: array					
   :return: value					
   :rtype: any	 				
   :raises: ^rt-array-bounds-error			
   						
   Treats `a` as a stack and pops a value off the end


.. _`array-unshift!`:

.. idio:function:: array-unshift! a v


   unshifts `v` onto `a`				
   						
   :param a: the array				
   :type a: array					
   :param v: value 				
   :rtype: any	 				
   :return: ``#<unspec>``				
   						
   Treats `a` as a stack and unshifts (prepends) `v` to the start


.. _`array-shift!`:

.. idio:function:: array-shift! a


   shifts the first value off `a`			
   						
   :param a: the array				
   :type a: array					
   :return: value					
   :rtype: any	 				
   						
   Treats `a` as a stack and shifts a value off the start


.. _`array-fill!`:

.. idio:function:: array-fill! a fill


   set all the elements of `a` to `fill`		
   						
   :param a: the array to fill			
   :type a: array					
   :param fill: value to use for fill		
   :type fill: any					
   :return: ``#<unspec>``				


.. _`array-find-eq?`:

.. idio:function:: array-find-eq? a v [index]


   return the first index of `v` in `a` starting	
   at `index` or ``-1``				
   						
   :param a: the array				
   :type a: array					
   :param v: the value to search for		
   :type v: any					
   :param index: starting index, defaults to ``0``	
   :type index: integer, optional			
   :return: the index of the first `v` in `a`	
   :rtype: integer					
   :raises: ^rt-array-bounds-error			


.. _`array-for-each-set`:

.. idio:function:: array-for-each-set a func


   call `func` for each element in array `a` with a non-default	
   value with arguments: `index` the value at that	index		
   								
   :param a: array							
   :type a: array							
   :param func: func to be called with each index, value tuple	
   :type func: 2-ary function					
   :return: ``#<unspec>``						


.. _`fold-array`:

.. idio:function:: fold-array a func val


   call `func` for each element in array `a` with arguments:	
   `index`, the value at that index and `val`			
   								
   `val` is updated to the value returned by `func`.		
   								
   The final value of `val` is returned.				
   								
   :param a: array							
   :type a: array							
   :param func: func to be called with each index, value, val tuple	
   :type func: 3-ary function					
   :param val: initial value for `val`				
   :type val: any							
   :return: final value of `val`					
   :rtype: any			 				




.. include:: ../../commit.rst