FSharp.Core

Array2D Module

Namespace: FSharp.Collections
Assembly: FSharp.Core.dll

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
namespace System
Multiple items
val array: int array2d

--------------------
type 'T array = 'T array
type Array = interface ICollection interface IEnumerable interface IList interface IStructuralComparable interface IStructuralEquatable interface ICloneable member Clone: unit -> obj member CopyTo: array: Array * index: int -> unit + 1 overload member GetEnumerator: unit -> IEnumerator member GetLength: dimension: int -> int ...
<summary>Provides methods for creating, manipulating, searching, and sorting arrays, thereby serving as the base class for all arrays in the common language runtime.</summary>
Array.CreateInstance(elementType: Type, [<ParamArray>] lengths: int64 array) : Array
Array.CreateInstance(elementType: Type, [<ParamArray>] lengths: int array) : Array
Array.CreateInstance(elementType: Type, length: int) : Array
Array.CreateInstance(elementType: Type, lengths: int array, lowerBounds: int array) : Array
Array.CreateInstance(elementType: Type, length1: int, length2: int) : Array
Array.CreateInstance(elementType: Type, length1: int, length2: int, length3: int) : Array
val typeof<'T> : Type
Multiple items
val int: value: 'T -> int (requires member op_Explicit)

--------------------
type int = int32

--------------------
type int<'Measure> = int
module Array2D from Microsoft.FSharp.Collections
val base1: array: 'T array2d -> int
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
namespace System
Multiple items
val array: int array2d

--------------------
type 'T array = 'T array
type Array = interface ICollection interface IEnumerable interface IList interface IStructuralComparable interface IStructuralEquatable interface ICloneable member Clone: unit -> obj member CopyTo: array: Array * index: int -> unit + 1 overload member GetEnumerator: unit -> IEnumerator member GetLength: dimension: int -> int ...
<summary>Provides methods for creating, manipulating, searching, and sorting arrays, thereby serving as the base class for all arrays in the common language runtime.</summary>
Array.CreateInstance(elementType: Type, [<ParamArray>] lengths: int64 array) : Array
Array.CreateInstance(elementType: Type, [<ParamArray>] lengths: int array) : Array
Array.CreateInstance(elementType: Type, length: int) : Array
Array.CreateInstance(elementType: Type, lengths: int array, lowerBounds: int array) : Array
Array.CreateInstance(elementType: Type, length1: int, length2: int) : Array
Array.CreateInstance(elementType: Type, length1: int, length2: int, length3: int) : Array
val typeof<'T> : Type
Multiple items
val int: value: 'T -> int (requires member op_Explicit)

--------------------
type int = int32

--------------------
type int<'Measure> = int
module Array2D from Microsoft.FSharp.Collections
val base2: array: 'T array2d -> int
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
val source: int array2d
val array2D: rows: seq<#seq<'T>> -> 'T array2d
val target: int array2d

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
val source: int array2d
val array2D: rows: seq<#seq<'T>> -> 'T array2d
val target: int array2d
module Array2D from Microsoft.FSharp.Collections
val blit: source: 'T array2d -> sourceIndex1: int -> sourceIndex2: int -> target: 'T array2d -> targetIndex1: int -> targetIndex2: int -> length1: int -> length2: int -> unit
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
namespace System
Multiple items
val array: int array2d

--------------------
type 'T array = 'T array
module Array2D from Microsoft.FSharp.Collections
val zeroCreate: length1: int -> length2: int -> 'T array2d
Multiple items
val int: value: 'T -> int (requires member op_Explicit)

--------------------
type int = int32

--------------------
type int<'Measure> = int
val copy: array: 'T array2d -> 'T array2d
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
module Array2D from Microsoft.FSharp.Collections
val create: length1: int -> length2: int -> value: 'T -> 'T array2d
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
module Array2D from Microsoft.FSharp.Collections
val createBased: base1: int -> base2: int -> length1: int -> length2: int -> initial: 'T -> 'T array2d
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]
Multiple items
val array: float array2d

--------------------
type 'T array = 'T array
val array2D: rows: seq<#seq<'T>> -> 'T array2d
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
Multiple items
val array: float array2d

--------------------
type 'T array = 'T array
val array2D: rows: seq<#seq<'T>> -> 'T array2d
module Array2D from Microsoft.FSharp.Collections
val get: array: 'T array2d -> index1: int -> index2: int -> 'T
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)
module Array2D from Microsoft.FSharp.Collections
val init: length1: int -> length2: int -> initializer: (int -> int -> 'T) -> 'T array2d
val i: int
val j: int
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)
module Array2D from Microsoft.FSharp.Collections
val initBased: base1: int -> base2: int -> length1: int -> length2: int -> initializer: (int -> int -> 'T) -> 'T array2d
val i: int
val j: int
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}")
val inputs: int array2d
val array2D: rows: seq<#seq<'T>> -> 'T array2d
module Array2D from Microsoft.FSharp.Collections
val iter: action: ('T -> unit) -> array: 'T array2d -> unit
val v: int
val printfn: format: Printf.TextWriterFormat<'T> -> 'T
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}")
val inputs: int array2d
val array2D: rows: seq<#seq<'T>> -> 'T array2d
module Array2D from Microsoft.FSharp.Collections
val iteri: action: (int -> int -> 'T -> unit) -> array: 'T array2d -> unit
val i: int
val j: int
val v: int
val printfn: format: Printf.TextWriterFormat<'T> -> 'T
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
Multiple items
val array: int array2d

--------------------
type 'T array = 'T array
val array2D: rows: seq<#seq<'T>> -> 'T array2d
module Array2D from Microsoft.FSharp.Collections
val length1: array: 'T array2d -> int
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
Multiple items
val array: int array2d

--------------------
type 'T array = 'T array
val array2D: rows: seq<#seq<'T>> -> 'T array2d
module Array2D from Microsoft.FSharp.Collections
val length2: array: 'T array2d -> int
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)
val inputs: int array2d
val array2D: rows: seq<#seq<'T>> -> 'T array2d
module Array2D from Microsoft.FSharp.Collections
val map: mapping: ('T -> 'U) -> array: 'T array2d -> 'U array2d
val v: int
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)
val inputs: int array2d
val array2D: rows: seq<#seq<'T>> -> 'T array2d
module Array2D from Microsoft.FSharp.Collections
val mapi: mapping: (int -> int -> 'T -> 'U) -> array: 'T array2d -> 'U array2d
val i: int
val j: int
val v: int
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
val inputs: int array2d
module Array2D from Microsoft.FSharp.Collections
val createBased: base1: int -> base2: int -> length1: int -> length2: int -> initial: 'T -> 'T array2d
val rebase: array: 'T array2d -> 'T array2d
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
Multiple items
val array: float array2d

--------------------
type 'T array = 'T array
module Array2D from Microsoft.FSharp.Collections
val zeroCreate: length1: int -> length2: int -> 'T array2d

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
Multiple items
val array: float array2d

--------------------
type 'T array = 'T array
module Array2D from Microsoft.FSharp.Collections
val zeroCreate: length1: int -> length2: int -> 'T array2d
val set: array: 'T array2d -> index1: int -> index2: int -> value: 'T -> unit
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
module Array2D from Microsoft.FSharp.Collections
val zeroCreate: length1: int -> length2: int -> 'T array2d
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
module Array2D from Microsoft.FSharp.Collections
val zeroCreateBased: base1: int -> base2: int -> length1: int -> length2: int -> 'T array2d
Evaluates to a 2x3 1-based array with contents [[0; 0; 0]; [0; 0; 0]]