1Bigarray.Genarray(3) OCamldoc 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 0 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 OCaml 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 OCaml type float .
42 val create : ('a, 'b) Bigarray.kind -> 'c Bigarray.layout -> int array
46 -> ('a, 'b, 'c) t
47 Genarray.create kind layout dimensions returns a new big array whose
50 element kind is determined by the parameter kind (one of float32 ,
51 float64 , int8_signed , etc) and whose layout is determined by the
52 parameter layout (one of c_layout or fortran_layout ). The dimensions
53 parameter is an array of integers that indicate the size of the big
54 array in each dimension. The length of dimensions determines the num‐
55 ber of dimensions of the bigarray.
56 For instance, Genarray.create int32 c_layout [|4;6;8|] returns a fresh
58 big array of 32-bit integers, in C layout, having three dimensions, the
59 three dimensions being 4, 6 and 8 respectively.
60 Big arrays returned by Genarray.create are not initialized: the initial
62 values of array elements is unspecified.
63 Genarray.create raises Invalid_argument if the number of dimensions is
66 not in the range 0 to 16 inclusive, or if one of the dimensions is neg‐
67 ative.
68 val num_dims : ('a, 'b, 'c) t -> int
72 Return the number of dimensions of the given big array.
74 val dims : ('a, 'b, 'c) t -> int array
78 Genarray.dims a returns all dimensions of the big array a , as an array
81 of integers of length Genarray.num_dims a .
82 val nth_dim : ('a, 'b, 'c) t -> int -> int
86 Genarray.nth_dim a n returns the n -th dimension of the big array a .
89 The first dimension corresponds to n = 0 ; the second dimension corre‐
90 sponds to n = 1 ; the last dimension, to n = Genarray.num_dims a - 1 .
91 Raise Invalid_argument if n is less than 0 or greater or equal than
92 Genarray.num_dims a .
93 val kind : ('a, 'b, 'c) t -> ('a, 'b) Bigarray.kind
97 Return the kind of the given big array.
99 val layout : ('a, 'b, 'c) t -> 'c Bigarray.layout
103 Return the layout of the given big array.
105 val change_layout : ('a, 'b, 'c) t -> 'd Bigarray.layout -> ('a, 'b,
109 'd) t
110 Genarray.change_layout a layout returns a bigarray with the specified
113 layout , sharing the data with a (and hence having the same dimensions
114 as a ). No copying of elements is involved: the new array and the orig‐
115 inal array share the same storage space. The dimensions are reversed,
116 such that get v [| a; b |] in C layout becomes get v [| b+1; a+1 |] in
117 Fortran layout.
118 Since 4.04.0
121 val size_in_bytes : ('a, 'b, 'c) t -> int
125 size_in_bytes a is the number of elements in a multiplied by a 's
128 Bigarray.kind_size_in_bytes .
129 Since 4.03.0
132 val get : ('a, 'b, 'c) t -> int array -> 'a
136 Read an element of a generic big array. Genarray.get a [|i1; ...; iN|]
138 returns the element of a whose coordinates are i1 in the first dimen‐
139 sion, i2 in the second dimension, ..., iN in the N -th dimension.
140 If a has C layout, the coordinates must be greater or equal than 0 and
142 strictly less than the corresponding dimensions of a . If a has For‐
143 tran layout, the coordinates must be greater or equal than 1 and less
144 or equal than the corresponding dimensions of a . Raise Invalid_argu‐
145 ment if the array a does not have exactly N dimensions, or if the coor‐
146 dinates are outside the array bounds.
147 If N > 3 , alternate syntax is provided: you can write a.{i1, i2, ...,
149 iN} instead of Genarray.get a [|i1; ...; iN|] . (The syntax a.{...}
150 with one, two or three coordinates is reserved for accessing one-, two-
151 and three-dimensional arrays as described below.)
152 val set : ('a, 'b, 'c) t -> int array -> 'a -> unit
156 Assign an element of a generic big array. Genarray.set a [|i1; ...;
158 iN|] v stores the value v in the element of a whose coordinates are i1
159 in the first dimension, i2 in the second dimension, ..., iN in the N
160 -th dimension.
161 The array a must have exactly N dimensions, and all coordinates must
163 lie inside the array bounds, as described for Genarray.get ; otherwise,
164 Invalid_argument is raised.
165 If N > 3 , alternate syntax is provided: you can write a.{i1, i2, ...,
167 iN} <- v instead of Genarray.set a [|i1; ...; iN|] v . (The syntax
168 a.{...} <- v with one, two or three coordinates is reserved for updat‐
169 ing one-, two- and three-dimensional arrays as described below.)
170 val sub_left : ('a, 'b, Bigarray.c_layout) t -> int -> int -> ('a, 'b,
174 Bigarray.c_layout) t
175 Extract a sub-array of the given big array by restricting the first
177 (left-most) dimension. Genarray.sub_left a ofs len returns a big array
178 with the same number of dimensions as a , and the same dimensions as a
179 , except the first dimension, which corresponds to the interval [ofs
180 ... ofs + len - 1] of the first dimension of a . No copying of ele‐
181 ments is involved: the sub-array and the original array share the same
182 storage space. In other terms, the element at coordinates [|i1; ...;
183 iN|] of the sub-array is identical to the element at coordinates
184 [|i1+ofs; ...; iN|] of the original array a .
185 Genarray.sub_left applies only to big arrays in C layout. Raise
188 Invalid_argument if ofs and len do not designate a valid sub-array of a
189 , that is, if ofs < 0 , or len < 0 , or ofs + len > Genarray.nth_dim a
190 0 .
191 val sub_right : ('a, 'b, Bigarray.fortran_layout) t -> int -> int ->
195 ('a, 'b, Bigarray.fortran_layout) t
196 Extract a sub-array of the given big array by restricting the last
198 (right-most) dimension. Genarray.sub_right a ofs len returns a big
199 array with the same number of dimensions as a , and the same dimensions
200 as a , except the last dimension, which corresponds to the interval
201 [ofs ... ofs + len - 1] of the last dimension of a . No copying of
202 elements is involved: the sub-array and the original array share the
203 same storage space. In other terms, the element at coordinates [|i1;
204 ...; iN|] of the sub-array is identical to the element at coordinates
205 [|i1; ...; iN+ofs|] of the original array a .
206 Genarray.sub_right applies only to big arrays in Fortran layout. Raise
209 Invalid_argument if ofs and len do not designate a valid sub-array of a
210 , that is, if ofs < 1 , or len < 0 , or ofs + len > Genarray.nth_dim a
211 (Genarray.num_dims a - 1) .
212 val slice_left : ('a, 'b, Bigarray.c_layout) t -> int array -> ('a, 'b,
216 Bigarray.c_layout) t
217 Extract a sub-array of lower dimension from the given big array by fix‐
219 ing one or several of the first (left-most) coordinates. Genar‐
220 ray.slice_left a [|i1; ... ; iM|] returns the 'slice' of a obtained by
221 setting the first M coordinates to i1 , ..., iM . If a has N dimen‐
222 sions, the slice has dimension N - M , and the element at coordinates
223 [|j1; ...; j(N-M)|] in the slice is identical to the element at coordi‐
224 nates [|i1; ...; iM; j1; ...; j(N-M)|] in the original array a . No
225 copying of elements is involved: the slice and the original array share
226 the same storage space.
227 Genarray.slice_left applies only to big arrays in C layout. Raise
230 Invalid_argument if M >= N , or if [|i1; ... ; iM|] is outside the
231 bounds of a .
232 val slice_right : ('a, 'b, Bigarray.fortran_layout) t -> int array ->
236 ('a, 'b, Bigarray.fortran_layout) t
237 Extract a sub-array of lower dimension from the given big array by fix‐
239 ing one or several of the last (right-most) coordinates. Genar‐
240 ray.slice_right a [|i1; ... ; iM|] returns the 'slice' of a obtained by
241 setting the last M coordinates to i1 , ..., iM . If a has N dimen‐
242 sions, the slice has dimension N - M , and the element at coordinates
243 [|j1; ...; j(N-M)|] in the slice is identical to the element at coordi‐
244 nates [|j1; ...; j(N-M); i1; ...; iM|] in the original array a . No
245 copying of elements is involved: the slice and the original array share
246 the same storage space.
247 Genarray.slice_right applies only to big arrays in Fortran layout.
250 Raise Invalid_argument if M >= N , or if [|i1; ... ; iM|] is outside
251 the bounds of a .
252 val blit : ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> unit
256 Copy all elements of a big array in another big array. Genarray.blit
258 src dst copies all elements of src into dst . Both arrays src and dst
259 must have the same number of dimensions and equal dimensions. Copying
260 a sub-array of src to a sub-array of dst can be achieved by applying
261 Genarray.blit to sub-array or slices of src and dst .
262 val fill : ('a, 'b, 'c) t -> 'a -> unit
266 Set all elements of a big array to a given value. Genarray.fill a v
268 stores the value v in all elements of the big array a . Setting only
269 some elements of a to v can be achieved by applying Genarray.fill to a
270 sub-array or a slice of a .
271 val map_file : Unix.file_descr -> ?pos:int64 -> ('a, 'b) Bigarray.kind
275 -> 'c Bigarray.layout -> bool -> int array -> ('a, 'b, 'c) t
276 Memory mapping of a file as a big array. Genarray.map_file fd kind
278 layout shared dims returns a big array of kind kind , layout layout ,
279 and dimensions as specified in dims . The data contained in this big
280 array are the contents of the file referred to by the file descriptor
281 fd (as opened previously with Unix.openfile , for example). The
282 optional pos parameter is the byte offset in the file of the data being
283 mapped; it defaults to 0 (map from the beginning of the file).
284 If shared is true , all modifications performed on the array are
286 reflected in the file. This requires that fd be opened with write per‐
287 missions. If shared is false , modifications performed on the array
288 are done in memory only, using copy-on-write of the modified pages; the
289 underlying file is not affected.
290 Genarray.map_file is much more efficient than reading the whole file in
293 a big array, modifying that big array, and writing it afterwards.
294 To adjust automatically the dimensions of the big array to the actual
296 size of the file, the major dimension (that is, the first dimension for
297 an array with C layout, and the last dimension for an array with For‐
298 tran layout) can be given as -1 . Genarray.map_file then determines
299 the major dimension from the size of the file. The file must contain
300 an integral number of sub-arrays as determined by the non-major dimen‐
301 sions, otherwise Failure is raised.
302 If all dimensions of the big array are given, the file size is matched
304 against the size of the big array. If the file is larger than the big
305 array, only the initial portion of the file is mapped to the big array.
306 If the file is smaller than the big array, the file is automatically
307 grown to the size of the big array. This requires write permissions on
308 fd .
309 Array accesses are bounds-checked, but the bounds are determined by the
311 initial call to map_file . Therefore, you should make sure no other
312 process modifies the mapped file while you're accessing it, or a SIGBUS
313 signal may be raised. This happens, for instance, if the file is
314 shrunk.
315 This function raises Sys_error in the case of any errors from the
317 underlying system calls. Invalid_argument or Failure may be raised in
318 cases where argument validation fails.
3192018-04-14 source: Bigarray.Genarray(3)