anil.recoil.org
My working unpac repository
1(**************************************************************************)
2(* *)
3(* OCaml *)
4(* *)
5(* Manuel Serrano and Xavier Leroy, INRIA Rocquencourt *)
6(* *)
7(* Copyright 2000 Institut National de Recherche en Informatique et *)
8(* en Automatique. *)
9(* *)
10(* All rights reserved. This file is distributed under the terms of *)
11(* the GNU Lesser General Public License version 2.1, with the *)
12(* special exception on linking described in the file LICENSE. *)
13(* *)
14(**************************************************************************)
15
16(** Large, multi-dimensional, numerical arrays.
17
18 This module implements multi-dimensional arrays of integers and
19 floating-point numbers, thereafter referred to as 'Bigarrays',
20 to distinguish them from the standard OCaml arrays described in
21 {!module:Array}.
22
23 The implementation allows efficient sharing of large numerical
24 arrays between OCaml code and C or Fortran numerical libraries.
25
26 The main differences between 'Bigarrays' and standard OCaml
27 arrays are as follows:
28 - Bigarrays are not limited in size, unlike OCaml arrays.
29 (Normal float arrays are limited to 2,097,151 elements on a 32-bit
30 platform, and normal arrays of other types to 4,194,303 elements.)
31 - Bigarrays are multi-dimensional. Any number of dimensions
32 between 0 and 16 is supported. In contrast, OCaml arrays
33 are mono-dimensional and require encoding multi-dimensional
34 arrays as arrays of arrays.
35 - Bigarrays can only contain integers and floating-point numbers,
36 while OCaml arrays can contain arbitrary OCaml data types.
37 - Bigarrays provide more space-efficient storage of
38 integer and floating-point elements than normal OCaml arrays, in
39 particular because they support 'small' types such as
40 single-precision floats and 8 and 16-bit integers, in addition to
41 the standard OCaml types of double-precision floats and 32 and
42 64-bit integers.
43 - The memory layout of Bigarrays is entirely compatible with that
44 of arrays in C and Fortran, allowing large arrays to be passed
45 back and forth between OCaml code and C / Fortran code with no
46 data copying at all.
47 - Bigarrays support interesting high-level operations that normal
48 arrays do not provide efficiently, such as extracting sub-arrays
49 and 'slicing' a multi-dimensional array along certain dimensions,
50 all without any copying.
51
52 Users of this module are encouraged to do [open Bigarray] in their
53 source, then refer to array types and operations via short dot
54 notation, e.g. [Array1.t] or [Array2.sub].
55
56 Bigarrays support all the OCaml ad-hoc polymorphic operations:
57 - comparisons ([=], [<>], [<=], etc, as well as {!Stdlib.compare});
58 - hashing (module [Hash]);
59 - and structured input-output (the functions from the
60 {!Marshal} module, as well as {!Stdlib.output_value}
61 and {!Stdlib.input_value}).
62*)
63
64(** {1:elementkinds Element kinds} *)
65
66(** Bigarrays can contain elements of the following kinds:
67- IEEE half precision (16 bits) floating-point numbers
68 ({!Bigarray.float16_elt}),
69- IEEE single precision (32 bits) floating-point numbers
70 ({!Bigarray.float32_elt}),
71- IEEE double precision (64 bits) floating-point numbers
72 ({!Bigarray.float64_elt}),
73- IEEE single precision (2 * 32 bits) floating-point complex numbers
74 ({!Bigarray.complex32_elt}),
75- IEEE double precision (2 * 64 bits) floating-point complex numbers
76 ({!Bigarray.complex64_elt}),
77- 8-bit integers (signed or unsigned)
78 ({!Bigarray.int8_signed_elt} or {!Bigarray.int8_unsigned_elt}),
79- 16-bit integers (signed or unsigned)
80 ({!Bigarray.int16_signed_elt} or {!Bigarray.int16_unsigned_elt}),
81- OCaml integers (signed, 31 bits on 32-bit architectures,
82 63 bits on 64-bit architectures) ({!Bigarray.int_elt}),
83- 32-bit signed integers ({!Bigarray.int32_elt}),
84- 64-bit signed integers ({!Bigarray.int64_elt}),
85- platform-native signed integers (32 bits on 32-bit architectures,
86 64 bits on 64-bit architectures) ({!Bigarray.nativeint_elt}).
87
88 Each element kind is represented at the type level by one of the
89 [*_elt] types defined below (defined with a single constructor instead
90 of abstract types for technical injectivity reasons).
91
92 @since 4.07 Moved from otherlibs to stdlib.
93 @since 5.2 Added float16_elt element kind.
94*)
95
96type float16_elt = Float16_elt
97type float32_elt = Float32_elt
98type float64_elt = Float64_elt
99type int8_signed_elt = Int8_signed_elt
100type int8_unsigned_elt = Int8_unsigned_elt
101type int16_signed_elt = Int16_signed_elt
102type int16_unsigned_elt = Int16_unsigned_elt
103type int32_elt = Int32_elt
104type int64_elt = Int64_elt
105type int_elt = Int_elt
106type nativeint_elt = Nativeint_elt
107type complex32_elt = Complex32_elt
108type complex64_elt = Complex64_elt
109
110type ('a, 'b) kind =
111 | Float32 : (float, float32_elt) kind
112 | Float64 : (float, float64_elt) kind
113 | Int8_signed : (int, int8_signed_elt) kind
114 | Int8_unsigned : (int, int8_unsigned_elt) kind
115 | Int16_signed : (int, int16_signed_elt) kind
116 | Int16_unsigned : (int, int16_unsigned_elt) kind
117 | Int32 : (int32, int32_elt) kind
118 | Int64 : (int64, int64_elt) kind
119 | Int : (int, int_elt) kind
120 | Nativeint : (nativeint, nativeint_elt) kind
121 | Complex32 : (Complex.t, complex32_elt) kind
122 | Complex64 : (Complex.t, complex64_elt) kind
123 | Char : (char, int8_unsigned_elt) kind
124 | Float16 : (float, float16_elt) kind (**)
125(** To each element kind is associated an OCaml type, which is
126 the type of OCaml values that can be stored in the Bigarray
127 or read back from it. This type is not necessarily the same
128 as the type of the array elements proper: for instance,
129 a Bigarray whose elements are of kind [float32_elt] contains
130 32-bit single precision floats, but reading or writing one of
131 its elements from OCaml uses the OCaml type [float], which is
132 64-bit double precision floats.
133
134 The GADT type [('a, 'b) kind] captures this association
135 of an OCaml type ['a] for values read or written in the Bigarray,
136 and of an element kind ['b] which represents the actual contents
137 of the Bigarray. Its constructors list all possible associations
138 of OCaml types with element kinds, and are re-exported below for
139 backward-compatibility reasons.
140
141 Using a generalized algebraic datatype (GADT) here allows writing
142 well-typed polymorphic functions whose return type depend on the
143 argument type, such as:
144
145{[
146 let zero : type a b. (a, b) kind -> a = function
147 | Float32 -> 0.0 | Complex32 -> Complex.zero
148 | Float64 -> 0.0 | Complex64 -> Complex.zero
149 | Float16 -> 0.0
150 | Int8_signed -> 0 | Int8_unsigned -> 0
151 | Int16_signed -> 0 | Int16_unsigned -> 0
152 | Int32 -> 0l | Int64 -> 0L
153 | Int -> 0 | Nativeint -> 0n
154 | Char -> '\000'
155]}
156
157 @since 5.2 Constructor Float16 for the GADT.
158*)
159
160val float16 : (float, float16_elt) kind
161(** See {!Bigarray.char}.
162 @since 5.2 *)
163
164val float32 : (float, float32_elt) kind
165(** See {!Bigarray.char}. *)
166
167val float64 : (float, float64_elt) kind
168(** See {!Bigarray.char}. *)
169
170val complex32 : (Complex.t, complex32_elt) kind
171(** See {!Bigarray.char}. *)
172
173val complex64 : (Complex.t, complex64_elt) kind
174(** See {!Bigarray.char}. *)
175
176val int8_signed : (int, int8_signed_elt) kind
177(** See {!Bigarray.char}. *)
178
179val int8_unsigned : (int, int8_unsigned_elt) kind
180(** See {!Bigarray.char}. *)
181
182val int16_signed : (int, int16_signed_elt) kind
183(** See {!Bigarray.char}. *)
184
185val int16_unsigned : (int, int16_unsigned_elt) kind
186(** See {!Bigarray.char}. *)
187
188val int : (int, int_elt) kind
189(** See {!Bigarray.char} and {!section:elementkinds}.
190
191 Beware that this is a bigarray containing OCaml integers
192 (signed, 31 bits on 32-bit architectures, 63 bits on 64-bit architectures),
193 which does not match the [C] int type.
194 *)
195
196val int32 : (int32, int32_elt) kind
197(** See {!Bigarray.char}. *)
198
199val int64 : (int64, int64_elt) kind
200(** See {!Bigarray.char}. *)
201
202val nativeint : (nativeint, nativeint_elt) kind
203(** See {!Bigarray.char}. *)
204
205val char : (char, int8_unsigned_elt) kind
206(** As shown by the types of the values above,
207 Bigarrays of kind [float16_elt], [float32_elt] and [float64_elt] are
208 accessed using the OCaml type [float]. Bigarrays of complex kinds
209 [complex32_elt], [complex64_elt] are accessed with the OCaml type
210 {!Complex.t}. Bigarrays of
211 integer kinds are accessed using the smallest OCaml integer
212 type large enough to represent the array elements:
213 [int] for 8- and 16-bit integer Bigarrays, as well as OCaml-integer
214 Bigarrays; [int32] for 32-bit integer Bigarrays; [int64]
215 for 64-bit integer Bigarrays; and [nativeint] for
216 platform-native integer Bigarrays. Finally, Bigarrays of
217 kind [int8_unsigned_elt] can also be accessed as arrays of
218 characters instead of arrays of small integers, by using
219 the kind value [char] instead of [int8_unsigned]. *)
220
221val kind_size_in_bytes : ('a, 'b) kind -> int
222(** [kind_size_in_bytes k] is the number of bytes used to store
223 an element of type [k].
224
225 @since 4.03 *)
226
227(** {1 Array layouts} *)
228
229type c_layout = C_layout_typ (**)
230(** See {!type:Bigarray.fortran_layout}.*)
231
232type fortran_layout = Fortran_layout_typ (**)
233(** To facilitate interoperability with existing C and Fortran code,
234 this library supports two different memory layouts for Bigarrays,
235 one compatible with the C conventions,
236 the other compatible with the Fortran conventions.
237
238 In the C-style layout, array indices start at 0, and
239 multi-dimensional arrays are laid out in row-major format.
240 That is, for a two-dimensional array, all elements of
241 row 0 are contiguous in memory, followed by all elements of
242 row 1, etc. In other terms, the array elements at [(x,y)]
243 and [(x, y+1)] are adjacent in memory.
244
245 In the Fortran-style layout, array indices start at 1, and
246 multi-dimensional arrays are laid out in column-major format.
247 That is, for a two-dimensional array, all elements of
248 column 0 are contiguous in memory, followed by all elements of
249 column 1, etc. In other terms, the array elements at [(x,y)]
250 and [(x+1, y)] are adjacent in memory.
251
252 Each layout style is identified at the type level by the
253 phantom types {!type:Bigarray.c_layout} and {!type:Bigarray.fortran_layout}
254 respectively. *)
255
256(** {2 Supported layouts}
257
258 The GADT type ['a layout] represents one of the two supported
259 memory layouts: C-style or Fortran-style. Its constructors are
260 re-exported as values below for backward-compatibility reasons.
261*)
262
263type 'a layout =
264 C_layout: c_layout layout
265 | Fortran_layout: fortran_layout layout
266
267val c_layout : c_layout layout
268val fortran_layout : fortran_layout layout
269
270
271(** {1 Generic arrays (of arbitrarily many dimensions)} *)
272
273module Genarray :
274 sig
275 type (!'a, !'b, !'c) t
276 (** The type [Genarray.t] is the type of Bigarrays with variable
277 numbers of dimensions. Any number of dimensions between 0 and 16
278 is supported.
279
280 The three type parameters to [Genarray.t] identify the array element
281 kind and layout, as follows:
282 - the first parameter, ['a], is the OCaml type for accessing array
283 elements ([float], [int], [int32], [int64], [nativeint]);
284 - the second parameter, ['b], is the actual kind of array elements
285 ([float32_elt], [float64_elt], [int8_signed_elt], [int8_unsigned_elt],
286 etc);
287 - the third parameter, ['c], identifies the array layout
288 ([c_layout] or [fortran_layout]).
289
290 For instance, [(float, float32_elt, fortran_layout) Genarray.t]
291 is the type of generic Bigarrays containing 32-bit floats
292 in Fortran layout; reads and writes in this array use the
293 OCaml type [float]. *)
294
295 external create: ('a, 'b) kind -> 'c layout -> int array -> ('a, 'b, 'c) t
296 = "caml_ba_create"
297 (** [Genarray.create kind layout dimensions] returns a new Bigarray
298 whose element kind is determined by the parameter [kind] (one of
299 [float32], [float64], [int8_signed], etc) and whose layout is
300 determined by the parameter [layout] (one of [c_layout] or
301 [fortran_layout]). The [dimensions] parameter is an array of
302 integers that indicate the size of the Bigarray in each dimension.
303 The length of [dimensions] determines the number of dimensions
304 of the Bigarray.
305
306 For instance, [Genarray.create int32 c_layout [|4;6;8|]]
307 returns a fresh Bigarray of 32-bit integers, in C layout,
308 having three dimensions, the three dimensions being 4, 6 and 8
309 respectively.
310
311 Bigarrays returned by [Genarray.create] are not initialized:
312 the initial values of array elements is unspecified.
313
314 [Genarray.create] raises [Invalid_argument] if the number of dimensions
315 is not in the range 0 to 16 inclusive, or if one of the dimensions
316 is negative. *)
317
318 val init: ('a, 'b) kind -> 'c layout -> int array -> (int array -> 'a) ->
319 ('a, 'b, 'c) t
320 (** [Genarray.init kind layout dimensions f] returns a new Bigarray [b]
321 whose element kind is determined by the parameter [kind] (one of
322 [float32], [float64], [int8_signed], etc) and whose layout is
323 determined by the parameter [layout] (one of [c_layout] or
324 [fortran_layout]). The [dimensions] parameter is an array of
325 integers that indicate the size of the Bigarray in each dimension.
326 The length of [dimensions] determines the number of dimensions
327 of the Bigarray.
328
329 Each element [Genarray.get b i] is initialized to the result of [f i].
330 In other words, [Genarray.init kind layout dimensions f] tabulates
331 the results of [f] applied to the indices of a new Bigarray whose
332 layout is described by [kind], [layout] and [dimensions]. The index
333 array [i] may be shared and mutated between calls to f.
334
335 For instance, [Genarray.init int c_layout [|2; 1; 3|]
336 (Array.fold_left (+) 0)] returns a fresh Bigarray of integers, in C
337 layout, having three dimensions (2, 1, 3, respectively), with the
338 element values 0, 1, 2, 1, 2, 3.
339
340 [Genarray.init] raises [Invalid_argument] if the number of dimensions
341 is not in the range 0 to 16 inclusive, or if one of the dimensions
342 is negative.
343
344 @since 4.12 *)
345
346 external num_dims: ('a, 'b, 'c) t -> int = "caml_ba_num_dims"
347 (** Return the number of dimensions of the given Bigarray. *)
348
349 val dims : ('a, 'b, 'c) t -> int array
350 (** [Genarray.dims a] returns all dimensions of the Bigarray [a],
351 as an array of integers of length [Genarray.num_dims a]. *)
352
353 external nth_dim: ('a, 'b, 'c) t -> int -> int = "caml_ba_dim"
354 (** [Genarray.nth_dim a n] returns the [n]-th dimension of the
355 Bigarray [a]. The first dimension corresponds to [n = 0];
356 the second dimension corresponds to [n = 1]; the last dimension,
357 to [n = Genarray.num_dims a - 1].
358 @raise Invalid_argument if [n] is less than 0 or greater or equal than
359 [Genarray.num_dims a]. *)
360
361 external kind: ('a, 'b, 'c) t -> ('a, 'b) kind = "caml_ba_kind"
362 (** Return the kind of the given Bigarray. *)
363
364 external layout: ('a, 'b, 'c) t -> 'c layout = "caml_ba_layout"
365 (** Return the layout of the given Bigarray. *)
366
367 external change_layout: ('a, 'b, 'c) t -> 'd layout -> ('a, 'b, 'd) t
368 = "caml_ba_change_layout"
369 (** [Genarray.change_layout a layout] returns a Bigarray with the
370 specified [layout], sharing the data with [a] (and hence having
371 the same dimensions as [a]). No copying of elements is involved: the
372 new array and the original array share the same storage space.
373 The dimensions are reversed, such that [get v [| a; b |]] in
374 C layout becomes [get v [| b+1; a+1 |]] in Fortran layout.
375
376 @since 4.04
377 *)
378
379 val size_in_bytes : ('a, 'b, 'c) t -> int
380 (** [size_in_bytes a] is the number of elements in [a] multiplied
381 by [a]'s {!kind_size_in_bytes}.
382
383 @since 4.03 *)
384
385 external get: ('a, 'b, 'c) t -> int array -> 'a = "caml_ba_get_generic"
386 (** Read an element of a generic Bigarray.
387 [Genarray.get a [|i1; ...; iN|]] returns the element of [a]
388 whose coordinates are [i1] in the first dimension, [i2] in
389 the second dimension, ..., [iN] in the [N]-th dimension.
390
391 If [a] has C layout, the coordinates must be greater or equal than 0
392 and strictly less than the corresponding dimensions of [a].
393 If [a] has Fortran layout, the coordinates must be greater or equal
394 than 1 and less or equal than the corresponding dimensions of [a].
395
396 If [N > 3], alternate syntax is provided: you can write
397 [a.{i1, i2, ..., iN}] instead of [Genarray.get a [|i1; ...; iN|]].
398 (The syntax [a.{...}] with one, two or three coordinates is
399 reserved for accessing one-, two- and three-dimensional arrays
400 as described below.)
401
402 @raise Invalid_argument if the array [a] does not have exactly [N]
403 dimensions, or if the coordinates are outside the array bounds.
404 *)
405
406 external set: ('a, 'b, 'c) t -> int array -> 'a -> unit
407 = "caml_ba_set_generic"
408 (** Assign an element of a generic Bigarray.
409 [Genarray.set a [|i1; ...; iN|] v] stores the value [v] in the
410 element of [a] whose coordinates are [i1] in the first dimension,
411 [i2] in the second dimension, ..., [iN] in the [N]-th dimension.
412
413 The array [a] must have exactly [N] dimensions, and all coordinates
414 must lie inside the array bounds, as described for [Genarray.get];
415 otherwise, [Invalid_argument] is raised.
416
417 If [N > 3], alternate syntax is provided: you can write
418 [a.{i1, i2, ..., iN} <- v] instead of
419 [Genarray.set a [|i1; ...; iN|] v].
420 (The syntax [a.{...} <- v] with one, two or three coordinates is
421 reserved for updating one-, two- and three-dimensional arrays
422 as described below.) *)
423
424 external sub_left: ('a, 'b, c_layout) t -> int -> int -> ('a, 'b, c_layout) t
425 = "caml_ba_sub"
426 (** Extract a sub-array of the given Bigarray by restricting the
427 first (left-most) dimension. [Genarray.sub_left a ofs len]
428 returns a Bigarray with the same number of dimensions as [a],
429 and the same dimensions as [a], except the first dimension,
430 which corresponds to the interval [[ofs ... ofs + len - 1]]
431 of the first dimension of [a]. No copying of elements is
432 involved: the sub-array and the original array share the same
433 storage space. In other terms, the element at coordinates
434 [[|i1; ...; iN|]] of the sub-array is identical to the
435 element at coordinates [[|i1+ofs; ...; iN|]] of the original
436 array [a].
437
438 [Genarray.sub_left] applies only to Bigarrays in C layout.
439 @raise Invalid_argument if [ofs] and [len] do not designate
440 a valid sub-array of [a], that is, if [ofs < 0], or [len < 0],
441 or [ofs + len > Genarray.nth_dim a 0]. *)
442
443 external sub_right:
444 ('a, 'b, fortran_layout) t -> int -> int -> ('a, 'b, fortran_layout) t
445 = "caml_ba_sub"
446 (** Extract a sub-array of the given Bigarray by restricting the
447 last (right-most) dimension. [Genarray.sub_right a ofs len]
448 returns a Bigarray with the same number of dimensions as [a],
449 and the same dimensions as [a], except the last dimension,
450 which corresponds to the interval [[ofs ... ofs + len - 1]]
451 of the last dimension of [a]. No copying of elements is
452 involved: the sub-array and the original array share the same
453 storage space. In other terms, the element at coordinates
454 [[|i1; ...; iN|]] of the sub-array is identical to the
455 element at coordinates [[|i1; ...; iN+ofs|]] of the original
456 array [a].
457
458 [Genarray.sub_right] applies only to Bigarrays in Fortran layout.
459 @raise Invalid_argument if [ofs] and [len] do not designate
460 a valid sub-array of [a], that is, if [ofs < 1], or [len < 0],
461 or [ofs + len > Genarray.nth_dim a (Genarray.num_dims a - 1)]. *)
462
463 external slice_left:
464 ('a, 'b, c_layout) t -> int array -> ('a, 'b, c_layout) t
465 = "caml_ba_slice"
466 (** Extract a sub-array of lower dimension from the given Bigarray
467 by fixing one or several of the first (left-most) coordinates.
468 [Genarray.slice_left a [|i1; ... ; iM|]] returns the 'slice'
469 of [a] obtained by setting the first [M] coordinates to
470 [i1], ..., [iM]. If [a] has [N] dimensions, the slice has
471 dimension [N - M], and the element at coordinates
472 [[|j1; ...; j(N-M)|]] in the slice is identical to the element
473 at coordinates [[|i1; ...; iM; j1; ...; j(N-M)|]] in the original
474 array [a]. No copying of elements is involved: the slice and
475 the original array share the same storage space.
476
477 [Genarray.slice_left] applies only to Bigarrays in C layout.
478 @raise Invalid_argument if [M >= N], or if [[|i1; ... ; iM|]]
479 is outside the bounds of [a]. *)
480
481 external slice_right:
482 ('a, 'b, fortran_layout) t -> int array -> ('a, 'b, fortran_layout) t
483 = "caml_ba_slice"
484 (** Extract a sub-array of lower dimension from the given Bigarray
485 by fixing one or several of the last (right-most) coordinates.
486 [Genarray.slice_right a [|i1; ... ; iM|]] returns the 'slice'
487 of [a] obtained by setting the last [M] coordinates to
488 [i1], ..., [iM]. If [a] has [N] dimensions, the slice has
489 dimension [N - M], and the element at coordinates
490 [[|j1; ...; j(N-M)|]] in the slice is identical to the element
491 at coordinates [[|j1; ...; j(N-M); i1; ...; iM|]] in the original
492 array [a]. No copying of elements is involved: the slice and
493 the original array share the same storage space.
494
495 [Genarray.slice_right] applies only to Bigarrays in Fortran layout.
496 @raise Invalid_argument if [M >= N], or if [[|i1; ... ; iM|]]
497 is outside the bounds of [a]. *)
498
499 external blit: ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> unit
500 = "caml_ba_blit"
501 (** Copy all elements of a Bigarray in another Bigarray.
502 [Genarray.blit src dst] copies all elements of [src] into
503 [dst]. Both arrays [src] and [dst] must have the same number of
504 dimensions and equal dimensions. Copying a sub-array of [src]
505 to a sub-array of [dst] can be achieved by applying [Genarray.blit]
506 to sub-array or slices of [src] and [dst]. *)
507
508 external fill: ('a, 'b, 'c) t -> 'a -> unit = "caml_ba_fill"
509 (** Set all elements of a Bigarray to a given value.
510 [Genarray.fill a v] stores the value [v] in all elements of
511 the Bigarray [a]. Setting only some elements of [a] to [v]
512 can be achieved by applying [Genarray.fill] to a sub-array
513 or a slice of [a]. *)
514 end
515
516(** {1 Zero-dimensional arrays} *)
517
518(** Zero-dimensional arrays. The [Array0] structure provides operations
519 similar to those of {!Bigarray.Genarray}, but specialized to the case
520 of zero-dimensional arrays that only contain a single scalar value.
521 Statically knowing the number of dimensions of the array allows
522 faster operations, and more precise static type-checking.
523 @since 4.05 *)
524module Array0 : sig
525 type (!'a, !'b, !'c) t
526 (** The type of zero-dimensional Bigarrays whose elements have
527 OCaml type ['a], representation kind ['b], and memory layout ['c]. *)
528
529 val create: ('a, 'b) kind -> 'c layout -> ('a, 'b, 'c) t
530 (** [Array0.create kind layout] returns a new Bigarray of zero dimension.
531 [kind] and [layout] determine the array element kind and the array
532 layout as described for {!Genarray.create}. *)
533
534 val init: ('a, 'b) kind -> 'c layout -> 'a -> ('a, 'b, 'c) t
535 (** [Array0.init kind layout v] behaves like [Array0.create kind layout]
536 except that the element is additionally initialized to the value [v].
537
538 @since 4.12 *)
539
540 external kind: ('a, 'b, 'c) t -> ('a, 'b) kind = "caml_ba_kind"
541 (** Return the kind of the given Bigarray. *)
542
543 external layout: ('a, 'b, 'c) t -> 'c layout = "caml_ba_layout"
544 (** Return the layout of the given Bigarray. *)
545
546 val change_layout: ('a, 'b, 'c) t -> 'd layout -> ('a, 'b, 'd) t
547 (** [Array0.change_layout a layout] returns a Bigarray with the
548 specified [layout], sharing the data with [a]. No copying of elements
549 is involved: the new array and the original array share the same
550 storage space.
551
552 @since 4.06
553 *)
554
555 val size_in_bytes : ('a, 'b, 'c) t -> int
556 (** [size_in_bytes a] is [a]'s {!kind_size_in_bytes}. *)
557
558 val get: ('a, 'b, 'c) t -> 'a
559 (** [Array0.get a] returns the only element in [a]. *)
560
561 val set: ('a, 'b, 'c) t -> 'a -> unit
562 (** [Array0.set a x v] stores the value [v] in [a]. *)
563
564 external blit: ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> unit = "caml_ba_blit"
565 (** Copy the first Bigarray to the second Bigarray.
566 See {!Genarray.blit} for more details. *)
567
568 external fill: ('a, 'b, 'c) t -> 'a -> unit = "caml_ba_fill"
569 (** Fill the given Bigarray with the given value.
570 See {!Genarray.fill} for more details. *)
571
572 val of_value: ('a, 'b) kind -> 'c layout -> 'a -> ('a, 'b, 'c) t
573 (** Build a zero-dimensional Bigarray initialized from the
574 given value. *)
575
576end
577
578
579(** {1 One-dimensional arrays} *)
580
581(** One-dimensional arrays. The [Array1] structure provides operations
582 similar to those of
583 {!Bigarray.Genarray}, but specialized to the case of one-dimensional arrays.
584 (The {!Array2} and {!Array3} structures below provide operations
585 specialized for two- and three-dimensional arrays.)
586 Statically knowing the number of dimensions of the array allows
587 faster operations, and more precise static type-checking. *)
588module Array1 : sig
589 type (!'a, !'b, !'c) t
590 (** The type of one-dimensional Bigarrays whose elements have
591 OCaml type ['a], representation kind ['b], and memory layout ['c]. *)
592
593 val create: ('a, 'b) kind -> 'c layout -> int -> ('a, 'b, 'c) t
594 (** [Array1.create kind layout dim] returns a new Bigarray of
595 one dimension, whose size is [dim]. [kind] and [layout]
596 determine the array element kind and the array layout
597 as described for {!Genarray.create}. *)
598
599 val init: ('a, 'b) kind -> 'c layout -> int -> (int -> 'a) ->
600 ('a, 'b, 'c) t
601 (** [Array1.init kind layout dim f] returns a new Bigarray [b]
602 of one dimension, whose size is [dim]. [kind] and [layout]
603 determine the array element kind and the array layout
604 as described for {!Genarray.create}.
605
606 Each element [Array1.get b i] of the array is initialized to the
607 result of [f i].
608
609 In other words, [Array1.init kind layout dimensions f] tabulates
610 the results of [f] applied to the indices of a new Bigarray whose
611 layout is described by [kind], [layout] and [dim].
612
613 @since 4.12 *)
614
615 external dim: ('a, 'b, 'c) t -> int = "%caml_ba_dim_1"
616 (** Return the size (dimension) of the given one-dimensional
617 Bigarray. *)
618
619 external kind: ('a, 'b, 'c) t -> ('a, 'b) kind = "caml_ba_kind"
620 (** Return the kind of the given Bigarray. *)
621
622 external layout: ('a, 'b, 'c) t -> 'c layout = "caml_ba_layout"
623 (** Return the layout of the given Bigarray. *)
624
625 val change_layout: ('a, 'b, 'c) t -> 'd layout -> ('a, 'b, 'd) t
626 (** [Array1.change_layout a layout] returns a Bigarray with the
627 specified [layout], sharing the data with [a] (and hence having
628 the same dimension as [a]). No copying of elements is involved: the
629 new array and the original array share the same storage space.
630
631 @since 4.06
632 *)
633
634
635 val size_in_bytes : ('a, 'b, 'c) t -> int
636 (** [size_in_bytes a] is the number of elements in [a]
637 multiplied by [a]'s {!kind_size_in_bytes}.
638
639 @since 4.03 *)
640
641 external get: ('a, 'b, 'c) t -> int -> 'a = "%caml_ba_ref_1"
642 (** [Array1.get a x], or alternatively [a.{x}],
643 returns the element of [a] at index [x].
644 [x] must be greater or equal than [0] and strictly less than
645 [Array1.dim a] if [a] has C layout. If [a] has Fortran layout,
646 [x] must be greater or equal than [1] and less or equal than
647 [Array1.dim a]. Otherwise, [Invalid_argument] is raised. *)
648
649 external set: ('a, 'b, 'c) t -> int -> 'a -> unit = "%caml_ba_set_1"
650 (** [Array1.set a x v], also written [a.{x} <- v],
651 stores the value [v] at index [x] in [a].
652 [x] must be inside the bounds of [a] as described in
653 {!Bigarray.Array1.get};
654 otherwise, [Invalid_argument] is raised. *)
655
656 external sub: ('a, 'b, 'c) t -> int -> int -> ('a, 'b, 'c) t
657 = "caml_ba_sub"
658 (** Extract a sub-array of the given one-dimensional Bigarray.
659 See {!Genarray.sub_left} for more details. *)
660
661 val slice: ('a, 'b, 'c) t -> int -> ('a, 'b, 'c) Array0.t
662 (** Extract a scalar (zero-dimensional slice) of the given one-dimensional
663 Bigarray. The integer parameter is the index of the scalar to
664 extract. See {!Bigarray.Genarray.slice_left} and
665 {!Bigarray.Genarray.slice_right} for more details.
666 @since 4.05 *)
667
668 external blit: ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> unit
669 = "caml_ba_blit"
670 (** Copy the first Bigarray to the second Bigarray.
671 See {!Genarray.blit} for more details. *)
672
673 external fill: ('a, 'b, 'c) t -> 'a -> unit = "caml_ba_fill"
674 (** Fill the given Bigarray with the given value.
675 See {!Genarray.fill} for more details. *)
676
677 val of_array: ('a, 'b) kind -> 'c layout -> 'a array -> ('a, 'b, 'c) t
678 (** Build a one-dimensional Bigarray initialized from the
679 given array. *)
680
681 external unsafe_get: ('a, 'b, 'c) t -> int -> 'a = "%caml_ba_unsafe_ref_1"
682 (** Like {!Bigarray.Array1.get}, but bounds checking is not always performed.
683 Use with caution and only when the program logic guarantees that
684 the access is within bounds. *)
685
686 external unsafe_set: ('a, 'b, 'c) t -> int -> 'a -> unit
687 = "%caml_ba_unsafe_set_1"
688 (** Like {!Bigarray.Array1.set}, but bounds checking is not always performed.
689 Use with caution and only when the program logic guarantees that
690 the access is within bounds. *)
691
692end
693
694
695(** {1 Two-dimensional arrays} *)
696
697(** Two-dimensional arrays. The [Array2] structure provides operations
698 similar to those of {!Bigarray.Genarray}, but specialized to the
699 case of two-dimensional arrays. *)
700module Array2 :
701 sig
702 type (!'a, !'b, !'c) t
703 (** The type of two-dimensional Bigarrays whose elements have
704 OCaml type ['a], representation kind ['b], and memory layout ['c]. *)
705
706 val create: ('a, 'b) kind -> 'c layout -> int -> int -> ('a, 'b, 'c) t
707 (** [Array2.create kind layout dim1 dim2] returns a new Bigarray of
708 two dimensions, whose size is [dim1] in the first dimension
709 and [dim2] in the second dimension. [kind] and [layout]
710 determine the array element kind and the array layout
711 as described for {!Bigarray.Genarray.create}. *)
712
713 val init: ('a, 'b) kind -> 'c layout -> int -> int ->
714 (int -> int -> 'a) -> ('a, 'b, 'c) t
715 (** [Array2.init kind layout dim1 dim2 f] returns a new Bigarray [b]
716 of two dimensions, whose size is [dim2] in the first dimension
717 and [dim2] in the second dimension. [kind] and [layout]
718 determine the array element kind and the array layout
719 as described for {!Bigarray.Genarray.create}.
720
721 Each element [Array2.get b i j] of the array is initialized to
722 the result of [f i j].
723
724 In other words, [Array2.init kind layout dim1 dim2 f] tabulates
725 the results of [f] applied to the indices of a new Bigarray whose
726 layout is described by [kind], [layout], [dim1] and [dim2].
727
728 @since 4.12 *)
729
730 external dim1: ('a, 'b, 'c) t -> int = "%caml_ba_dim_1"
731 (** Return the first dimension of the given two-dimensional Bigarray. *)
732
733 external dim2: ('a, 'b, 'c) t -> int = "%caml_ba_dim_2"
734 (** Return the second dimension of the given two-dimensional Bigarray. *)
735
736 external kind: ('a, 'b, 'c) t -> ('a, 'b) kind = "caml_ba_kind"
737 (** Return the kind of the given Bigarray. *)
738
739 external layout: ('a, 'b, 'c) t -> 'c layout = "caml_ba_layout"
740 (** Return the layout of the given Bigarray. *)
741
742 val change_layout: ('a, 'b, 'c) t -> 'd layout -> ('a, 'b, 'd) t
743 (** [Array2.change_layout a layout] returns a Bigarray with the
744 specified [layout], sharing the data with [a] (and hence having
745 the same dimensions as [a]). No copying of elements is involved: the
746 new array and the original array share the same storage space.
747 The dimensions are reversed, such that [get v [| a; b |]] in
748 C layout becomes [get v [| b+1; a+1 |]] in Fortran layout.
749
750 @since 4.06
751 *)
752
753
754 val size_in_bytes : ('a, 'b, 'c) t -> int
755 (** [size_in_bytes a] is the number of elements in [a]
756 multiplied by [a]'s {!kind_size_in_bytes}.
757
758 @since 4.03 *)
759
760 external get: ('a, 'b, 'c) t -> int -> int -> 'a = "%caml_ba_ref_2"
761 (** [Array2.get a x y], also written [a.{x,y}],
762 returns the element of [a] at coordinates ([x], [y]).
763 [x] and [y] must be within the bounds
764 of [a], as described for {!Bigarray.Genarray.get};
765 otherwise, [Invalid_argument] is raised. *)
766
767 external set: ('a, 'b, 'c) t -> int -> int -> 'a -> unit = "%caml_ba_set_2"
768 (** [Array2.set a x y v], or alternatively [a.{x,y} <- v],
769 stores the value [v] at coordinates ([x], [y]) in [a].
770 [x] and [y] must be within the bounds of [a],
771 as described for {!Bigarray.Genarray.set};
772 otherwise, [Invalid_argument] is raised. *)
773
774 external sub_left: ('a, 'b, c_layout) t -> int -> int -> ('a, 'b, c_layout) t
775 = "caml_ba_sub"
776 (** Extract a two-dimensional sub-array of the given two-dimensional
777 Bigarray by restricting the first dimension.
778 See {!Bigarray.Genarray.sub_left} for more details.
779 [Array2.sub_left] applies only to arrays with C layout. *)
780
781 external sub_right:
782 ('a, 'b, fortran_layout) t -> int -> int -> ('a, 'b, fortran_layout) t
783 = "caml_ba_sub"
784 (** Extract a two-dimensional sub-array of the given two-dimensional
785 Bigarray by restricting the second dimension.
786 See {!Bigarray.Genarray.sub_right} for more details.
787 [Array2.sub_right] applies only to arrays with Fortran layout. *)
788
789 val slice_left: ('a, 'b, c_layout) t -> int -> ('a, 'b, c_layout) Array1.t
790 (** Extract a row (one-dimensional slice) of the given two-dimensional
791 Bigarray. The integer parameter is the index of the row to
792 extract. See {!Bigarray.Genarray.slice_left} for more details.
793 [Array2.slice_left] applies only to arrays with C layout. *)
794
795 val slice_right:
796 ('a, 'b, fortran_layout) t -> int -> ('a, 'b, fortran_layout) Array1.t
797 (** Extract a column (one-dimensional slice) of the given
798 two-dimensional Bigarray. The integer parameter is the
799 index of the column to extract. See {!Bigarray.Genarray.slice_right}
800 for more details. [Array2.slice_right] applies only to arrays
801 with Fortran layout. *)
802
803 external blit: ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> unit
804 = "caml_ba_blit"
805 (** Copy the first Bigarray to the second Bigarray.
806 See {!Bigarray.Genarray.blit} for more details. *)
807
808 external fill: ('a, 'b, 'c) t -> 'a -> unit = "caml_ba_fill"
809 (** Fill the given Bigarray with the given value.
810 See {!Bigarray.Genarray.fill} for more details. *)
811
812 val of_array: ('a, 'b) kind -> 'c layout -> 'a array array -> ('a, 'b, 'c) t
813 (** Build a two-dimensional Bigarray initialized from the
814 given array of arrays. *)
815
816 external unsafe_get: ('a, 'b, 'c) t -> int -> int -> 'a
817 = "%caml_ba_unsafe_ref_2"
818 (** Like {!Bigarray.Array2.get}, but bounds checking is not always
819 performed. *)
820
821 external unsafe_set: ('a, 'b, 'c) t -> int -> int -> 'a -> unit
822 = "%caml_ba_unsafe_set_2"
823 (** Like {!Bigarray.Array2.set}, but bounds checking is not always
824 performed. *)
825
826end
827
828(** {1 Three-dimensional arrays} *)
829
830(** Three-dimensional arrays. The [Array3] structure provides operations
831 similar to those of {!Bigarray.Genarray}, but specialized to the case
832 of three-dimensional arrays. *)
833module Array3 :
834 sig
835 type (!'a, !'b, !'c) t
836 (** The type of three-dimensional Bigarrays whose elements have
837 OCaml type ['a], representation kind ['b], and memory layout ['c]. *)
838
839 val create: ('a, 'b) kind -> 'c layout -> int -> int -> int -> ('a, 'b, 'c) t
840 (** [Array3.create kind layout dim1 dim2 dim3] returns a new Bigarray of
841 three dimensions, whose size is [dim1] in the first dimension,
842 [dim2] in the second dimension, and [dim3] in the third.
843 [kind] and [layout] determine the array element kind and
844 the array layout as described for {!Bigarray.Genarray.create}. *)
845
846 val init: ('a, 'b) kind -> 'c layout -> int -> int -> int ->
847 (int -> int -> int -> 'a) -> ('a, 'b, 'c) t
848 (** [Array3.init kind layout dim1 dim2 dim3 f] returns a new Bigarray [b]
849 of three dimensions, whose size is [dim1] in the first dimension,
850 [dim2] in the second dimension, and [dim3] in the third.
851 [kind] and [layout] determine the array element kind and the array
852 layout as described for {!Bigarray.Genarray.create}.
853
854 Each element [Array3.get b i j k] of the array is initialized to
855 the result of [f i j k].
856
857 In other words, [Array3.init kind layout dim1 dim2 dim3 f] tabulates
858 the results of [f] applied to the indices of a new Bigarray whose
859 layout is described by [kind], [layout], [dim1], [dim2] and [dim3].
860
861 @since 4.12 *)
862
863 external dim1: ('a, 'b, 'c) t -> int = "%caml_ba_dim_1"
864 (** Return the first dimension of the given three-dimensional Bigarray. *)
865
866 external dim2: ('a, 'b, 'c) t -> int = "%caml_ba_dim_2"
867 (** Return the second dimension of the given three-dimensional Bigarray. *)
868
869 external dim3: ('a, 'b, 'c) t -> int = "%caml_ba_dim_3"
870 (** Return the third dimension of the given three-dimensional Bigarray. *)
871
872 external kind: ('a, 'b, 'c) t -> ('a, 'b) kind = "caml_ba_kind"
873 (** Return the kind of the given Bigarray. *)
874
875 external layout: ('a, 'b, 'c) t -> 'c layout = "caml_ba_layout"
876 (** Return the layout of the given Bigarray. *)
877
878
879 val change_layout: ('a, 'b, 'c) t -> 'd layout -> ('a, 'b, 'd) t
880 (** [Array3.change_layout a layout] returns a Bigarray with the
881 specified [layout], sharing the data with [a] (and hence having
882 the same dimensions as [a]). No copying of elements is involved: the
883 new array and the original array share the same storage space.
884 The dimensions are reversed, such that [get v [| a; b; c |]] in
885 C layout becomes [get v [| c+1; b+1; a+1 |]] in Fortran layout.
886
887 @since 4.06
888 *)
889
890 val size_in_bytes : ('a, 'b, 'c) t -> int
891 (** [size_in_bytes a] is the number of elements in [a]
892 multiplied by [a]'s {!kind_size_in_bytes}.
893
894 @since 4.03 *)
895
896 external get: ('a, 'b, 'c) t -> int -> int -> int -> 'a = "%caml_ba_ref_3"
897 (** [Array3.get a x y z], also written [a.{x,y,z}],
898 returns the element of [a] at coordinates ([x], [y], [z]).
899 [x], [y] and [z] must be within the bounds of [a],
900 as described for {!Bigarray.Genarray.get};
901 otherwise, [Invalid_argument] is raised. *)
902
903 external set: ('a, 'b, 'c) t -> int -> int -> int -> 'a -> unit
904 = "%caml_ba_set_3"
905 (** [Array3.set a x y v], or alternatively [a.{x,y,z} <- v],
906 stores the value [v] at coordinates ([x], [y], [z]) in [a].
907 [x], [y] and [z] must be within the bounds of [a],
908 as described for {!Bigarray.Genarray.set};
909 otherwise, [Invalid_argument] is raised. *)
910
911 external sub_left: ('a, 'b, c_layout) t -> int -> int -> ('a, 'b, c_layout) t
912 = "caml_ba_sub"
913 (** Extract a three-dimensional sub-array of the given
914 three-dimensional Bigarray by restricting the first dimension.
915 See {!Bigarray.Genarray.sub_left} for more details. [Array3.sub_left]
916 applies only to arrays with C layout. *)
917
918 external sub_right:
919 ('a, 'b, fortran_layout) t -> int -> int -> ('a, 'b, fortran_layout) t
920 = "caml_ba_sub"
921 (** Extract a three-dimensional sub-array of the given
922 three-dimensional Bigarray by restricting the second dimension.
923 See {!Bigarray.Genarray.sub_right} for more details. [Array3.sub_right]
924 applies only to arrays with Fortran layout. *)
925
926 val slice_left_1:
927 ('a, 'b, c_layout) t -> int -> int -> ('a, 'b, c_layout) Array1.t
928 (** Extract a one-dimensional slice of the given three-dimensional
929 Bigarray by fixing the first two coordinates.
930 The integer parameters are the coordinates of the slice to
931 extract. See {!Bigarray.Genarray.slice_left} for more details.
932 [Array3.slice_left_1] applies only to arrays with C layout. *)
933
934 val slice_right_1:
935 ('a, 'b, fortran_layout) t ->
936 int -> int -> ('a, 'b, fortran_layout) Array1.t
937 (** Extract a one-dimensional slice of the given three-dimensional
938 Bigarray by fixing the last two coordinates.
939 The integer parameters are the coordinates of the slice to
940 extract. See {!Bigarray.Genarray.slice_right} for more details.
941 [Array3.slice_right_1] applies only to arrays with Fortran
942 layout. *)
943
944 val slice_left_2: ('a, 'b, c_layout) t -> int -> ('a, 'b, c_layout) Array2.t
945 (** Extract a two-dimensional slice of the given three-dimensional
946 Bigarray by fixing the first coordinate.
947 The integer parameter is the first coordinate of the slice to
948 extract. See {!Bigarray.Genarray.slice_left} for more details.
949 [Array3.slice_left_2] applies only to arrays with C layout. *)
950
951 val slice_right_2:
952 ('a, 'b, fortran_layout) t -> int -> ('a, 'b, fortran_layout) Array2.t
953 (** Extract a two-dimensional slice of the given
954 three-dimensional Bigarray by fixing the last coordinate.
955 The integer parameter is the coordinate of the slice
956 to extract. See {!Bigarray.Genarray.slice_right} for more details.
957 [Array3.slice_right_2] applies only to arrays with Fortran
958 layout. *)
959
960 external blit: ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> unit
961 = "caml_ba_blit"
962 (** Copy the first Bigarray to the second Bigarray.
963 See {!Bigarray.Genarray.blit} for more details. *)
964
965 external fill: ('a, 'b, 'c) t -> 'a -> unit = "caml_ba_fill"
966 (** Fill the given Bigarray with the given value.
967 See {!Bigarray.Genarray.fill} for more details. *)
968
969 val of_array:
970 ('a, 'b) kind -> 'c layout -> 'a array array array -> ('a, 'b, 'c) t
971 (** Build a three-dimensional Bigarray initialized from the
972 given array of arrays of arrays. *)
973
974 external unsafe_get: ('a, 'b, 'c) t -> int -> int -> int -> 'a
975 = "%caml_ba_unsafe_ref_3"
976 (** Like {!Bigarray.Array3.get}, but bounds checking is not always
977 performed. *)
978
979 external unsafe_set: ('a, 'b, 'c) t -> int -> int -> int -> 'a -> unit
980 = "%caml_ba_unsafe_set_3"
981 (** Like {!Bigarray.Array3.set}, but bounds checking is not always
982 performed. *)
983
984end
985
986(** {1 Coercions between generic Bigarrays and fixed-dimension Bigarrays} *)
987
988external genarray_of_array0 :
989 ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genarray.t = "%identity"
990(** Return the generic Bigarray corresponding to the given zero-dimensional
991 Bigarray.
992 @since 4.05 *)
993
994external genarray_of_array1 :
995 ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genarray.t = "%identity"
996(** Return the generic Bigarray corresponding to the given one-dimensional
997 Bigarray. *)
998
999external genarray_of_array2 :
1000 ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genarray.t = "%identity"
1001(** Return the generic Bigarray corresponding to the given two-dimensional
1002 Bigarray. *)
1003
1004external genarray_of_array3 :
1005 ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genarray.t = "%identity"
1006(** Return the generic Bigarray corresponding to the given three-dimensional
1007 Bigarray. *)
1008
1009val array0_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
1010(** Return the zero-dimensional Bigarray corresponding to the given
1011 generic Bigarray.
1012 @raise Invalid_argument if the generic Bigarray
1013 does not have exactly zero dimension.
1014 @since 4.05 *)
1015
1016val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array1.t
1017(** Return the one-dimensional Bigarray corresponding to the given
1018 generic Bigarray.
1019 @raise Invalid_argument if the generic Bigarray
1020 does not have exactly one dimension. *)
1021
1022val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array2.t
1023(** Return the two-dimensional Bigarray corresponding to the given
1024 generic Bigarray.
1025 @raise Invalid_argument if the generic Bigarray
1026 does not have exactly two dimensions. *)
1027
1028val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array3.t
1029(** Return the three-dimensional Bigarray corresponding to the given
1030 generic Bigarray.
1031 @raise Invalid_argument if the generic Bigarray
1032 does not have exactly three dimensions. *)
1033
1034
1035(** {1 Re-shaping Bigarrays} *)
1036
1037val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c) Genarray.t
1038(** [reshape b [|d1;...;dN|]] converts the Bigarray [b] to a
1039 [N]-dimensional array of dimensions [d1]...[dN]. The returned
1040 array and the original array [b] share their data
1041 and have the same layout. For instance, assuming that [b]
1042 is a one-dimensional array of dimension 12, [reshape b [|3;4|]]
1043 returns a two-dimensional array [b'] of dimensions 3 and 4.
1044 If [b] has C layout, the element [(x,y)] of [b'] corresponds
1045 to the element [x * 3 + y] of [b]. If [b] has Fortran layout,
1046 the element [(x,y)] of [b'] corresponds to the element
1047 [x + (y - 1) * 4] of [b].
1048 The returned Bigarray must have exactly the same number of
1049 elements as the original Bigarray [b]. That is, the product
1050 of the dimensions of [b] must be equal to [i1 * ... * iN].
1051 Otherwise, [Invalid_argument] is raised. *)
1052
1053val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
1054(** Specialized version of {!Bigarray.reshape} for reshaping to
1055 zero-dimensional arrays.
1056 @since 4.05 *)
1057
1058val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
1059(** Specialized version of {!Bigarray.reshape} for reshaping to
1060 one-dimensional arrays. *)
1061
1062val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c) Array2.t
1063(** Specialized version of {!Bigarray.reshape} for reshaping to
1064 two-dimensional arrays. *)
1065
1066val reshape_3 :
1067 ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a, 'b, 'c) Array3.t
1068(** Specialized version of {!Bigarray.reshape} for reshaping to
1069 three-dimensional arrays. *)
1070
1071(** {1:bigarray_concurrency Bigarrays and concurrency safety}
1072
1073 Care must be taken when concurrently accessing bigarrays from multiple
1074 domains: accessing a bigarray will never crash a program, but unsynchronized
1075 accesses might yield surprising (non-sequentially-consistent) results.
1076
1077 {2:bigarray_atomicity Atomicity}
1078
1079 Every bigarray operation that accesses more than one array element is not
1080 atomic. This includes slicing, bliting, and filling bigarrays.
1081
1082 For example, consider the following program:
1083{[open Bigarray
1084let size = 100_000_000
1085let a = Array1.init Int C_layout size (fun _ -> 1)
1086let update f a () =
1087 for i = 0 to size - 1 do a.{i} <- f a.{i} done
1088let d1 = Domain.spawn (update (fun x -> x + 1) a)
1089let d2 = Domain.spawn (update (fun x -> 2 * x + 1) a)
1090let () = Domain.join d1; Domain.join d2
1091]}
1092
1093 After executing this code, each field of the bigarray [a] is either [2],
1094 [3], [4] or [5]. If atomicity is required, then the user must implement
1095 their own synchronization (for example, using {!Mutex.t}).
1096
1097 {2:bigarray_data_race Data races}
1098
1099 If two domains only access disjoint parts of the bigarray, then the
1100 observed behaviour is the equivalent to some sequential interleaving of the
1101 operations from the two domains.
1102
1103 A data race is said to occur when two domains access the same bigarray
1104 element without synchronization and at least one of the accesses is a
1105 write. In the absence of data races, the observed behaviour is equivalent
1106 to some sequential interleaving of the operations from different domains.
1107
1108 Whenever possible, data races should be avoided by using synchronization to
1109 mediate the accesses to the bigarray elements.
1110
1111 Indeed, in the presence of data races, programs will not crash but the
1112 observed behaviour may not be equivalent to any sequential interleaving of
1113 operations from different domains.
1114
1115 {2:bigarrarray_data_race_tearing Tearing}
1116
1117 Bigarrays have a distinct caveat in the presence of data races:
1118 concurrent bigarray operations might produce surprising values due to
1119 tearing. More precisely, the interleaving of partial writes and reads might
1120 create values that would not exist with a sequential execution.
1121 For instance, at the end of
1122{[let res = Array1.init Complex64 c_layout size (fun _ -> Complex.zero)
1123let d1 = Domain.spawn (fun () -> Array1.fill res Complex.one)
1124let d2 = Domain.spawn (fun () -> Array1.fill res Complex.i)
1125let () = Domain.join d1; Domain.join d2
1126]}
1127 the [res] bigarray might contain values that are neither [Complex.i]
1128 nor [Complex.one] (for instance [1 + i]).
1129*)