View source for AINS()

==Purpose==
Function to insert an element into an array

==Syntax==
AINS(<array>, <expN> [, <exp>])

==See Also==
[[AADD()]], [[AAVERAGE()]], [[ACOPY()]], [[ADEL()]], [[ADESC()]], [[ADIR()]], [[AELEMENT()]], [[AFIELDS()]], [[AFILL()]], [[ALEN()]], [[AMAX()]], [[AMIN()]], [[APPEND FROM ARRAY]], [[ARRAY()]], [[ASCAN()]], [[ASIZE()]], [[ASORT()]], [[ASTORE()]], [[ASTRING()]], [[ASUBSCRIPT()]], [[ASUM()]], [[COPY TO ARRAY]], [[DECLARE]], [[DIMENSION]], [[GATHER]], [[IN_ARRAY()]], [[IS_ARRAY()]], [[LOCAL]], [[PRIVATE]], [[PUBLIC]], [[RELEASE]], [[RESTORE]], [[SAVE]], [[SCATTER]]

==Description==
The AINS() function inserts an element into the <array> at the position of <expN>.  The element will be defined as .F. unless an optional <exp> is included.  All elements higher than the inserted element are shifted up and the contents of the last element are overwritten.  If <array> is a two-dimensional array, AINS() operates on a row of elements.  The total number of elements in the array remains the same.  The array must have been previously declared.

Note: for two-dimensional arrays, the <exp> is still used as the value stored in the elements.  Specifying 2 will store the numeric 2 to the elements.

==Example==
<code lang="recital">
declare table[10]
ains(table, 3, "hello world")
// Another Example
declare flist[5]
...
if ascan(flist, "new information") = 0
    ains(flist,1,"new information")
endif

// Two-dimensional array
open database southwind
use shippers
copy to array arr1
? arr1
ains(arr1,1)
? arr1
close data

// Results
Array (refcnt=1)
(
    [1,1] = 1
    [1,2] = Speedy Express                          
    [1,3] = (503) 555-9831          
    [2,1] = 2
    [2,2] = United Package                          
    [2,3] = (503) 555-3199          
    [3,1] = 3
    [3,2] = Federal Shipping                        
    [3,3] = (503) 555-9931          
)

Array (refcnt=1)
(
    [1,1] = False
    [1,2] = False
    [1,3] = False
    [2,1] = 1
    [2,2] = Speedy Express                          
    [2,3] = (503) 555-9831          
    [3,1] = 2
    [3,2] = United Package                          
    [3,3] = (503) 555-3199          
)
</code>

==Version Notes==
* Prior to v1.3.1, AINS() operated on individual elements only, not on rows of two-dimensional arrays.

[[Category:Documentation]]
[[Category:Functions]]
[[Category:Array Processing Functions]]