Arrays (F#)
Arrays are fixed-size, zero-based, mutable collections of consecutive data elements that are all of the same type.
Create arrays
You can create arrays in several ways. You can create a small array by listing consecutive values between [| and |] and separated by semicolons, as shown in the following examples.
let array1 = [| 1; 2; 3 |]
You can also put each element on a separate line, in which case the semicolon separator is optional.
let array1 =
[|
1
2
3
|]
The type of the array elements is inferred from the literals used and must be consistent.
// This is an array of 3 integers.
let array1 = [| 1; 2; 3 |]
// This is an array of a tuple of 3 integers.
let array2 = [| 1, 2, 3 |]
The following code causes an error because 3.0 is a float and 1 and 2 are integers.
// Causes an error. The 3.0 (float) cannot be converted to integer implicitly.
// let array3 = [| 1; 2; 3.0 |]
The following code causes an error too because 1,2 is a tuple and 3 is an integer.
// Causes an error too. The 3 (integer) cannot be converted to tuple implicitly.
// let array4 = [| 1, 2; 3 |]
You can also use sequence expressions to create arrays. Following is an example that creates an array of squares of integers from 1 to 10.
let array3 = [| for i in 1 .. 10 -> i * i |]
To create an array in which all the elements are initialized to zero, use Array.zeroCreate.
let arrayOfTenZeroes : int array = Array.zeroCreate 10
Access elements
You can access array elements by using brackets ([ and ]). The original dot syntax (.[index]) is still supported but no longer recommended as of F# 6.0.
array1[0]
Array indexes start at 0.
You can also access array elements by using slice notation, which enables you to specify a subrange of the array. Examples of slice notation follow.
// Accesses elements from 0 to 2.
array1[0..2]
// Accesses elements from the beginning of the array to 2.
array1[..2]
// Accesses elements from 2 to the end of the array.
array1[2..]
When slice notation is used, a new copy of the array is created.
Array types and modules
The type of all F# arrays is the .NET Framework type System.Array. Therefore, F# arrays support all the functionality available in System.Array.
The Array module supports operations on one-dimensional arrays. The modules Array2D, Array3D, and Array4D contain functions that support operations on arrays of two, three, and four dimensions, respectively. You can create arrays of rank greater than four by using System.Array.
Simple functions
Array.get gets an element. Array.length gives the length of an array. Array.set sets an element to a specified value. The following code example illustrates the use of these functions.
let array1 = Array.create 10 ""
for i in 0 .. array1.Length - 1 do
Array.set array1 i (i.ToString())
for i in 0 .. array1.Length - 1 do
printf "%s " (Array.get array1 i)
The output is as follows.
0 1 2 3 4 5 6 7 8 9
Functions that create arrays
Several functions create arrays without requiring an existing array. Array.empty creates a new array that does not contain any elements. Array.create creates an array of a specified size and sets all the elements to provided values. Array.init creates an array, given a dimension and a function to generate the elements. Array.zeroCreate creates an array in which all the elements are initialized to the zero value for the array's type. The following code demonstrates these functions.
let myEmptyArray = Array.empty
printfn "Length of empty array: %d" myEmptyArray.Length
printfn "Array of floats set to 5.0: %A" (Array.create 10 5.0)
printfn "Array of squares: %A" (Array.init 10 (fun index -> index * index))
let (myZeroArray : float array) = Array.zeroCreate 10
The output is as follows.
Length of empty array: 0
Area of floats set to 5.0: [|5.0; 5.0; 5.0; 5.0; 5.0; 5.0; 5.0; 5.0; 5.0; 5.0|]
Array of squares: [|0; 1; 4; 9; 16; 25; 36; 49; 64; 81|]
Array.copy creates a new array that contains elements that are copied from an existing array. Note that the copy is a shallow copy, which means that if the element type is a reference type, only the reference is copied, not the underlying object. The following code example illustrates this.
open System.Text
let firstArray : StringBuilder array = Array.init 3 (fun index -> new StringBuilder(""))
let secondArray = Array.copy firstArray
// Reset an element of the first array to a new value.
firstArray[0] <- new StringBuilder("Test1")
// Change an element of the first array.
firstArray[1].Insert(0, "Test2") |> ignore
printfn "%A" firstArray
printfn "%A" secondArray
The output of the preceding code is as follows:
[|Test1; Test2; |]
[|; Test2; |]
The string Test1 appears only in the first array because the operation of creating a new element overwrites the reference in firstArray but does not affect the original reference to an empty string that is still present in secondArray. The string Test2 appears in both arrays because the Insert operation on the System.Text.StringBuilder type affects the underlying System.Text.StringBuilder object, which is referenced in both arrays.
Array.sub generates a new array from a subrange of an array. You specify the subrange by providing the starting index and the length. The following code demonstrates the use of Array.sub.
let a1 = [| 0 .. 99 |]
let a2 = Array.sub a1 5 10
printfn "%A" a2
The output shows that the subarray starts at element 5 and contains 10 elements.
[|5; 6; 7; 8; 9; 10; 11; 12; 13; 14|]
Array.append creates a new array by combining two existing arrays.
The following code demonstrates Array.append.
printfn "%A" (Array.append [| 1; 2; 3|] [| 4; 5; 6|])
The output of the preceding code is as follows.
[|1; 2; 3; 4; 5; 6|]
Array.choose selects elements of an array to include in a new array. The following code demonstrates Array.choose. Note that the element type of the array does not have to match the type of the value returned in the option type. In this example, the element type is int and the option is the result of a polynomial function, elem*elem - 1, as a floating point number.
printfn "%A" (Array.choose (fun elem -> if elem % 2 = 0 then
Some(float (elem*elem - 1))
else
None) [| 1 .. 10 |])
The output of the preceding code is as follows.
[|3.0; 15.0; 35.0; 63.0; 99.0|]
Array.collect runs a specified function on each array element of an existing array and then collects the elements generated by the function and combines them into a new array. The following code demonstrates Array.collect.
printfn "%A" (Array.collect (fun elem -> [| 0 .. elem |]) [| 1; 5; 10|])
The output of the preceding code is as follows.
[|0; 1; 0; 1; 2; 3; 4; 5; 0; 1; 2; 3; 4; 5; 6; 7; 8; 9; 10|]
Array.concat takes a sequence of arrays and combines them into a single array. The following code demonstrates Array.concat.
Array.concat [ [|0..3|] ; [|4|] ]
//output [|0; 1; 2; 3; 4|]
Array.concat [| [|0..3|] ; [|4|] |]
//output [|0; 1; 2; 3; 4|]
Array.filter takes a Boolean condition function and generates a new array that contains only those elements from the input array for which the condition is true. The following code demonstrates Array.filter.
printfn "%A" (Array.filter (fun elem -> elem % 2 = 0) [| 1 .. 10|])
The output of the preceding code is as follows.
[|2; 4; 6; 8; 10|]
Array.rev generates a new array by reversing the order of an existing array. The following code demonstrates Array.rev.
let stringReverse (s: string) =
System.String(Array.rev (s.ToCharArray()))
printfn "%A" (stringReverse("!dlrow olleH"))
The output of the preceding code is as follows.
"Hello world!"
You can easily combine functions in the array module that transform arrays by using the pipeline operator (|>), as shown in the following example.
[| 1 .. 10 |]
|> Array.filter (fun elem -> elem % 2 = 0)
|> Array.choose (fun elem -> if (elem <> 8) then Some(elem*elem) else None)
|> Array.rev
|> printfn "%A"
The output is
[|100; 36; 16; 4|]
Multidimensional arrays
A multidimensional array can be created, but there is no syntax for writing a multidimensional array literal. Use the operator array2D to create an array from a sequence of sequences of array elements. The sequences can be array or list literals. For example, the following code creates a two-dimensional array.
let my2DArray = array2D [ [ 1; 0]; [0; 1] ]
You can also use the function Array2D.init to initialize arrays of two dimensions, and similar functions are available for arrays of three and four dimensions. These functions take a function that is used to create the elements. To create a two-dimensional array that contains elements set to an initial value instead of specifying a function, use the Array2D.create function, which is also available for arrays up to four dimensions. The following code example first shows how to create an array of arrays that contain the desired elements, and then uses Array2D.init to generate the desired two-dimensional array.
let arrayOfArrays = [| [| 1.0; 0.0 |]; [|0.0; 1.0 |] |]
let twoDimensionalArray = Array2D.init 2 2 (fun i j -> arrayOfArrays[i][j])
Array indexing and slicing syntax is supported for arrays up to rank 4. When you specify an index in multiple dimensions, you use commas to separate the indexes, as illustrated in the following code example.
twoDimensionalArray[0, 1] <- 1.0
The type of a two-dimensional array is written out as <type>[,] (for example, int[,], double[,]), and the type of a three-dimensional array is written as <type>[,,], and so on for arrays of higher dimensions.
Only a subset of the functions available for one-dimensional arrays is also available for multidimensional arrays.
Array slicing and multidimensional arrays
In a two-dimensional array (a matrix), you can extract a sub-matrix by specifying ranges and using a wildcard (*) character to specify whole rows or columns.
// Get rows 1 to N from an NxM matrix (returns a matrix):
matrix[1.., *]
// Get rows 1 to 3 from a matrix (returns a matrix):
matrix[1..3, *]
// Get columns 1 to 3 from a matrix (returns a matrix):
matrix[*, 1..3]
// Get a 3x3 submatrix:
matrix[1..3, 1..3]
You can decompose a multidimensional array into subarrays of the same or lower dimension. For example, you can obtain a vector from a matrix by specifying a single row or column.
// Get row 3 from a matrix as a vector:
matrix[3, *]
// Get column 3 from a matrix as a vector:
matrix[*, 3]
You can use this slicing syntax for types that implement the element access operators and overloaded GetSlice methods. For example, the following code creates a Matrix type that wraps the F# 2D array, implements an Item property to provide support for array indexing, and implements three versions of GetSlice. If you can use this code as a template for your matrix types, you can use all the slicing operations that this section describes.
type Matrix<'T>(N: int, M: int) =
let internalArray = Array2D.zeroCreate<'T> N M
member this.Item
with get(a: int, b: int) = internalArray[a, b]
and set(a: int, b: int) (value:'T) = internalArray[a, b] <- value
member this.GetSlice(rowStart: int option, rowFinish : int option, colStart: int option, colFinish : int option) =
let rowStart =
match rowStart with
| Some(v) -> v
| None -> 0
let rowFinish =
match rowFinish with
| Some(v) -> v
| None -> internalArray.GetLength(0) - 1
let colStart =
match colStart with
| Some(v) -> v
| None -> 0
let colFinish =
match colFinish with
| Some(v) -> v
| None -> internalArray.GetLength(1) - 1
internalArray[rowStart..rowFinish, colStart..colFinish]
member this.GetSlice(row: int, colStart: int option, colFinish: int option) =
let colStart =
match colStart with
| Some(v) -> v
| None -> 0
let colFinish =
match colFinish with
| Some(v) -> v
| None -> internalArray.GetLength(1) - 1
internalArray[row, colStart..colFinish]
member this.GetSlice(rowStart: int option, rowFinish: int option, col: int) =
let rowStart =
match rowStart with
| Some(v) -> v
| None -> 0
let rowFinish =
match rowFinish with
| Some(v) -> v
| None -> internalArray.GetLength(0) - 1
internalArray[rowStart..rowFinish, col]
module test =
let generateTestMatrix x y =
let matrix = new Matrix<float>(3, 3)
for i in 0..2 do
for j in 0..2 do
matrix[i, j] <- float(i) * x - float(j) * y
matrix
let test1 = generateTestMatrix 2.3 1.1
let submatrix = test1[0..1, 0..1]
printfn $"{submatrix}"
let firstRow = test1[0,*]
let secondRow = test1[1,*]
let firstCol = test1[*,0]
printfn $"{firstCol}"
Boolean functions on arrays
The functions Array.exists and Array.exists2 test elements in either one or two arrays, respectively. These functions take a test function and return true if there is an element (or element pair for Array.exists2) that satisfies the condition.
The following code demonstrates the use of Array.exists and Array.exists2. In these examples, new functions are created by applying only one of the arguments, in these cases, the function argument.
let allNegative = Array.exists (fun elem -> abs (elem) = elem) >> not
printfn "%A" (allNegative [| -1; -2; -3 |])
printfn "%A" (allNegative [| -10; -1; 5 |])
printfn "%A" (allNegative [| 0 |])
let haveEqualElement = Array.exists2 (fun elem1 elem2 -> elem1 = elem2)
printfn "%A" (haveEqualElement [| 1; 2; 3 |] [| 3; 2; 1|])
The output of the preceding code is as follows.
true
false
false
true
Similarly, the function Array.forall tests an array to determine whether every element satisfies a Boolean condition. The variation Array.forall2 does the same thing by using a Boolean function that involves elements of two arrays of equal length. The following code illustrates the use of these functions.
let allPositive = Array.forall (fun elem -> elem > 0)
printfn "%A" (allPositive [| 0; 1; 2; 3 |])
printfn "%A" (allPositive [| 1; 2; 3 |])
let allEqual = Array.forall2 (fun elem1 elem2 -> elem1 = elem2)
printfn "%A" (allEqual [| 1; 2 |] [| 1; 2 |])
printfn "%A" (allEqual [| 1; 2 |] [| 2; 1 |])
The output for these examples is as follows.
false
true
true
false
Search arrays
Array.find takes a Boolean function and returns the first element for which the function returns true, or raises a System.Collections.Generic.KeyNotFoundException if no element that satisfies the condition is found. Array.findIndex is like Array.find, except that it returns the index of the element instead of the element itself.
The following code uses Array.find and Array.findIndex to locate a number that is both a perfect square and perfect cube.
let arrayA = [| 2 .. 100 |]
let delta = 1.0e-10
let isPerfectSquare (x:int) =
let y = sqrt (float x)
abs(y - round y) < delta
let isPerfectCube (x:int) =
let y = System.Math.Pow(float x, 1.0/3.0)
abs(y - round y) < delta
let element = Array.find (fun elem -> isPerfectSquare elem && isPerfectCube elem) arrayA
let index = Array.findIndex (fun elem -> isPerfectSquare elem && isPerfectCube elem) arrayA
printfn "The first element that is both a square and a cube is %d and its index is %d." element index
The output is as follows.
The first element that is both a square and a cube is 64 and its index is 62.
Array.tryFind is like Array.find, except that its result is an option type, and it returns None if no element is found. Array.tryFind should be used instead of Array.find when you do not know whether a matching element is in the array. Similarly, Array.tryFindIndex is like Array.findIndex except that the option type is the return value. If no element is found, the option is None.
The following code demonstrates the use of Array.tryFind. This code depends on the previous code.
let delta = 1.0e-10
let isPerfectSquare (x:int) =
let y = sqrt (float x)
abs(y - round y) < delta
let isPerfectCube (x:int) =
let y = System.Math.Pow(float x, 1.0/3.0)
abs(y - round y) < delta
let lookForCubeAndSquare array1 =
let result = Array.tryFind (fun elem -> isPerfectSquare elem && isPerfectCube elem) array1
match result with
| Some x -> printfn "Found an element: %d" x
| None -> printfn "Failed to find a matching element."
lookForCubeAndSquare [| 1 .. 10 |]
lookForCubeAndSquare [| 100 .. 1000 |]
lookForCubeAndSquare [| 2 .. 50 |]
The output is as follows.
Found an element: 1
Found an element: 729
Failed to find a matching element.
Use Array.tryPick when you need to transform an element in addition to finding it. The result is the first element for which the function returns the transformed element as an option value, or None if no such element is found.
The following code shows the use of Array.tryPick. In this case, instead of a lambda expression, several local helper functions are defined to simplify the code.
let findPerfectSquareAndCube array1 =
let delta = 1.0e-10
let isPerfectSquare (x:int) =
let y = sqrt (float x)
abs(y - round y) < delta
let isPerfectCube (x:int) =
let y = System.Math.Pow(float x, 1.0/3.0)
abs(y - round y) < delta
// intFunction : (float -> float) -> int -> int
// Allows the use of a floating point function with integers.
let intFunction function1 number = int (round (function1 (float number)))
let cubeRoot x = System.Math.Pow(x, 1.0/3.0)
// testElement: int -> (int * int * int) option
// Test an element to see whether it is a perfect square and a perfect
// cube, and, if so, return the element, square root, and cube root
// as an option value. Otherwise, return None.
let testElement elem =
if isPerfectSquare elem && isPerfectCube elem then
Some(elem, intFunction sqrt elem, intFunction cubeRoot elem)
else None
match Array.tryPick testElement array1 with
| Some (n, sqrt, cuberoot) -> printfn "Found an element %d with square root %d and cube root %d." n sqrt cuberoot
| None -> printfn "Did not find an element that is both a perfect square and a perfect cube."
findPerfectSquareAndCube [| 1 .. 10 |]
findPerfectSquareAndCube [| 2 .. 100 |]
findPerfectSquareAndCube [| 100 .. 1000 |]
findPerfectSquareAndCube [| 1000 .. 10000 |]
findPerfectSquareAndCube [| 2 .. 50 |]
The output is as follows.
Found an element 1 with square root 1 and cube root 1.
Found an element 64 with square root 8 and cube root 4.
Found an element 729 with square root 27 and cube root 9.
Found an element 4096 with square root 64 and cube root 16.
Did not find an element that is both a perfect square and a perfect cube.
Perform computations on arrays
The Array.average function returns the average of each element in an array. It is limited to element types that support exact division by an integer, which includes floating point types but not integral types. The Array.averageBy function returns the average of the results of calling a function on each element. For an array of integral type, you can use Array.averageBy and have the function convert each element to a floating point type for the computation.
Use Array.max or Array.min to get the maximum or minimum element, if the element type supports it. Similarly, Array.maxBy and Array.minBy allow a function to be executed first, perhaps to transform to a type that supports comparison.
Array.sum adds the elements of an array, and Array.sumBy calls a function on each element and adds the results together.
To execute a function on each element in an array without storing the return values, use Array.iter. For a function involving two arrays of equal length, use Array.iter2. If you also need to keep an array of the results of the function, use Array.map or Array.map2, which operates on two arrays at a time.
The variations Array.iteri and Array.iteri2 allow the index of the element to be involved in the computation; the same is true for Array.mapi and Array.mapi2.
The functions Array.fold, Array.foldBack, Array.reduce, Array.reduceBack, Array.scan, and Array.scanBack execute algorithms that involve all the elements of an array. Similarly, the variations Array.fold2 and Array.foldBack2 perform computations on two arrays.
These functions for performing computations correspond to the functions of the same name in the List module. For usage examples, see Lists.
Modify arrays
Array.set sets an element to a specified value. Array.fill sets a range of elements in an array to a specified value. The following code provides an example of Array.fill.
let arrayFill1 = [| 1 .. 25 |]
Array.fill arrayFill1 2 20 0
printfn "%A" arrayFill1
The output is as follows.
[|1; 2; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 23; 24; 25|]
You can use Array.blit to copy a subsection of one array to another array.
Convert to and from other types
Array.ofList creates an array from a list. Array.ofSeq creates an array from a sequence. Array.toList and Array.toSeq convert to these other collection types from the array type.
Sort arrays
Use Array.sort to sort an array by using the generic comparison function. Use Array.sortBy to specify a function that generates a value, referred to as a key, to sort by using the generic comparison function on the key. Use Array.sortWith if you want to provide a custom comparison function. Array.sort, Array.sortBy, and Array.sortWith all return the sorted array as a new array. The variations Array.sortInPlace, Array.sortInPlaceBy, and Array.sortInPlaceWith modify the existing array instead of returning a new one.
Arrays and tuples
The functions Array.zip and Array.unzip convert arrays of tuple pairs to tuples of arrays and vice versa. Array.zip3 and Array.unzip3 are similar except that they work with tuples of three elements or tuples of three arrays.
Parallel computations on arrays
The module Array.Parallel contains functions for performing parallel computations on arrays. This module is not available in applications that target versions of the .NET Framework prior to version 4.
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for