FSharp.Core


Array2D Module

Contains operations for working with 2-dimensional arrays.

See also F# Language Guide - Arrays.

F# and CLI multi-dimensional arrays are typically zero-based. However, CLI multi-dimensional arrays used in conjunction with external libraries (e.g. libraries associated with Visual Basic) be non-zero based, using a potentially different base for each dimension. The operations in this module will accept such arrays, and the basing on an input array will be propagated to a matching output array on the Array2D.map and Array2D.mapi operations. Non-zero-based arrays can also be created using Array2D.zeroCreateBased, Array2D.createBased and Array2D.initBased.

Functions and values

Function or value Description

Array2D.base1 array

Full Usage: Array2D.base1 array

Parameters:
    array : 'T[,] - The input array.

Returns: int The base-index of the first dimension of the array.

Fetches the base-index for the first dimension of the array.

array : 'T[,]

The input array.

Returns: int

The base-index of the first dimension of the array.

Example

Create a 10x10 1-based array:


 open System

 let array = Array.CreateInstance(typeof<int>, [| 10; 10 |], [| 1; 1 |]) :?> int[,]

 array |> Array2D.base1
Evaluates to 1.

Array2D.base2 array

Full Usage: Array2D.base2 array

Parameters:
    array : 'T[,] - The input array.

Returns: int The base-index of the second dimension of the array.

Fetches the base-index for the second dimension of the array.

array : 'T[,]

The input array.

Returns: int

The base-index of the second dimension of the array.

Example

Create a 10x10 1-based array:


 open System

 let array = Array.CreateInstance(typeof<int>, [| 10; 10 |], [| 1; 1 |]) :?> int[,]

 array |> Array2D.base2
Evaluates to 1.

Array2D.blit source sourceIndex1 sourceIndex2 target targetIndex1 targetIndex2 length1 length2

Full Usage: Array2D.blit source sourceIndex1 sourceIndex2 target targetIndex1 targetIndex2 length1 length2

Parameters:
    source : 'T[,] - The source array.
    sourceIndex1 : int - The first-dimension index to begin copying from in the source array.
    sourceIndex2 : int - The second-dimension index to begin copying from in the source array.
    target : 'T[,] - The target array.
    targetIndex1 : int - The first-dimension index to begin copying into in the target array.
    targetIndex2 : int - The second-dimension index to begin copying into in the target array.
    length1 : int - The number of elements to copy across the first dimension of the arrays.
    length2 : int - The number of elements to copy across the second dimension of the arrays.

Reads a range of elements from the first array and write them into the second.

Slicing syntax is generally preferred, e.g.


 let source = array2D [ [ 3; 4 ]; [ 13; 14 ] ]
 let target = array2D [ [ 2; 2; 2 ]; [ 12; 12; 12 ] ]
 target[0..1,1..2] <- source

source : 'T[,]

The source array.

sourceIndex1 : int

The first-dimension index to begin copying from in the source array.

sourceIndex2 : int

The second-dimension index to begin copying from in the source array.

target : 'T[,]

The target array.

targetIndex1 : int

The first-dimension index to begin copying into in the target array.

targetIndex2 : int

The second-dimension index to begin copying into in the target array.

length1 : int

The number of elements to copy across the first dimension of the arrays.

length2 : int

The number of elements to copy across the second dimension of the arrays.

ArgumentException Thrown when any of the indices are negative or if either of the counts are larger than the dimensions of the array allow.
Example


 let source = array2D [ [ 3; 4 ]; [ 13; 14 ] ]
 let target = array2D [ [ 2; 2; 2 ]; [ 12; 12; 12 ] ]

 Array2D.blit source 0 0 target 0 1 2 2
After evaluation target contains [ [ 2; 3; 4 ]; [ 12; 13; 14 ] ].

Array2D.copy array

Full Usage: Array2D.copy array

Parameters:
    array : 'T[,] - The input array.

Returns: 'T[,] A copy of the input array.

Builds a new array whose elements are the same as the input array.

For non-zero-based arrays the basing on an input array will be propagated to the output array.

