//
//------------------ DOK FILE --------------------------------------------------
+Header	arrayLib
=pkg	bios
=title	Arrays
=short	ordered set of mutable elements
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- array
+Proto	array
=type	array a1
=mode	type
=pkg	language
=impl	mcy
=link	
=desc
An array is an ordered set of elements. These elements all have the same type. It is possible to modify these elements, but it is not possible to change the length of the array.

It is possible to define an array in the Minimacy syntax. An array is always delimited with curly brackets.
	> {"foo", "bar"}
>-> array Str: #2 {
>   0:
>     Str: "foo"
>   1:
>     Str: "bar"
>}

To change the value of an element of the array, you will use the 'set' keyword:
	> let {"foo", "bar"} -> myArray in (set myArray[1]="BAR"; myArray)
>-> array Str: #2 {
>   0:
>     Str: "foo"
>   1:
>     Str: "BAR"
>}
//
//
//------------------ PROTO ----------------------------------------------------- arrayCreate
+Proto	arrayCreate
=type	fun Int a1 -> array a1
=mode	function
=pkg	bios
=impl	native
=link	
=desc
This function creates a new array of the specified length, where each value is initialized with initialValue.
	> arrayCreate (3, true)
>-> array Bool: #3 {
>   0:
>     Bool: true
>   1:
>     Bool: true
>   2:
>     Bool: true
>}
//
+arg	length
=type	Int
=desc	A positive integer
//
+arg	initialValue
=type	a1
=desc	A value of any type
//
+arg	result
=type	array a1
=desc	An array of length initialized with value
//
//
//------------------ PROTO ----------------------------------------------------- arrayIndexOf
+Proto	arrayIndexOf
=type	fun array a1 a1 -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function returns the index of the first occurrence of the searched value in an array.
It returns nil if the value is not found in the array.
	> arrayIndexOf ({ 12, 23, 34 }, 23)
>-> Int: 1 (0x1)
//
+arg	src
=type	array a1
=desc	An array of any type
//
+arg	search
=type	a1
=desc	A value of the same type
//
+arg	result
=type	Int
=desc	The index of the searched value
//
//
//------------------ PROTO ----------------------------------------------------- arrayInit
+Proto	arrayInit
=type	fun Int (fun Int -> a1) -> array a1
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function returns a new array of the specified length, where each value is computed by the fInit function.
	> arrayInit (3, lambda (i)=i*2)
>-> array Int: #3 {
	   0:
	     Int: 0 (0x0)
	   1:
	     Int: 2 (0x2)
	   2:
	     Int: 4 (0x4)
	}
//
+arg	length
=type	Int
=desc	A positive integer
//
+arg	fInit
=type	fun Int -> a1
=desc	A function which provides a value for each index between 0 and length-1
//
+arg	result
=type	array a1
=desc	An array of length initialized with the values provided by the fInit function
//
//
//------------------ PROTO ----------------------------------------------------- arrayLength
+Proto	arrayLength
=type	fun array a1 -> Int
=mode	function
=pkg	bios
=impl	native
=link	
=desc
This function returns the length of the array.
	> arrayLength ({"foo", "bar"})
>-> Int: 2 (0x2)
//
+arg	src
=type	array a1
=desc	An array of any type
//
+arg	result
=type	Int
=desc	The length of the array
//
//
//------------------ PROTO ----------------------------------------------------- arrayMap
+Proto	arrayMap
=type	fun array a1 (fun a1 -> a2) -> array a2
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function returns a new array of the same length where each element is obtained by applying the fMap function to the corresponding element of array src.
	> arrayMap( {0, 1, 2}, lambda (v) = strFromInt (v*2))
>-> array Str: #3 {
>   0:
>     Str: "0"
>   1:
>     Str: "2"
>   2:
>     Str: "4"
>}
//
+arg	src
=type	array a1
=desc	An array of any type
//
+arg	fMap
=type	fun a1 -> a2
=desc	A function that associates a value to each element of the array src
//
+arg	result
=type	array a2
=desc	An array where each element is a result of function fMap
//
//
//------------------ PROTO ----------------------------------------------------- arrayMapIndex
+Proto	arrayMapIndex
=type	fun array a1 (fun Int a1 -> a2) -> array a2
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function returns a new array of the same length where each element is obtained by applying the fMap function to each index and the corresponding element of array src.
	> arrayMapIndex ({0, 1, 2}, lambda (i, v) = strFormat ("*: *", i, v*2))
>-> array Str: #3 {
>   0:
>     Str: "0: 0"
>   1:
>     Str: "1: 2"
>   2:
>     Str: "2: 4"
>}
//
+arg	src
=type	array a1
=desc	An array of any type
//
+arg	fMap
=type	fun Int a1 -> a2
=desc	A function that associates a value to each element of the array src. The first argument is the index of the element in src, starting from 0.
//
+arg	result
=type	array a2
=desc	An array where each element is a result of function fMap
//
//
//------------------ PROTO ----------------------------------------------------- listFromArray
+Proto	listFromArray
=type	fun array a1 -> list a1
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function returns the list of all the elements of the array, in the same order.
	> listFromArray ({"foo", "bar"})
>-> list Str:
>   Str: "foo"
>   Str: "bar"
This is the opposite of the [[arrayFromList]] function.
//
+arg	src
=type	array a1
=desc	An array of any type
//
+arg	result
=type	list a1
=desc	The list of the elements of the array
//
//
//------------------ PROTO ----------------------------------------------------- arraySlice
+Proto	arraySlice
=type	fun array a1 Int Int -> array a1
=mode	function
=pkg	bios
=impl	native
=link	
=desc	
This function extracts a subarray from the array src, and returns it as a new array.
When the offset is negative it is counted from the end of src.
	> arraySlice ({2, 4, 6, 8}, 1, 2)
>-> array Int: #2 {
>   0:
>     Int: 4 (0x4)
>   1:
>     Int: 6 (0x6)
>}
//
+arg	src
=type	array a1
=desc	An array of any type
//
+arg	offset
=type	Int
=desc	An integer
//
+arg	len
=type	Int
=desc	Another integer
//
+arg	result
=type	array a1
=desc	A subarray
//
//
//------------------ PROTO ----------------------------------------------------- arrayReduce
+Proto	arrayReduce
=type	fun array a1 a2 (fun a2 a1 -> a2) -> a2
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function apply a reduce function to an array.
-	The fReduce function is applied to v0 and the first element of the array src
-	The fReduce function is applied to this result and the second element of the array
-	and again until the end of the array

It makes it easy to compute the max element of an array:
	> arrayReduce ({1, 2, 5, 3}, 0, #max)
>-> Int: 5 (0x5)

Another example to compute the sum of all the elements of an array:
	> arrayReduce ({1, 2, 5, 3}, 0, lambda (v0, v)=v0+v)
>-> Int: 11 (0xB)
//
+arg	src
=type	array a1
=desc	An array
//
+arg	v0
=type	a2
=desc	The initial result
//
+arg	fReduce
=type	fun a2 a1 -> a2
=desc	A function which is applied iteratively to the current result and the next element in the array src.
//
+arg	result
=type	a2
=desc	The final result
//
//
//------------------ PROTO ----------------------------------------------------- arrayDump
+Proto	arrayDump
=type	fun a1 -> a1
=mode	keyword
=pkg	bios
=impl	mcy
=link	
=desc	
//
+arg	a
=type	a1
=desc	
//
+arg	result
=type	a1
=desc