Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Bigarray(3)			 OCaml library			   Bigarray(3)

       Bigarray	- Large, multi-dimensional, numerical arrays.

       Module	Bigarray

       Module Bigarray
	: sig end

       Large, multi-dimensional, numerical arrays.

       This  module implements multi-dimensional arrays	of integers and	float-
       ing-point numbers, thereafter referred to as 'big arrays'.  The	imple-
       mentation  allows  efficient  sharing of	large numerical	arrays between
       OCaml code and C	or Fortran numerical libraries.

       Concerning the naming conventions, users	of this	module are  encouraged
       to  do open Bigarray in their source, then refer	to array types and op-
       erations	via short dot notation,	e.g.  Array1.t or Array2.sub .

       Big arrays support all the OCaml	ad-hoc polymorphic operations:

       -comparisons ( =	, <> , <= , etc, as well as );

       -hashing	(module	Hash );

       -and structured input-output (the functions from	the Marshal module, as
       well as Pervasives.output_value and Pervasives.input_value ).

       === Element kinds ===

       === Element kinds ===

       === Big arrays can contain elements of the following kinds: - IEEE sin-
       gle precision (32 bits) floating-point numbers  (Bigarray.float32_elt),
       -  IEEE	double	precision  (64	bits)  floating-point  numbers (Bigar-
       ray.float64_elt), - IEEE	single precision (2 * 32 bits)	floating-point
       complex	numbers	(Bigarray.complex32_elt), - IEEE double	precision (2 *
       64 bits)	floating-point	complex	 numbers  (Bigarray.complex64_elt),  -
       8-bit integers (signed or unsigned) (Bigarray.int8_signed_elt or	Bigar-
       ray.int8_unsigned_elt), - 16-bit	integers (signed or unsigned)  (Bigar-
       ray.int16_signed_elt  or	Bigarray.int16_unsigned_elt), -	OCaml integers
       (signed,	31 bits	on 32-bit architectures, 63 bits on  64-bit  architec-
       tures)	 (Bigarray.int_elt),   -   32-bit   signed   integer   (Bigar-
       ray.int32_elt), - 64-bit	signed integers	(Bigarray.int64_elt), -	 plat-
       form-native  signed  integers (32 bits on 32-bit	architectures, 64 bits
       on 64-bit architectures)	(Bigarray.nativeint_elt).  Each	 element  kind
       is  represented at the type level by one	of the *_elt types defined be-
       low (defined with a single constructor instead of  abstract  types  for
       technical injectivity reasons). ===

       type float32_elt	=
	| Float32_elt

       type float64_elt	=
	| Float64_elt

       type int8_signed_elt =
	| Int8_signed_elt

       type int8_unsigned_elt =
	| Int8_unsigned_elt

       type int16_signed_elt =
	| Int16_signed_elt

       type int16_unsigned_elt =
	| Int16_unsigned_elt

       type int32_elt =
	| Int32_elt

       type int64_elt =
	| Int64_elt

       type int_elt =
	| Int_elt

       type nativeint_elt =
	| Nativeint_elt

       type complex32_elt =
	| Complex32_elt

       type complex64_elt =
	| Complex64_elt

       type ('a, 'b) kind =
	| Float32 : (float, float32_elt) kind
	| Float64 : (float, float64_elt) kind
	| Int8_signed :	(int, int8_signed_elt) kind
	| Int8_unsigned	: (int,	int8_unsigned_elt) kind
	| Int16_signed : (int, int16_signed_elt) kind
	| Int16_unsigned : (int, int16_unsigned_elt) kind
	| Int32	: (int32, int32_elt) kind
	| Int64	: (int64, int64_elt) kind
	| Int :	(int, int_elt) kind
	| Nativeint : (nativeint, nativeint_elt) kind
	| Complex32 : (Complex.t, complex32_elt) kind
	| Complex64 : (Complex.t, complex64_elt) kind
	| Char : (char,	int8_unsigned_elt) kind
	 (*  To	 each  element	kind is	associated an OCaml type, which	is the
       type of OCaml values that can be	stored in the big array	or  read  back
       from  it.  This type is not necessarily the same	as the type of the ar-
       ray elements proper: for	instance, a big	array whose  elements  are  of
       kind  float32_elt  contains 32-bit single precision floats, but reading
       or writing one of its elements from OCaml uses the OCaml	type  float  ,
       which is	64-bit double precision	floats.

       The  GADT type ('a, 'b) kind captures this association of an OCaml type
       'a for values read or written in	the big	array, and of an element  kind
       'b which	represents the actual contents of the big array. Its construc-
       tors list all possible associations of OCaml types with element	kinds,
       and are re-exported below for backward-compatibility reasons.

       Using  a	 generalized  algebraic	 datatype  (GADT) here allows to write
       well-typed polymorphic functions	whose return type depend on the	 argu-
       ment type, such as:

       let  zero  :  type  a b.	(a, b) kind -> a = function | Float32 -> 0.0 |
       Complex32 -> | Float64 -> 0.0 | Complex64 ->
       | Int8_signed ->	0 | Int8_unsigned -> 0 | Int16_signed -> 0 | Int16_un-
       signed -> 0 | Int32 -> 0l | Int64 -> 0L | Int ->	0 | Nativeint -> 0n  |
       Char -> '\000'


       val float32 : (float, float32_elt) kind

       See Bigarray.char .

       val float64 : (float, float64_elt) kind

       See Bigarray.char .

       val complex32 : (Complex.t, complex32_elt) kind

       See Bigarray.char .

       val complex64 : (Complex.t, complex64_elt) kind

       See Bigarray.char .

       val int8_signed : (int, int8_signed_elt)	kind

       See Bigarray.char .

       val int8_unsigned : (int, int8_unsigned_elt) kind

       See Bigarray.char .

       val int16_signed	: (int,	int16_signed_elt) kind

       See Bigarray.char .

       val int16_unsigned : (int, int16_unsigned_elt) kind

       See Bigarray.char .

       val int : (int, int_elt)	kind

       See Bigarray.char .

       val int32 : (int32, int32_elt) kind

       See Bigarray.char .

       val int64 : (int64, int64_elt) kind

       See Bigarray.char .

       val nativeint : (nativeint, nativeint_elt) kind

       See Bigarray.char .

       val char	: (char, int8_unsigned_elt) kind

       As  shown  by  the  types  of  the  values  above,  big	arrays of kind
       float32_elt and float64_elt are accessed	using the OCaml	type  float  .
       Big  arrays of complex kinds complex32_elt , complex64_elt are accessed
       with the	OCaml type Complex.t . Big arrays of  integer  kinds  are  ac-
       cessed  using the smallest OCaml	integer	type large enough to represent
       the array elements: int for 8- and 16-bit integer bigarrays, as well as
       OCaml-integer  bigarrays; int32 for 32-bit integer bigarrays; int64 for
       64-bit integer bigarrays; and nativeint for platform-native integer bi-
       garrays.	 Finally, big arrays of	kind int8_unsigned_elt can also	be ac-
       cessed as arrays	of characters instead of arrays	of small integers,  by
       using the kind value char instead of int8_unsigned .

       === Array layouts ===

       type c_layout =
	| C_layout_typ	(* See Bigarray.fortran_layout .

       type fortran_layout =
	|  Fortran_layout_typ  (* To facilitate	interoperability with existing
       C and Fortran code, this	library	supports two different memory  layouts
       for  big	 arrays, one compatible	with the C conventions,	the other com-
       patible with the	Fortran	conventions.

       In the C-style layout, array indices start at 0,	and  multi-dimensional
       arrays  are  laid  out  in row-major format.  That is, for a two-dimen-
       sional array, all elements of row 0 are contiguous in memory,  followed
       by  all	elements of row	1, etc.	 In other terms, the array elements at
       (x,y) and (x, y+1) are adjacent in memory.

       In the Fortran-style layout, array indices start	at 1, and multi-dimen-
       sional  arrays  are  laid  out  in column-major format.	That is, for a
       two-dimensional array, all elements of column 0 are contiguous in  mem-
       ory,  followed  by  all elements	of column 1, etc.  In other terms, the
       array elements at (x,y) and (x+1, y) are	adjacent in memory.

       Each layout style is identified at the type level by the	phantom	 types
       Bigarray.c_layout and Bigarray.fortran_layout respectively.

       === Supported layouts The GADT type 'a layout represents	one of the two
       supported memory	layouts: C-style or  Fortran-style.  Its  constructors
       are re-exported as values below for backward-compatibility reasons. ===

       type 'a layout =
	| C_layout : c_layout layout
	| Fortran_layout : fortran_layout layout

       val c_layout : c_layout layout

       val fortran_layout : fortran_layout layout

       === Generic arrays (of arbitrarily many dimensions) ===

       module Genarray : sig end

       === One-dimensional arrays ===

       module Array1 : sig end

       One-dimensional	arrays.	The Array1 structure provides operations simi-
       lar to those of Bigarray.Genarray , but	specialized  to	 the  case  of
       one-dimensional	arrays.	  (The Array2 and Array3 structures below pro-
       vide operations specialized for	two-  and  three-dimensional  arrays.)
       Statically  knowing the number of dimensions of the array allows	faster
       operations, and more precise static type-checking.

       === Two-dimensional arrays ===

       module Array2 : sig end

       Two-dimensional arrays. The Array2 structure provides operations	 simi-
       lar  to	those  of  Bigarray.Genarray  ,	but specialized	to the case of
       two-dimensional arrays.

       === Three-dimensional arrays ===

       module Array3 : sig end

       Three-dimensional arrays. The Array3 structure provides operations sim-
       ilar  to	 those	of  Bigarray.Genarray ,	but specialized	to the case of
       three-dimensional arrays.

       === Coercions between generic big arrays	and fixed-dimension big	arrays

       val  genarray_of_array1	: ('a, 'b, 'c) Array1.t	-> ('a,	'b, 'c)	Genar-

       Return the generic big array corresponding to the given one-dimensional
       big array.

       val  genarray_of_array2	: ('a, 'b, 'c) Array2.t	-> ('a,	'b, 'c)	Genar-

       Return the generic big array corresponding to the given two-dimensional
       big array.

       val  genarray_of_array3	: ('a, 'b, 'c) Array3.t	-> ('a,	'b, 'c)	Genar-

       Return the generic big array corresponding to  the  given  three-dimen-
       sional big array.

       val  array1_of_genarray	:  ('a,	'b, 'c)	Genarray.t -> ('a, 'b, 'c) Ar-

       Return the one-dimensional big array corresponding to the given generic
       big  array.   Raise  Invalid_argument if	the generic big	array does not
       have exactly one	dimension.

       val array2_of_genarray :	('a, 'b, 'c) Genarray.t	-> ('a,	 'b,  'c)  Ar-

       Return the two-dimensional big array corresponding to the given generic
       big array.  Raise Invalid_argument if the generic big  array  does  not
       have exactly two	dimensions.

       val  array3_of_genarray	:  ('a,	'b, 'c)	Genarray.t -> ('a, 'b, 'c) Ar-

       Return the three-dimensional  big  array	 corresponding	to  the	 given
       generic	big  array.   Raise  Invalid_argument if the generic big array
       does not	have exactly three dimensions.

       === Re-shaping big arrays ===

       val reshape : ('a, 'b, 'c) Genarray.t ->	int  array  ->	('a,  'b,  'c)

       reshape	b  [|d1;...;dN|]  converts the big array b to a	N -dimensional
       array of	dimensions d1 ...  dN .	 The returned array and	 the  original
       array  b	 share their data and have the same layout.  For instance, as-
       suming that b is	a one-dimensional array	of  dimension  12,  reshape  b
       [|3;4|] returns a two-dimensional array b' of dimensions	3 and 4.  If b
       has C layout, the element (x,y) of b' corresponds to the	element	x *  3
       +  y  of	 b  .  If b has	Fortran	layout,	the element (x,y) of b'	corre-
       sponds to the element x + (y - 1) * 4 of	b .  The  returned  big	 array
       must have exactly the same number of elements as	the original big array
       b .  That is, the product of the	dimensions of b	must be	equal to i1  *
       ... * iN	.  Otherwise, Invalid_argument is raised.

       val reshape_1 : ('a, 'b,	'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t

       Specialized  version  of	 Bigarray.reshape  for reshaping to one-dimen-
       sional arrays.

       val reshape_2 : ('a, 'b,	'c) Genarray.t -> int -> int ->	('a,  'b,  'c)

       Specialized  version  of	 Bigarray.reshape  for reshaping to two-dimen-
       sional arrays.

       val reshape_3 : ('a, 'b,	'c) Genarray.t -> int -> int ->	 int  ->  ('a,
       'b, 'c) Array3.t

       Specialized  version  of	Bigarray.reshape for reshaping to three-dimen-
       sional arrays.

OCamldoc			  2017-04-30			   Bigarray(3)

NAME | Module | Documentation

Want to link to this manual page? Use this URL:

home | help