1Bigarray.Genarray(3) OCaml library Bigarray.Genarray(3)
2
6 Bigarray.Genarray - no description
7
9 Module Bigarray.Genarray
10
12 Module Genarray
13 : sig end
14 type ('a, 'b, 'c) t
22 The type Genarray.t is the type of big arrays with variable numbers of
25 dimensions. Any number of dimensions between 1 and 16 is supported.
26 The three type parameters to Genarray.t identify the array element kind
28 and layout, as follows:
29 -the first parameter, 'a , is the Caml type for accessing array ele‐
31 ments ( float , int , int32 , int64 , nativeint );
32 -the second parameter, 'b , is the actual kind of array elements (
34 float32_elt , float64_elt , int8_signed_elt , int8_unsigned_elt , etc);
35 -the third parameter, 'c , identifies the array layout ( c_layout or
37 fortran_layout ).
38 For instance, (float, float32_elt, fortran_layout) Genarray.t is the
40 type of generic big arrays containing 32-bit floats in Fortran layout;
41 reads and writes in this array use the Caml type float .
42 val create : ('a, 'b) Bigarray.kind -> 'c Bigarray.layout -> int array
47 -> ('a, 'b, 'c) t
48 Genarray.create kind layout dimensions returns a new big array whose
51 element kind is determined by the parameter kind (one of float32 ,
52 float64 , int8_signed , etc) and whose layout is determined by the
53 parameter layout (one of c_layout or fortran_layout ). The dimensions
54 parameter is an array of integers that indicate the size of the big
55 array in each dimension. The length of dimensions determines the num‐
56 ber of dimensions of the bigarray.
57 For instance, Genarray.create int32 c_layout [|4;6;8|] returns a fresh
59 big array of 32-bit integers, in C layout, having three dimensions, the
60 three dimensions being 4, 6 and 8 respectively.
61 Big arrays returned by Genarray.create are not initialized: the initial
63 values of array elements is unspecified.
64 Genarray.create raises Invalid_argument if the number of dimensions is
67 not in the range 1 to 16 inclusive, or if one of the dimensions is neg‐
68 ative.
69 val num_dims : ('a, 'b, 'c) t -> int
74 Return the number of dimensions of the given big array.
76 val dims : ('a, 'b, 'c) t -> int array
81 Genarray.dims a returns all dimensions of the big array a , as an array
84 of integers of length Genarray.num_dims a .
85 val nth_dim : ('a, 'b, 'c) t -> int -> int
90 Genarray.nth_dim a n returns the n -th dimension of the big array a .
93 The first dimension corresponds to n = 0 ; the second dimension corre‐
94 sponds to n = 1 ; the last dimension, to n = Genarray.num_dims a - 1 .
95 Raise Invalid_argument if n is less than 0 or greater or equal than
96 Genarray.num_dims a .
97 val kind : ('a, 'b, 'c) t -> ('a, 'b) Bigarray.kind
102 Return the kind of the given big array.
104 val layout : ('a, 'b, 'c) t -> 'c Bigarray.layout
109 Return the layout of the given big array.
111 val get : ('a, 'b, 'c) t -> int array -> 'a
116 Read an element of a generic big array. Genarray.get a [|i1; ...; iN|]
118 returns the element of a whose coordinates are i1 in the first dimen‐
119 sion, i2 in the second dimension, ..., iN in the N -th dimension.
120 If a has C layout, the coordinates must be greater or equal than 0 and
122 strictly less than the corresponding dimensions of a . If a has For‐
123 tran layout, the coordinates must be greater or equal than 1 and less
124 or equal than the corresponding dimensions of a . Raise Invalid_argu‐
125 ment if the array a does not have exactly N dimensions, or if the coor‐
126 dinates are outside the array bounds.
127 If N > 3 , alternate syntax is provided: you can write a.{i1, i2, ...,
129 iN} instead of Genarray.get a [|i1; ...; iN|] . (The syntax a.{...}
130 with one, two or three coordinates is reserved for accessing one-, two-
131 and three-dimensional arrays as described below.)
132 val set : ('a, 'b, 'c) t -> int array -> 'a -> unit
137 Assign an element of a generic big array. Genarray.set a [|i1; ...;
139 iN|] v stores the value v in the element of a whose coordinates are i1
140 in the first dimension, i2 in the second dimension, ..., iN in the N
141 -th dimension.
142 The array a must have exactly N dimensions, and all coordinates must
144 lie inside the array bounds, as described for Genarray.get ; otherwise,
145 Invalid_argument is raised.
146 If N > 3 , alternate syntax is provided: you can write a.{i1, i2, ...,
148 iN} <- v instead of Genarray.set a [|i1; ...; iN|] v . (The syntax
149 a.{...} <- v with one, two or three coordinates is reserved for updat‐
150 ing one-, two- and three-dimensional arrays as described below.)
151 val sub_left : ('a, 'b, Bigarray.c_layout) t -> int -> int -> ('a, 'b,
156 Bigarray.c_layout) t
157 Extract a sub-array of the given big array by restricting the first
159 (left-most) dimension. Genarray.sub_left a ofs len returns a big array
160 with the same number of dimensions as a , and the same dimensions as a
161 , except the first dimension, which corresponds to the interval [ofs
162 ... ofs + len - 1] of the first dimension of a . No copying of ele‐
163 ments is involved: the sub-array and the original array share the same
164 storage space. In other terms, the element at coordinates [|i1; ...;
165 iN|] of the sub-array is identical to the element at coordinates
166 [|i1+ofs; ...; iN|] of the original array a .
167 Genarray.sub_left applies only to big arrays in C layout. Raise
170 Invalid_argument if ofs and len do not designate a valid sub-array of a
171 , that is, if ofs < 0 , or len < 0 , or ofs + len > Genarray.nth_dim a
172 0 .
173 val sub_right : ('a, 'b, Bigarray.fortran_layout) t -> int -> int ->
178 ('a, 'b, Bigarray.fortran_layout) t
179 Extract a sub-array of the given big array by restricting the last
181 (right-most) dimension. Genarray.sub_right a ofs len returns a big
182 array with the same number of dimensions as a , and the same dimensions
183 as a , except the last dimension, which corresponds to the interval
184 [ofs ... ofs + len - 1] of the last dimension of a . No copying of
185 elements is involved: the sub-array and the original array share the
186 same storage space. In other terms, the element at coordinates [|i1;
187 ...; iN|] of the sub-array is identical to the element at coordinates
188 [|i1; ...; iN+ofs|] of the original array a .
189 Genarray.sub_right applies only to big arrays in Fortran layout. Raise
192 Invalid_argument if ofs and len do not designate a valid sub-array of a
193 , that is, if ofs < 1 , or len < 0 , or ofs + len > Genarray.nth_dim a
194 (Genarray.num_dims a - 1) .
195 val slice_left : ('a, 'b, Bigarray.c_layout) t -> int array -> ('a, 'b,
200 Bigarray.c_layout) t
201 Extract a sub-array of lower dimension from the given big array by fix‐
203 ing one or several of the first (left-most) coordinates. Genar‐
204 ray.slice_left a [|i1; ... ; iM|] returns the ``slice'' of a obtained
205 by setting the first M coordinates to i1 , ..., iM . If a has N dimen‐
206 sions, the slice has dimension N - M , and the element at coordinates
207 [|j1; ...; j(N-M)|] in the slice is identical to the element at coordi‐
208 nates [|i1; ...; iM; j1; ...; j(N-M)|] in the original array a . No
209 copying of elements is involved: the slice and the original array share
210 the same storage space.
211 Genarray.slice_left applies only to big arrays in C layout. Raise
214 Invalid_argument if M >= N , or if [|i1; ... ; iM|] is outside the
215 bounds of a .
216 val slice_right : ('a, 'b, Bigarray.fortran_layout) t -> int array ->
221 ('a, 'b, Bigarray.fortran_layout) t
222 Extract a sub-array of lower dimension from the given big array by fix‐
224 ing one or several of the last (right-most) coordinates. Genar‐
225 ray.slice_right a [|i1; ... ; iM|] returns the ``slice'' of a obtained
226 by setting the last M coordinates to i1 , ..., iM . If a has N dimen‐
227 sions, the slice has dimension N - M , and the element at coordinates
228 [|j1; ...; j(N-M)|] in the slice is identical to the element at coordi‐
229 nates [|j1; ...; j(N-M); i1; ...; iM|] in the original array a . No
230 copying of elements is involved: the slice and the original array share
231 the same storage space.
232 Genarray.slice_right applies only to big arrays in Fortran layout.
235 Raise Invalid_argument if M >= N , or if [|i1; ... ; iM|] is outside
236 the bounds of a .
237 val blit : ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> unit
242 Copy all elements of a big array in another big array. Genarray.blit
244 src dst copies all elements of src into dst . Both arrays src and dst
245 must have the same number of dimensions and equal dimensions. Copying
246 a sub-array of src to a sub-array of dst can be achieved by applying
247 Genarray.blit to sub-array or slices of src and dst .
248 val fill : ('a, 'b, 'c) t -> 'a -> unit
253 Set all elements of a big array to a given value. Genarray.fill a v
255 stores the value v in all elements of the big array a . Setting only
256 some elements of a to v can be achieved by applying Genarray.fill to a
257 sub-array or a slice of a .
258 val map_file : Unix.file_descr -> ?pos:int64 -> ('a, 'b) Bigarray.kind
263 -> 'c Bigarray.layout -> bool -> int array -> ('a, 'b, 'c) t
264 Memory mapping of a file as a big array. Genarray.map_file fd kind
266 layout shared dims returns a big array of kind kind , layout layout ,
267 and dimensions as specified in dims . The data contained in this big
268 array are the contents of the file referred to by the file descriptor
269 fd (as opened previously with Unix.openfile , for example). The
270 optional pos parameter is the byte offset in the file of the data being
271 mapped; it defaults to 0 (map from the beginning of the file).
272 If shared is true , all modifications performed on the array are
274 reflected in the file. This requires that fd be opened with write per‐
275 missions. If shared is false , modifications performed on the array
276 are done in memory only, using copy-on-write of the modified pages; the
277 underlying file is not affected.
278 Genarray.map_file is much more efficient than reading the whole file in
281 a big array, modifying that big array, and writing it afterwards.
282 To adjust automatically the dimensions of the big array to the actual
284 size of the file, the major dimension (that is, the first dimension for
285 an array with C layout, and the last dimension for an array with For‐
286 tran layout) can be given as -1 . Genarray.map_file then determines
287 the major dimension from the size of the file. The file must contain
288 an integral number of sub-arrays as determined by the non-major dimen‐
289 sions, otherwise Failure is raised.
290 If all dimensions of the big array are given, the file size is matched
292 against the size of the big array. If the file is larger than the big
293 array, only the initial portion of the file is mapped to the big array.
294 If the file is smaller than the big array, the file is automatically
295 grown to the size of the big array. This requires write permissions on
296 fd .
297OCamldoc 2010-01-29 Bigarray.Genarray(3)