# Array

Vector and Matrix are specialized in numeric data and can only contain numeric values. However, Array can contain both numeric and non-numeric values.

### Creating an Array

>>arr1=Array.new(3, "a")
>>arr1
"a"    "a"    "a"

>>arr2=Array.new(2, 3.14)
>>arr2
3.14    3.14

>>arr3=std.toarray{1,2,"a","b"}
>>arr3
1    2    "a"    "b"

In order to create an array from data, you can use either toarray function or use the interface. When interface is used to create an array, if a string can be converted to a valid number, then it will be stored as type number, otherwise as type string.

It should be noted that, unlike the Vector data type, there is no algebra defined for arrays.

### Array Manipulation

Consider the following array, a:     a = 1    2    3    "a"    "b"

If you print the array using the command-line:

>>a
1    2    3    "a"    "b"

It is seen that string values are printed using double quotient.

To read an entry from the array:

>>a or >>a(1)
10

>>type(a)
number

>>type(a)
string

To change an entry:

>>a=10 --a will be numeric

>>a="c" --a will be a string

>>a
10    2    3    "c"    "b"

## Member functions

### capacity

capacity() → integer

Returns the capacity of the array.

>>a=std.toarray{1, 2, 3, "a", "b"}
>>a
1    2    3    "a"    "b"

>>a:capacity()
6

>>#a -- size
5

Note: Capacity is important as nearing the limit of capacity will cause reallocation of the memory to accomodate more elements, thus causing the copying of the existing elements.

### clone

clone() → Array

Makes a deep copy of the array.

Note that, the assignment operator such as arr1=arr2 makes a shallow copy and arr1 and arr2 refers to the same data.

>>a=std.toarray{1, 2, 3, "a", "b"}

>>b=a
>>b=10

>>a
10    2    3    "a"    "b"

However, if we had used clone() function:

>>a=std.toarray{1, 2, 3, "a", "b"}
>>b=a:clone()

>>b=10

>>a
1    2    3    "a"    "b"

>>b
10    2    3     "a"    "b"

### erase

erase(pos)

Erases the element at the specified position as long as array will have at least one element at the end of the operation.

>>a=std.toarray{1, 2, 3, "a", "b"}

>>a:erase(4)
>>a
1    2    3    "b"

>>a=std.toarray{"a", "b"}
>>a:erase(1)
>>a
"b"

>>a:erase(1)
ERROR: An array must have at least one element.

### insert

insert(i, elem)

Inserts a number, 1D Lua table or an array at ith position.

>>a=std.toarray{"a", "b"}
>>a:insert( 2, {1, "c"} )

>>a
"a"    "c"    1    "b"

>>a=std.toarray{"a", "b"}
>>a2=std.toarray{1, "c"}

>>a:insert( 2, a2)
>>a
"a"    1    "c"    "b"

Note that, when a Lua table is inserted into the array, there is no guarantee that the order of the elements in the table will be preserved when they are inserted to the array. If order of the elements matter, insert elements as an array or individually.

### push_back

push_back(elem)

Inserts the elem at the end of the array. The argument elem can be either number or string.

>>a=std.toarray{"a", "b"}
>>a:insert(3, "c")
ERROR: Requested position index exceeds array's size.

>>>a:push_back("c")
>>a
"a"    "b"    "c"

### reserve

reserve(n)

Requests that the array capacity be at least enough to contain n number of elements. If the parameter n is smaller than the current capacity, calling reserve has no effect.

>>arr=std.toarray{1, 2, "a", "b"}
>>arr:capacity()
4

>>arr:reserve(3)
>>arr:capacity()
4

>>arr:reserve(10)
>>arr:capacity()
10

>>#arr
4

### resize

resize(n) → Array

Resizes the container so that it contains n number of elements. Depending on the requested number, the Array can shrink or expand.

>>arr=std.toarray{1, 2, "a", "b"}
>>a
1    2    "a"    "b"
>>#a
4

>>a:resize(6)
>>a
1    2    "a"    "b"    0    0
>>#a
6

>>a:resize(3)
>>a
1    2    "a"
>>#a
3

### shuffle

shuffle()

Shuffles the order of the elements in the Array.

>>a=std.toarray{1, 2, "a", "b"}

>>a:shuffle()

>>a
"a"    1    "b"    2

### slice

slice(index) → Array, Array

Slices the array into 2 arrays as of the requested index and returns 2 arrays. The original array itself is not affected.

>>a=std.toarray{1, 2, "a", "b"}
>>a1, a2=a:slice(2)

>>a1
1    2

>>a2
"a"    "b"

>>a
1    2    "a"    "b"

### sort

sort(order=, caseSensitive=true)

Sorts the array either in ascending or descending order and/or case-sensitive or case-insensitive manner. Regardless of case-sensitivity, the numbers are always assumed to be smaller than letters.
If order="A" then the array is sorted in ascending order, if order="D" then the array is sorted in descending order. The sorting by default is case-sensitive.

>>a=std.toarray{2, "c", "a", "d", 1}
>>a
2    "c"    "a"    "d"    1

>>a:sort("A")
>>a
1    2    "a"    "c"    "d"

>>a:sort("D")
>>a
"d"    "c"    "a"    2    1

### unique

unique()

Removes the recurring elements so that the array contains only the unique elements. At the end of the operation, the array is resized to only contain unique elements.

>>a=std.toarray{1, "b", "2", "a", "b", "2"}
>>a
1    "b"    2    "a"    "b"    2

>>a:unique()

>>a
1    2    "a"    "b"