array : 'T[,]

The input array.

Returns: 'T[,]

A copy of the input array.

Example


 open System

 let array = Array2D.zeroCreate<int> 10 10

 array |> Array2D.copy
Evaluates to a new copy of the 10x10 array.

Array2D.create length1 length2 value

Full Usage: Array2D.create length1 length2 value

Parameters:
    length1 : int - The length of the first dimension of the array.
    length2 : int - The length of the second dimension of the array.
    value : 'T - The value to populate the new array.

Returns: 'T[,] The created array.

Creates an array whose elements are all initially the given value.

length1 : int

The length of the first dimension of the array.

length2 : int

The length of the second dimension of the array.

value : 'T

The value to populate the new array.

Returns: 'T[,]

The created array.

ArgumentException Thrown when length1 or length2 is negative.
Example


 Array2D.create 2 3 1
Evaluates to a 2x3 array with contents [[1; 1; 1]; [1; 1; 1]]

Array2D.createBased base1 base2 length1 length2 initial

Full Usage: Array2D.createBased base1 base2 length1 length2 initial

Parameters:
    base1 : int - The base for the first dimension of the array.
    base2 : int - The base for the second dimension of the array.
    length1 : int - The length of the first dimension of the array.
    length2 : int - The length of the second dimension of the array.
    initial : 'T - The value to populate the new array.

Returns: 'T[,] The created array.

Creates a based array whose elements are all initially the given value.

base1 : int

The base for the first dimension of the array.

base2 : int

The base for the second dimension of the array.

length1 : int

The length of the first dimension of the array.

length2 : int

The length of the second dimension of the array.

initial : 'T

The value to populate the new array.

Returns: 'T[,]

The created array.

ArgumentException Thrown when base1, base2, length1, or length2 is negative.
Example


 Array2D.createBased 1 1 2 3 1
Evaluates to a 2x3 1-based array with contents [[1; 1; 1]; [1; 1; 1]]

Array2D.get array index1 index2

Full Usage: Array2D.get array index1 index2

Parameters:
    array : 'T[,] - The input array.
    index1 : int - The index along the first dimension.
    index2 : int - The index along the second dimension.

Returns: 'T The value of the array at the given index.

Fetches an element from a 2D array. You can also use the syntax array.[index1,index2].

Indexer syntax is generally preferred, e.g.


 let array = array2D [ [ 1.0; 2.0 ]; [ 3.0; 4.0 ] ]

 array[0,1]
Evaluates to 2.0.

array : 'T[,]

The input array.

index1 : int

The index along the first dimension.

index2 : int

The index along the second dimension.

Returns: 'T

The value of the array at the given index.

ArgumentException Thrown when the indices are negative or exceed the bounds of the array.
Example


 let array = array2D [ [ 1.0; 2.0 ]; [ 3.0; 4.0 ] ]

 Array2D.get array 0 1
Evaluates to 2.0.

Array2D.init length1 length2 initializer

Full Usage: Array2D.init length1 length2 initializer

Parameters:
    length1 : int - The length of the first dimension of the array.
    length2 : int - The length of the second dimension of the array.
    initializer : int -> int -> 'T - A function to produce elements of the array given the two indices.

Returns: 'T[,] The generated array.

Creates an array given the dimensions and a generator function to compute the elements.

length1 : int

The length of the first dimension of the array.

length2 : int

The length of the second dimension of the array.

initializer : int -> int -> 'T

A function to produce elements of the array given the two indices.

Returns: 'T[,]

The generated array.

ArgumentException Thrown when either of the lengths is negative.
Example


 Array2D.init 2 3 (fun i j -> i + j)
Evaluates to a 2x3 array with contents [[0; 1; 2]; [1; 2; 3]]

Array2D.initBased base1 base2 length1 length2 initializer

Full Usage: Array2D.initBased base1 base2 length1 length2 initializer

