The Standard ML Basis Library


The MONO_ARRAY2 signature

The MONO_ARRAY2 signature is a generic interface to mutable 2-dimensional arrays. Arrays also have a special equality property: two arrays are equal if they are the same array, i.e., created by the same call to a primitive array constructor such as array, fromList, etc.; otherwise they are not equal. This also holds for arrays of zero length. Thus, type t array admits equality even if ty does not.


Synopsis

signature MONO_ARRAY2
structure Word8Array2 : MONO_ARRAY2
structure CharArray2 : MONO_ARRAY2
structure WideCharArray2 : MONO_ARRAY2
structure BoolArray2 : MONO_ARRAY2
structure IntArray2 : MONO_ARRAY2
structure RealArray2 : MONO_ARRAY2
structure Int{N}Array2 : MONO_ARRAY2
structure Real{N}Array2 : MONO_ARRAY2

Interface

eqtype array
type elem
type 'a region = {base : 'a array, row : int, col : int, nrows : int option, ncols : int option}
datatype traversal = datatype Array2.traversal
structure Vector : MONO_VECTOR
val array : (int * int * elem) -> array
val fromList : elem list list -> array
val tabulate : traversal -> (int * int * ((int * int) -> elem)) -> array
val sub : (array * int * int) -> elem
val update : (array * int * int * elem) -> unit
val dimensions : array -> (int * int)
val nCols : array -> int
val nRows : array -> int
val row : (array * int) -> Vector.vector
val column : (array * int) -> Vector.vector
val copy : {src : region, dst : array, dst_row : int, dst_col : int} -> unit
val appi : Array2.traversal -> ((int * int * elem) -> unit) -> region -> unit
val app : Array2.traversal -> (elem -> unit) -> array -> unit
val modifyi : Array2.traversal -> ((int * int * elem) -> elem) -> region -> unit
val modify : Array2.traversal -> (elem -> elem) -> array -> unit
val foldi : Array2.traversal -> ((int * int * elem * 'b) -> 'b) -> 'b -> region -> 'b
val fold : Array2.traversal -> ((elem * 'b) -> 'b) -> 'b -> array -> 'b

Description

eqtype array

type elem

type 'a region
This type specifies a rectangular subregion of a 2-dimensional array. It serves the same role as the slice for 1-dimensional arrays and vectors. If ncols = SOME w, the region includes only those elements in columns with indices in the range col + (w - 1) (inclusive). If ncols = NONE, the region includes only those elements lying on or to the right of column col. A similar interpretation holds for the row and nrows fields. Thus, the region corresponds to all those elements with position (i,j) such that i lies in the specified range of rows and j lies in the specified range of columns. If arr is an array, with dimensions arr = (rows,cols), then a region is said to be valid with respect to arr if
0 <= row <= row+nr <= rows
and
0 <= col <= col+nc <= cols
where nr and nc are the number of rows and columns, respectively, of the region.

datatype traversal
specifies way of traversing a region.

structure Vector

array (r, c, init)
creates a new array with r rows and c columns, with each element initialized to the value init. If r < 0, c < 0 or the resulting array size is too large, the Size exception is raised.

fromList l
creates a new array from a list of a list of elements. The elements should be presented in row major form, i.e., hd l gives the first row, hd (tl l) gives the second row, etc. Raises the Size exception if the the resulting array size is too large, or if the lists in l do not all have the same length.

tabulate tr (r, c, f)
creates a new array with r rows and c columns, with the (i,j)th element initialized to f (i,j). The elements are initialized in the traversal order specified by tr. If r < 0, c < 0 or the resulting array size is too large, the Size exception is raised.

sub (arr, i, j)
returns the (i,j)th element of the array arr. If i < 0, j < 0, nRows arr <= i or nCols arr <= j, then the Subscript exception is raised.

update (arr, i, j, a)
sets the (i,j)th element of the array arr to a. If i < 0, j < 0, nRows arr <= i or nCols arr <= j, then the Subscript exception is raised.

dimensions arr
nCols arr
nRows arr
return size information concerning arr. nCols returns the number of columns, nRows returns the number of rows and dimension returns a pair containing the number of rows and columns of arr. The functions nRows and nCols are respectively equivalent to #1 o dimensions and #2 o dimensions

row (arr, i)
returns row i of arr. Raises Subscript if i < 0 or nRows arr <= i.

column (arr, j)
returns column j of arr. Raises Subscript if j < 0 or nCols arr <= j.

copy {src, dst, dst_row, dst_col}
copies the region src into the array dst, with the (#row src,#col src)th element being copied to position (dst_row,dst_col) in the destination array. If the source region is not valid, then the Subscript exception is raised. Similarly, if the derived destination region (the source region src translated to (dst_row,dst_col)) is not valid in dst, then the Subscript exception is raised.
Implementation note:

The copy function must correctly handle the case in which src and dst are equal, and the source and destination regions overlap.



appi tr f reg
app tr f arr
apply the function f to the elements of an array in the order specified by tr. The more general appi function applies f to the elements of the region reg and supplies both the element and the element's coordinates to the function f. If reg is not valid, then the exception Subscript is raised.

The function app applies f to the whole array and does not supply the element index to f. Thus the expression app tr f arr is equivalent to:

	    appi tr (f o #3) (arr, {row=0, col=0, nrows=NONE, ncols=NONE})
	  


modifyi tr f reg
modify tr f arr
apply the function f to the elements of an array in the order specified by tr, and replace each element with the result of f. The more general modifyi function applies f to the elements of the region reg and supplies both the element and the element's coordinates to the function f. If reg is not valid, then the exception Subscript is raised.

The function modify applies f to the whole array and does not supply the element index to f. Thus the expression modify f arr is equivalent to:

	    modifyi (f o #3) (arr, {row=0, col=0, nrows=NONE, ncols=NONE})
	  


foldi tr f init reg
fold tr f init arr
fold the function f over the elements of an array arr, traversing the elements in tr order, and using the value init as the initial value. The more general foldi function applies f to the elements of the region reg and supplies both the element and the element's coordinates to the function f. If reg is not valid, then the exception Subscript is raised.

The function fold applies f to the whole array and does not supply the element index to f. Thus the expression fold tr f init arr is equivalent to:

	    foldi tr (fn (_,_,a,b) => f (a,b)) init (arr, {row=0, col=0, nrows=NONE, ncols=NONE})
	  



Discussion

If an implementation provides any structure matching MONO_ARRAY2, it must also supply the structure Array2 and its signature ARRAY2.

See Also

Array2

[ INDEX | TOP | Parent | Root ]

Last Modified April 14, 1997
Comments to John Reppy.
Copyright © 1997 Bell Labs, Lucent Technologies