1Stdlib.Bigarray(3) OCaml library Stdlib.Bigarray(3)
2
6 Stdlib.Bigarray - no description
7
9 Module Stdlib.Bigarray
10
12 Module Bigarray
13 : (module Stdlib__bigarray)
14 Element kinds
24 Bigarrays can contain elements of the following kinds:
25 -IEEE single precision (32 bits) floating-point numbers ( Bigar‐
27 ray.float32_elt ),
28 -IEEE double precision (64 bits) floating-point numbers ( Bigar‐
30 ray.float64_elt ),
31 -IEEE single precision (2 * 32 bits) floating-point complex numbers (
33 Bigarray.complex32_elt ),
34 -IEEE double precision (2 * 64 bits) floating-point complex numbers (
36 Bigarray.complex64_elt ),
37 -8-bit integers (signed or unsigned) ( Bigarray.int8_signed_elt or
39 Bigarray.int8_unsigned_elt ),
40 -16-bit integers (signed or unsigned) ( Bigarray.int16_signed_elt or
42 Bigarray.int16_unsigned_elt ),
43 -OCaml integers (signed, 31 bits on 32-bit architectures, 63 bits on
45 64-bit architectures) ( Bigarray.int_elt ),
46 -32-bit signed integers ( Bigarray.int32_elt ),
48 -64-bit signed integers ( Bigarray.int64_elt ),
50 -platform-native signed integers (32 bits on 32-bit architectures, 64
52 bits on 64-bit architectures) ( Bigarray.nativeint_elt ).
53 Each element kind is represented at the type level by one of the *_elt
55 types defined below (defined with a single constructor instead of
56 abstract types for technical injectivity reasons).
57 type float32_elt =
59 | Float32_elt
60 type float64_elt =
65 | Float64_elt
66 type int8_signed_elt =
71 | Int8_signed_elt
72 type int8_unsigned_elt =
77 | Int8_unsigned_elt
78 type int16_signed_elt =
83 | Int16_signed_elt
84 type int16_unsigned_elt =
89 | Int16_unsigned_elt
90 type int32_elt =
95 | Int32_elt
96 type int64_elt =
101 | Int64_elt
102 type int_elt =
107 | Int_elt
108 type nativeint_elt =
113 | Nativeint_elt
114 type complex32_elt =
119 | Complex32_elt
120 type complex64_elt =
125 | Complex64_elt
126 type ('a, 'b) kind =
131 | Float32 : (float, float32_elt) kind
132 | Float64 : (float, float64_elt) kind
133 | Int8_signed : (int, int8_signed_elt) kind
134 | Int8_unsigned : (int, int8_unsigned_elt) kind
135 | Int16_signed : (int, int16_signed_elt) kind
136 | Int16_unsigned : (int, int16_unsigned_elt) kind
137 | Int32 : (int32, int32_elt) kind
138 | Int64 : (int64, int64_elt) kind
139 | Int : (int, int_elt) kind
140 | Nativeint : (nativeint, nativeint_elt) kind
141 | Complex32 : (Complex.t, complex32_elt) kind
142 | Complex64 : (Complex.t, complex64_elt) kind
143 | Char : (char, int8_unsigned_elt) kind
144 To each element kind is associated an OCaml type, which is the type of
147 OCaml values that can be stored in the Bigarray or read back from it.
148 This type is not necessarily the same as the type of the array elements
149 proper: for instance, a Bigarray whose elements are of kind float32_elt
150 contains 32-bit single precision floats, but reading or writing one of
151 its elements from OCaml uses the OCaml type float , which is 64-bit
152 double precision floats.
153 The GADT type ('a, 'b) kind captures this association of an OCaml type
155 'a for values read or written in the Bigarray, and of an element kind
156 'b which represents the actual contents of the Bigarray. Its construc‐
157 tors list all possible associations of OCaml types with element kinds,
158 and are re-exported below for backward-compatibility reasons.
159 Using a generalized algebraic datatype (GADT) here allows writing
161 well-typed polymorphic functions whose return type depend on the argu‐
162 ment type, such as:
163 let zero : type a b. (a, b) kind -> a = function | Float32 -> 0.0 |
166 Complex32 -> Complex.zero | Float64 -> 0.0 | Complex64 -> Complex.zero
167 | Int8_signed -> 0 | Int8_unsigned -> 0 | Int16_signed -> 0 |
168 Int16_unsigned -> 0 | Int32 -> 0l | Int64 -> 0L | Int -> 0 | Nativeint
169 -> 0n | Char -> '\000'
170 val float32 : (float, float32_elt) kind
175 See Bigarray.char .
177 val float64 : (float, float64_elt) kind
181 See Bigarray.char .
183 val complex32 : (Complex.t, complex32_elt) kind
187 See Bigarray.char .
189 val complex64 : (Complex.t, complex64_elt) kind
193 See Bigarray.char .
195 val int8_signed : (int, int8_signed_elt) kind
199 See Bigarray.char .
201 val int8_unsigned : (int, int8_unsigned_elt) kind
205 See Bigarray.char .
207 val int16_signed : (int, int16_signed_elt) kind
211 See Bigarray.char .
213 val int16_unsigned : (int, int16_unsigned_elt) kind
217 See Bigarray.char .
219 val int : (int, int_elt) kind
223 See Bigarray.char .
225 val int32 : (int32, int32_elt) kind
229 See Bigarray.char .
231 val int64 : (int64, int64_elt) kind
235 See Bigarray.char .
237 val nativeint : (nativeint, nativeint_elt) kind
241 See Bigarray.char .
243 val char : (char, int8_unsigned_elt) kind
247 As shown by the types of the values above, Bigarrays of kind
249 float32_elt and float64_elt are accessed using the OCaml type float .
250 Bigarrays of complex kinds complex32_elt , complex64_elt are accessed
251 with the OCaml type Complex.t . Bigarrays of integer kinds are accessed
252 using the smallest OCaml integer type large enough to represent the
253 array elements: int for 8- and 16-bit integer Bigarrays, as well as
254 OCaml-integer Bigarrays; int32 for 32-bit integer Bigarrays; int64 for
255 64-bit integer Bigarrays; and nativeint for platform-native integer
256 Bigarrays. Finally, Bigarrays of kind int8_unsigned_elt can also be
257 accessed as arrays of characters instead of arrays of small integers,
258 by using the kind value char instead of int8_unsigned .
259 val kind_size_in_bytes : ('a, 'b) kind -> int
263 kind_size_in_bytes k is the number of bytes used to store an element of
266 type k .
267 Since 4.03.0
270 Array layouts
275 type c_layout =
276 | C_layout_typ
277 See Bigarray.fortran_layout .
280 type fortran_layout =
283 | Fortran_layout_typ
284 To facilitate interoperability with existing C and Fortran code, this
287 library supports two different memory layouts for Bigarrays, one com‐
288 patible with the C conventions, the other compatible with the Fortran
289 conventions.
290 In the C-style layout, array indices start at 0, and multi-dimensional
292 arrays are laid out in row-major format. That is, for a two-dimen‐
293 sional array, all elements of row 0 are contiguous in memory, followed
294 by all elements of row 1, etc. In other terms, the array elements at
295 (x,y) and (x, y+1) are adjacent in memory.
296 In the Fortran-style layout, array indices start at 1, and multi-dimen‐
298 sional arrays are laid out in column-major format. That is, for a
299 two-dimensional array, all elements of column 0 are contiguous in mem‐
300 ory, followed by all elements of column 1, etc. In other terms, the
301 array elements at (x,y) and (x+1, y) are adjacent in memory.
302 Each layout style is identified at the type level by the phantom types
304 Bigarray.c_layout and Bigarray.fortran_layout respectively.
305 Supported layouts
310 The GADT type 'a layout represents one of the two supported memory lay‐
311 outs: C-style or Fortran-style. Its constructors are re-exported as
312 values below for backward-compatibility reasons.
313 type 'a layout =
315 | C_layout : c_layout layout
316 | Fortran_layout : fortran_layout layout
317 val c_layout : c_layout layout
323 val fortran_layout : fortran_layout layout
328 Generic arrays (of arbitrarily many dimensions)
334 module Genarray : sig end
335 Zero-dimensional arrays
342 module Array0 : sig end
343 Zero-dimensional arrays. The Array0 structure provides operations simi‐
346 lar to those of Bigarray.Genarray , but specialized to the case of
347 zero-dimensional arrays that only contain a single scalar value. Stat‐
348 ically knowing the number of dimensions of the array allows faster
349 operations, and more precise static type-checking.
350 Since 4.05.0
353 One-dimensional arrays
358 module Array1 : sig end
359 One-dimensional arrays. The Array1 structure provides operations simi‐
362 lar to those of Bigarray.Genarray , but specialized to the case of
363 one-dimensional arrays. (The Bigarray.Array2 and Bigarray.Array3
364 structures below provide operations specialized for two- and
365 three-dimensional arrays.) Statically knowing the number of dimensions
366 of the array allows faster operations, and more precise static
367 type-checking.
368 Two-dimensional arrays
373 module Array2 : sig end
374 Two-dimensional arrays. The Array2 structure provides operations simi‐
377 lar to those of Bigarray.Genarray , but specialized to the case of
378 two-dimensional arrays.
379 Three-dimensional arrays
384 module Array3 : sig end
385 Three-dimensional arrays. The Array3 structure provides operations sim‐
388 ilar to those of Bigarray.Genarray , but specialized to the case of
389 three-dimensional arrays.
390 Coercions between generic Bigarrays and fixed-dimension Bigarrays
395 val genarray_of_array0 : ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genar‐
396 ray.t
397 Return the generic Bigarray corresponding to the given zero-dimensional
399 Bigarray.
400 Since 4.05.0
403 val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
407 ray.t
408 Return the generic Bigarray corresponding to the given one-dimensional
410 Bigarray.
411 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
415 ray.t
416 Return the generic Bigarray corresponding to the given two-dimensional
418 Bigarray.
419 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
423 ray.t
424 Return the generic Bigarray corresponding to the given three-dimen‐
426 sional Bigarray.
427 val array0_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
431 Array0.t
432 Return the zero-dimensional Bigarray corresponding to the given generic
434 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
435 exactly zero dimension.
436 Since 4.05.0
439 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
443 Array1.t
444 Return the one-dimensional Bigarray corresponding to the given generic
446 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
447 exactly one dimension.
448 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
452 Array2.t
453 Return the two-dimensional Bigarray corresponding to the given generic
455 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
456 exactly two dimensions.
457 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
461 Array3.t
462 Return the three-dimensional Bigarray corresponding to the given
464 generic Bigarray. Raise Invalid_argument if the generic Bigarray does
465 not have exactly three dimensions.
466 Re-shaping Bigarrays
471 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
472 Genarray.t
473 reshape b [|d1;...;dN|] converts the Bigarray b to a N -dimensional
476 array of dimensions d1 ... dN . The returned array and the original
477 array b share their data and have the same layout. For instance,
478 assuming that b is a one-dimensional array of dimension 12, reshape b
479 [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4. If b
480 has C layout, the element (x,y) of b' corresponds to the element x * 3
481 + y of b . If b has Fortran layout, the element (x,y) of b' corre‐
482 sponds to the element x + (y - 1) * 4 of b . The returned Bigarray
483 must have exactly the same number of elements as the original Bigarray
484 b . That is, the product of the dimensions of b must be equal to i1 *
485 ... * iN . Otherwise, Invalid_argument is raised.
486 val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
490 Specialized version of Bigarray.reshape for reshaping to zero-dimen‐
492 sional arrays.
493 Since 4.05.0
496 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
500 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
502 sional arrays.
503 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
507 Array2.t
508 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
510 sional arrays.
511 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
515 'b, 'c) Array3.t
516 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
518 sional arrays.
519OCamldoc 2019-07-30 Stdlib.Bigarray(3)