1Bigarray.Genarray(3)               OCamldoc               Bigarray.Genarray(3)
2
3
4

NAME

6       Bigarray.Genarray - no description
7

Module

9       Module   Bigarray.Genarray
10

Documentation

12       Module Genarray
13        : sig end
14
15
16
17
18
19
20
21       type ('a, 'b, 'c) t
22
23
24       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
27       The three type parameters to Genarray.t identify the array element kind
28       and layout, as follows:
29
30       -the  first  parameter, 'a , is the OCaml type for accessing array ele‐
31       ments ( float , int , int32 , int64 , nativeint );
32
33       -the second parameter, 'b , is the actual  kind  of  array  elements  (
34       float32_elt , float64_elt , int8_signed_elt , int8_unsigned_elt , etc);
35
36       -the  third  parameter,  'c , identifies the array layout ( c_layout or
37       fortran_layout ).
38
39       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
43
44
45       val create : ('a, 'b) Bigarray.kind -> 'c Bigarray.layout -> int  array
46       -> ('a, 'b, 'c) t
47
48
49       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
57       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
61       Big arrays returned by Genarray.create are not initialized: the initial
62       values of array elements is unspecified.
63
64
65       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
69
70
71       val num_dims : ('a, 'b, 'c) t -> int
72
73       Return the number of dimensions of the given big array.
74
75
76
77       val dims : ('a, 'b, 'c) t -> int array
78
79
80       Genarray.dims a returns all dimensions of the big array a , as an array
81       of integers of length Genarray.num_dims a .
82
83
84
85       val nth_dim : ('a, 'b, 'c) t -> int -> int
86
87
88       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
94
95
96       val kind : ('a, 'b, 'c) t -> ('a, 'b) Bigarray.kind
97
98       Return the kind of the given big array.
99
100
101
102       val layout : ('a, 'b, 'c) t -> 'c Bigarray.layout
103
104       Return the layout of the given big array.
105
106
107
108       val  change_layout  :  ('a, 'b, 'c) t -> 'd Bigarray.layout -> ('a, 'b,
109       'd) t
110
111
112       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
119
120       Since 4.04.0
121
122
123
124       val size_in_bytes : ('a, 'b, 'c) t -> int
125
126
127       size_in_bytes  a  is  the  number  of  elements in a multiplied by a 's
128       Bigarray.kind_size_in_bytes .
129
130
131       Since 4.03.0
132
133
134
135       val get : ('a, 'b, 'c) t -> int array -> 'a
136
137       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
141       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
148       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
153
154
155       val set : ('a, 'b, 'c) t -> int array -> 'a -> unit
156
157       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
162       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
166       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
171
172
173       val sub_left : ('a, 'b, Bigarray.c_layout) t -> int -> int -> ('a,  'b,
174       Bigarray.c_layout) t
175
176       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
186
187       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
192
193
194       val sub_right : ('a, 'b, Bigarray.fortran_layout) t -> int  ->  int  ->
195       ('a, 'b, Bigarray.fortran_layout) t
196
197       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
207
208       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
213
214
215       val slice_left : ('a, 'b, Bigarray.c_layout) t -> int array -> ('a, 'b,
216       Bigarray.c_layout) t
217
218       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
228
229       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
233
234
235       val  slice_right  : ('a, 'b, Bigarray.fortran_layout) t -> int array ->
236       ('a, 'b, Bigarray.fortran_layout) t
237
238       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
248
249       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
253
254
255       val blit : ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> unit
256
257       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
263
264
265       val fill : ('a, 'b, 'c) t -> 'a -> unit
266
267       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
272
273
274       val  map_file : Unix.file_descr -> ?pos:int64 -> ('a, 'b) Bigarray.kind
275       -> 'c Bigarray.layout -> bool -> int array -> ('a, 'b, 'c) t
276
277       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
285       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
291
292       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
295       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
303       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
310       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
316       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.
319
320
321
322
323
3242018-04-14                          source:               Bigarray.Genarray(3)
Impressum