Parameters:
    base1 : int - The base for the first dimension of the array.
    base2 : int - The base for the second dimension of the array.
    length1 : int - The length of the first dimension of the array.
    length2 : int - The length of the second dimension of the array.
    initializer : int -> int -> 'T - A function to produce elements of the array given the two indices.

Returns: 'T[,] The created array.

Creates a based array given the dimensions and a generator function to compute the elements.

base1 : int

The base for the first dimension of the array.

base2 : int

The base for the second dimension of the array.

length1 : int

The length of the first dimension of the array.

length2 : int

The length of the second dimension of the array.

initializer : int -> int -> 'T

A function to produce elements of the array given the two indices.

Returns: 'T[,]

The created array.

ArgumentException Thrown when base1, base2, length1, or length2 is negative.
Example


 Array2D.initBased 1 1 2 3 (fun i j -> i + j)
Evaluates to a 2x3 1-based array with contents [[2; 3; 4]; [3; 4; 5]]

Array2D.iter action array

Full Usage: Array2D.iter action array

Parameters:
    action : 'T -> unit - A function to apply to each element of the array.
    array : 'T[,] - The input array.

Applies the given function to each element of the array.

action : 'T -> unit

A function to apply to each element of the array.

array : 'T[,]

The input array.

Example


 let inputs = array2D [ [ 3; 4 ]; [ 13; 14 ] ]

 inputs |> Array2D.iter (fun v -> printfn $"value = {v}")
Evaluates to unit and prints

 value = 3
 value = 4
 value = 13
 value = 14
in the console.

Array2D.iteri action array

Full Usage: Array2D.iteri action array

Parameters:
    action : int -> int -> 'T -> unit - A function to apply to each element of the array with the indices available as an argument.
    array : 'T[,] - The input array.

Applies the given function to each element of the array. The integer indices passed to the function indicates the index of element.

action : int -> int -> 'T -> unit

A function to apply to each element of the array with the indices available as an argument.

array : 'T[,]

The input array.

Example


 let inputs = array2D [ [ 3; 4 ]; [ 13; 14 ] ]

 inputs |> Array2D.iteri (fun i j v -> printfn $"value at ({i},{j}) = {v}")
Evaluates to unit and prints

 value at (0,0) = 3
 value at (0,1) = 4
 value at (1,0) = 13
 value at (1,1) = 14
in the console.

Array2D.length1 array

Full Usage: Array2D.length1 array

Parameters:
    array : 'T[,] - The input array.

Returns: int The length of the array in the first dimension.

Returns the length of an array in the first dimension.

array : 'T[,]

The input array.

Returns: int

The length of the array in the first dimension.

Example


 let array = array2D [ [ 3; 4; 5 ]; [ 13; 14; 15 ] ]

 array |> Array2D.length1
Evaluates to 2.

Array2D.length2 array

Full Usage: Array2D.length2 array

Parameters:
    array : 'T[,] - The input array.

Returns: int The length of the array in the second dimension.

Returns the length of an array in the second dimension.

array : 'T[,]

The input array.

Returns: int

The length of the array in the second dimension.

Example


 let array = array2D [ [ 3; 4; 5 ]; [ 13; 14; 15 ] ]

 array |> Array2D.length2
Evaluates to 3.

Array2D.map mapping array

Full Usage: Array2D.map mapping array

Parameters:
    mapping : 'T -> 'U - A function that is applied to transform each item of the input array.
    array : 'T[,] - The input array.

Returns: 'U[,] An array whose elements have been transformed by the given mapping.

Builds a new array whose elements are the results of applying the given function to each of the elements of the array.

For non-zero-based arrays the basing on an input array will be propagated to the output array.

mapping : 'T -> 'U

A function that is applied to transform each item of the input array.

array : 'T[,]

The input array.

Returns: 'U[,]

An array whose elements have been transformed by the given mapping.

Example


 let inputs = array2D [ [ 3; 4 ]; [ 13; 14 ] ]

 inputs |> Array2D.map (fun v -> 2 * v)
Evaluates to a 2x2 array with contents [[6; 8;]; [26; 28]]

Array2D.mapi mapping array

Full Usage: Array2D.mapi mapping array

