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

FreeBSD Manual Pages

  
 
  

home | help
Bigarray.Genarray(3)		   OCamldoc		  Bigarray.Genarray(3)

NAME
       Bigarray.Genarray - no description

Module
       Module	Bigarray.Genarray

Documentation
       Module Genarray
	: sig end

       type ('a, 'b, 'c) t

       The  type Genarray.t is the type	of big arrays with variable numbers of
       dimensions.  Any	number of dimensions between 0 and 16 is supported.

       The three type parameters to Genarray.t identify	the array element kind
       and layout, as follows:

       -the  first  parameter, 'a , is the OCaml type for accessing array ele-
       ments ( float , int , int32 , int64 , nativeint );

       -the second parameter, 'b , is the actual  kind	of  array  elements  (
       float32_elt , float64_elt , int8_signed_elt , int8_unsigned_elt , etc);

       -the  third  parameter,	'c , identifies	the array layout ( c_layout or
       fortran_layout ).

       For instance, (float, float32_elt, fortran_layout)  Genarray.t  is  the
       type  of	generic	big arrays containing 32-bit floats in Fortran layout;
       reads and writes	in this	array use the OCaml type float .

       val create : ('a, 'b) Bigarray.kind -> 'c Bigarray.layout -> int	 array
       -> ('a, 'b, 'c) t

       Genarray.create	kind  layout  dimensions returns a new big array whose
       element kind is determined by the parameter  kind  (one	of  float32  ,
       float64	, int8_signed ,	etc) and whose layout is determined by the pa-
       rameter layout (one of c_layout or fortran_layout  ).   The  dimensions
       parameter is an array of	integers that indicate the size	of the big ar-
       ray in each dimension.  The length of dimensions	determines the	number
       of dimensions of	the bigarray.

       For  instance, Genarray.create int32 c_layout [|4;6;8|] returns a fresh
       big array of 32-bit integers, in	C layout, having three dimensions, the
       three dimensions	being 4, 6 and 8 respectively.

       Big arrays returned by Genarray.create are not initialized: the initial
       values of array elements	is unspecified.

       Genarray.create raises Invalid_argument if the number of	dimensions  is
       not in the range	0 to 16	inclusive, or if one of	the dimensions is neg-
       ative.

       val num_dims : ('a, 'b, 'c) t ->	int

       Return the number of dimensions of the given big	array.

       val dims	: ('a, 'b, 'c) t -> int	array

       Genarray.dims a returns all dimensions of the big array a , as an array
       of integers of length Genarray.num_dims a .

       val nth_dim : ('a, 'b, 'c) t -> int -> int

       Genarray.nth_dim	 a  n returns the n -th	dimension of the big array a .
       The first dimension corresponds to n = 0	; the second dimension	corre-
       sponds  to n = 1	; the last dimension, to n = Genarray.num_dims a - 1 .
       Raise Invalid_argument if n is less than	0 or  greater  or  equal  than
       Genarray.num_dims a .

       val kind	: ('a, 'b, 'c) t -> ('a, 'b) Bigarray.kind

       Return the kind of the given big	array.

       val layout : ('a, 'b, 'c) t -> 'c Bigarray.layout

       Return the layout of the	given big array.

       val  change_layout  :  ('a, 'b, 'c) t ->	'd Bigarray.layout -> ('a, 'b,
       'd) t

       Genarray.change_layout a	layout returns a bigarray with	the  specified
       layout  , sharing the data with a (and hence having the same dimensions
       as a ). No copying of elements is involved: the new array and the orig-
       inal  array share the same storage space.  The dimensions are reversed,
       such that get v [| a; b |] in C layout becomes get v [| b+1; a+1	|]  in
       Fortran layout.

       Since 4.04.0

       val size_in_bytes : ('a,	'b, 'c)	t -> int

       size_in_bytes  a	 is the	number of elements in a	multiplied by a	's Bi-
       garray.kind_size_in_bytes .

       Since 4.03.0

       val get : ('a, 'b, 'c) t	-> int array ->	'a

       Read an element of a generic big	array.	Genarray.get a [|i1; ...; iN|]
       returns	the  element of	a whose	coordinates are	i1 in the first	dimen-
       sion, i2	in the second dimension, ..., iN in the	N -th dimension.

       If a has	C layout, the coordinates must be greater or equal than	0  and
       strictly	 less  than the	corresponding dimensions of a .	 If a has For-
       tran layout, the	coordinates must be greater or equal than 1  and  less
       or  equal than the corresponding	dimensions of a	.  Raise Invalid_argu-
       ment if the array a does	not have exactly N dimensions, or if the coor-
       dinates are outside the array bounds.

       If  N > 3 , alternate syntax is provided: you can write a.{i1, i2, ...,
       iN} instead of Genarray.get a [|i1; ...;	iN|] .	 (The  syntax  a.{...}
       with one, two or	three coordinates is reserved for accessing one-, two-
       and three-dimensional arrays as described below.)

       val set : ('a, 'b, 'c) t	-> int array ->	'a -> unit

       Assign an element of a generic big array.  Genarray.set	a  [|i1;  ...;
       iN|]  v stores the value	v in the element of a whose coordinates	are i1
       in the first dimension, i2 in the second	dimension, ...,	iN  in	the  N
       -th dimension.

       The  array  a  must have	exactly	N dimensions, and all coordinates must
       lie inside the array bounds, as described for Genarray.get ; otherwise,
       Invalid_argument	is raised.

       If  N > 3 , alternate syntax is provided: you can write a.{i1, i2, ...,
       iN} <- v	instead	of Genarray.set	a [|i1;	...; iN|]  v  .	  (The	syntax
       a.{...}	<- v with one, two or three coordinates	is reserved for	updat-
       ing one-, two- and three-dimensional arrays as described	below.)

       val sub_left : ('a, 'b, Bigarray.c_layout) t -> int -> int -> ('a,  'b,
       Bigarray.c_layout) t

       Extract	a  sub-array  of  the given big	array by restricting the first
       (left-most) dimension.  Genarray.sub_left a ofs len returns a big array
       with  the same number of	dimensions as a	, and the same dimensions as a
       , except	the first dimension, which corresponds to  the	interval  [ofs
       ...  ofs	 +  len	- 1] of	the first dimension of a .  No copying of ele-
       ments is	involved: the sub-array	and the	original array share the  same
       storage	space.	 In other terms, the element at	coordinates [|i1; ...;
       iN|] of the sub-array  is  identical  to	 the  element  at  coordinates
       [|i1+ofs; ...; iN|] of the original array a .

       Genarray.sub_left  applies  only	 to big	arrays in C layout.  Raise In-
       valid_argument if ofs and len do	not designate a	valid sub-array	of a ,
       that  is, if ofs	< 0 , or len < 0 , or ofs + len	> Genarray.nth_dim a 0
       .

       val sub_right : ('a, 'b,	Bigarray.fortran_layout) t -> int  ->  int  ->
       ('a, 'b,	Bigarray.fortran_layout) t

       Extract	a  sub-array  of  the  given big array by restricting the last
       (right-most) dimension.	Genarray.sub_right a ofs len returns a big ar-
       ray  with  the same number of dimensions	as a , and the same dimensions
       as a , except the last dimension, which	corresponds  to	 the  interval
       [ofs ...	ofs + len - 1] of the last dimension of	a .  No	copying	of el-
       ements is involved: the sub-array and the original array	share the same
       storage	space.	 In other terms, the element at	coordinates [|i1; ...;
       iN|] of the sub-array is	identical to the element at coordinates	 [|i1;
       ...; iN+ofs|] of	the original array a .

       Genarray.sub_right applies only to big arrays in	Fortran	layout.	 Raise
       Invalid_argument	if ofs and len do not designate	a valid	sub-array of a
       ,  that is, if ofs < 1 ,	or len < 0 , or	ofs + len > Genarray.nth_dim a
       (Genarray.num_dims a - 1) .

       val slice_left :	('a, 'b, Bigarray.c_layout) t -> int array -> ('a, 'b,
       Bigarray.c_layout) t

       Extract a sub-array of lower dimension from the given big array by fix-
       ing one or  several  of	the  first  (left-most)	 coordinates.	Genar-
       ray.slice_left  a [|i1; ... ; iM|] returns the 'slice' of a obtained by
       setting the first M coordinates to i1 , ..., iM .  If a	has  N	dimen-
       sions,  the  slice has dimension	N - M ,	and the	element	at coordinates
       [|j1; ...; j(N-M)|] in the slice	is identical to	the element at coordi-
       nates  [|i1;  ...;  iM; j1; ...;	j(N-M)|] in the	original array a .  No
       copying of elements is involved:	the slice and the original array share
       the same	storage	space.

       Genarray.slice_left  applies only to big	arrays in C layout.  Raise In-
       valid_argument if M >= N	, or if	[|i1; ... ; iM|] is outside the	bounds
       of a .

       val  slice_right	 : ('a,	'b, Bigarray.fortran_layout) t -> int array ->
       ('a, 'b,	Bigarray.fortran_layout) t

       Extract a sub-array of lower dimension from the given big array by fix-
       ing  one	 or  several  of  the  last  (right-most) coordinates.	Genar-
       ray.slice_right a [|i1; ... ; iM|] returns the 'slice' of a obtained by
       setting	the  last  M  coordinates to i1	, ..., iM .  If	a has N	dimen-
       sions, the slice	has dimension N	- M , and the element  at  coordinates
       [|j1; ...; j(N-M)|] in the slice	is identical to	the element at coordi-
       nates [|j1; ...;	j(N-M);	i1; ...; iM|] in the original array  a	.   No
       copying of elements is involved:	the slice and the original array share
       the same	storage	space.

       Genarray.slice_right applies only to  big  arrays  in  Fortran  layout.
       Raise  Invalid_argument	if  M >= N , or	if [|i1; ... ; iM|] is outside
       the bounds of a .

       val blit	: ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> unit

       Copy all	elements of a big array	in another big	array.	 Genarray.blit
       src  dst	copies all elements of src into	dst .  Both arrays src and dst
       must have the same number of dimensions and equal dimensions.   Copying
       a  sub-array  of	 src to	a sub-array of dst can be achieved by applying
       Genarray.blit to	sub-array or slices of src and dst .

       val fill	: ('a, 'b, 'c) t -> 'a -> unit

       Set all elements	of a big array to a given value.   Genarray.fill  a  v
       stores  the  value v in all elements of the big array a .  Setting only
       some elements of	a to v can be achieved by applying Genarray.fill to  a
       sub-array or a slice of a .

       val  map_file : Unix.file_descr -> ?pos:int64 ->	('a, 'b) Bigarray.kind
       -> 'c Bigarray.layout ->	bool ->	int array -> ('a, 'b, 'c) t

       Memory mapping of a file	as a big  array.   Genarray.map_file  fd  kind
       layout  shared  dims returns a big array	of kind	kind , layout layout ,
       and dimensions as specified in dims .  The data contained in  this  big
       array  are  the contents	of the file referred to	by the file descriptor
       fd (as opened previously	with Unix.openfile , for  example).   The  op-
       tional  pos  parameter is the byte offset in the	file of	the data being
       mapped; it defaults to 0	(map from the beginning	of the file).

       If shared is true , all modifications performed on the  array  are  re-
       flected	in  the	file.  This requires that fd be	opened with write per-
       missions.  If shared is false , modifications performed	on  the	 array
       are done	in memory only,	using copy-on-write of the modified pages; the
       underlying file is not affected.

       Genarray.map_file is much more efficient	than reading the whole file in
       a big array, modifying that big array, and writing it afterwards.

       To  adjust  automatically the dimensions	of the big array to the	actual
       size of the file, the major dimension (that is, the first dimension for
       an  array  with C layout, and the last dimension	for an array with For-
       tran layout) can	be given as -1 .   Genarray.map_file  then  determines
       the  major  dimension from the size of the file.	 The file must contain
       an integral number of sub-arrays	as determined by the non-major	dimen-
       sions, otherwise	Failure	is raised.

       If  all dimensions of the big array are given, the file size is matched
       against the size	of the big array.  If the file is larger than the  big
       array, only the initial portion of the file is mapped to	the big	array.
       If the file is smaller than the big array, the  file  is	 automatically
       grown to	the size of the	big array.  This requires write	permissions on
       fd .

       Array accesses are bounds-checked, but the bounds are determined	by the
       initial	call  to  map_file  . Therefore, you should make sure no other
       process modifies	the mapped file	while you're accessing it, or a	SIGBUS
       signal  may  be	raised.	 This  happens,	 for  instance,	if the file is
       shrunk.

       This function raises Sys_error in the case of any errors	from  the  un-
       derlying	 system	 calls.	  Invalid_argument or Failure may be raised in
       cases where argument validation fails.

2020-08-11			    source:		  Bigarray.Genarray(3)

NAME | Module | Documentation

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bigarray.Genarray&sektion=3o&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help