Parameters:
    mapping : int -> int -> 'T -> 'U - A function that is applied to transform each element of the array. The two integers provide the index of the element.
    array : 'T[,] - The input array.

Returns: 'U[,] An array whose elements have been transformed by the given mapping.

Builds a new array whose elements are the results of applying the given function to each of the elements of the array. The integer indices passed to the function indicates the element being transformed.

For non-zero-based arrays the basing on an input array will be propagated to the output array.

mapping : int -> int -> 'T -> 'U

A function that is applied to transform each element of the array. The two integers provide the index of the element.

array : 'T[,]

The input array.

Returns: 'U[,]

An array whose elements have been transformed by the given mapping.

Example


 let inputs = array2D [ [ 3; 4 ]; [ 13; 14 ] ]

 inputs |> Array2D.mapi (fun i j v -> i + j + v)
Evaluates to a 2x2 array with contents [[3; 5;]; [14; 16]]

Array2D.rebase array

Full Usage: Array2D.rebase array

Parameters:
    array : 'T[,] - The input array.

Returns: 'T[,] The zero-based output array.

Builds a new array whose elements are the same as the input array but where a non-zero-based input array generates a corresponding zero-based output array.

array : 'T[,]

The input array.

Returns: 'T[,]

The zero-based output array.

Example


 let inputs = Array2D.createBased 1 1 2 3 1

 inputs |> Array2D.rebase
Evaluates to a 2x2 zero-based array with contents [[1; 1]; [1; 1]]

Array2D.set array index1 index2 value

Full Usage: Array2D.set array index1 index2 value

Parameters:
    array : 'T[,] - The input array.
    index1 : int - The index along the first dimension.
    index2 : int - The index along the second dimension.
    value : 'T - The value to set in the array.

Sets the value of an element in an array. You can also use the syntax array.[index1,index2] <- value.

Indexer syntax is generally preferred, e.g.


 let array = Array2D.zeroCreate 2 2

 array[0,1] <- 4.0

array : 'T[,]

The input array.

index1 : int

The index along the first dimension.

index2 : int

The index along the second dimension.

value : 'T

The value to set in the array.

ArgumentException Thrown when the indices are negative or exceed the bounds of the array.
Example


 let array = Array2D.zeroCreate 2 2

 Array2D.set array 0 1 4.0
After evaluation array is a 2x2 array with contents [[0.0; 4.0]; [0.0; 0.0]]

Array2D.zeroCreate length1 length2

Full Usage: Array2D.zeroCreate length1 length2

Parameters:
    length1 : int - The length of the first dimension of the array.
    length2 : int - The length of the second dimension of the array.

Returns: 'T[,] The created array.

Creates an array where the entries are initially Unchecked.defaultof<'T>.

length1 : int

The length of the first dimension of the array.

length2 : int

The length of the second dimension of the array.

Returns: 'T[,]

The created array.

ArgumentException Thrown when length1 or length2 is negative.
Example


 Array2D.zeroCreate 2 3
Evaluates to a 2x3 array with contents [[0; 0; 0]; [0; 0; 0]]

Array2D.zeroCreateBased base1 base2 length1 length2

Full Usage: Array2D.zeroCreateBased base1 base2 length1 length2

Parameters:
    base1 : int - The base for the first dimension of the array.
    base2 : int - The base for the second dimension of the array.
    length1 : int - The length of the first dimension of the array.
    length2 : int - The length of the second dimension of the array.

Returns: 'T[,] The created array.

Creates a based array where the entries are initially Unchecked.defaultof<'T>.

base1 : int

The base for the first dimension of the array.

base2 : int

The base for the second dimension of the array.

length1 : int

The length of the first dimension of the array.

length2 : int

The length of the second dimension of the array.

Returns: 'T[,]

The created array.

ArgumentException Thrown when base1, base2, length1, or length2 is negative.
Example


 Array2D.zeroCreateBased 1 1 2 3
Evaluates to a 2x3 1-based array with contents [[0; 0; 0]; [0; 0; 0]]