1Stdlib.Bigarray(3) OCaml library Stdlib.Bigarray(3)
2
3
4
6 Stdlib.Bigarray - no description
7
9 Module Stdlib.Bigarray
10
12 Module Bigarray
13 : (module Stdlib__bigarray)
14
15
16
17
18
19
20
21
22
23 Element kinds
24 Bigarrays can contain elements of the following kinds:
25
26 -IEEE single precision (32 bits) floating-point numbers ( Bigar‐
27 ray.float32_elt ),
28
29 -IEEE double precision (64 bits) floating-point numbers ( Bigar‐
30 ray.float64_elt ),
31
32 -IEEE single precision (2 * 32 bits) floating-point complex numbers (
33 Bigarray.complex32_elt ),
34
35 -IEEE double precision (2 * 64 bits) floating-point complex numbers (
36 Bigarray.complex64_elt ),
37
38 -8-bit integers (signed or unsigned) ( Bigarray.int8_signed_elt or
39 Bigarray.int8_unsigned_elt ),
40
41 -16-bit integers (signed or unsigned) ( Bigarray.int16_signed_elt or
42 Bigarray.int16_unsigned_elt ),
43
44 -OCaml integers (signed, 31 bits on 32-bit architectures, 63 bits on
45 64-bit architectures) ( Bigarray.int_elt ),
46
47 -32-bit signed integers ( Bigarray.int32_elt ),
48
49 -64-bit signed integers ( Bigarray.int64_elt ),
50
51 -platform-native signed integers (32 bits on 32-bit architectures, 64
52 bits on 64-bit architectures) ( Bigarray.nativeint_elt ).
53
54 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
58 type float32_elt =
59 | Float32_elt
60
61
62
63
64 type float64_elt =
65 | Float64_elt
66
67
68
69
70 type int8_signed_elt =
71 | Int8_signed_elt
72
73
74
75
76 type int8_unsigned_elt =
77 | Int8_unsigned_elt
78
79
80
81
82 type int16_signed_elt =
83 | Int16_signed_elt
84
85
86
87
88 type int16_unsigned_elt =
89 | Int16_unsigned_elt
90
91
92
93
94 type int32_elt =
95 | Int32_elt
96
97
98
99
100 type int64_elt =
101 | Int64_elt
102
103
104
105
106 type int_elt =
107 | Int_elt
108
109
110
111
112 type nativeint_elt =
113 | Nativeint_elt
114
115
116
117
118 type complex32_elt =
119 | Complex32_elt
120
121
122
123
124 type complex64_elt =
125 | Complex64_elt
126
127
128
129
130 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
145
146 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
154 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
160 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
164
165 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
171
172
173
174 val float32 : (float, float32_elt) kind
175
176 See Bigarray.char .
177
178
179
180 val float64 : (float, float64_elt) kind
181
182 See Bigarray.char .
183
184
185
186 val complex32 : (Complex.t, complex32_elt) kind
187
188 See Bigarray.char .
189
190
191
192 val complex64 : (Complex.t, complex64_elt) kind
193
194 See Bigarray.char .
195
196
197
198 val int8_signed : (int, int8_signed_elt) kind
199
200 See Bigarray.char .
201
202
203
204 val int8_unsigned : (int, int8_unsigned_elt) kind
205
206 See Bigarray.char .
207
208
209
210 val int16_signed : (int, int16_signed_elt) kind
211
212 See Bigarray.char .
213
214
215
216 val int16_unsigned : (int, int16_unsigned_elt) kind
217
218 See Bigarray.char .
219
220
221
222 val int : (int, int_elt) kind
223
224 See Bigarray.char .
225
226
227
228 val int32 : (int32, int32_elt) kind
229
230 See Bigarray.char .
231
232
233
234 val int64 : (int64, int64_elt) kind
235
236 See Bigarray.char .
237
238
239
240 val nativeint : (nativeint, nativeint_elt) kind
241
242 See Bigarray.char .
243
244
245
246 val char : (char, int8_unsigned_elt) kind
247
248 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
260
261
262 val kind_size_in_bytes : ('a, 'b) kind -> int
263
264
265 kind_size_in_bytes k is the number of bytes used to store an element of
266 type k .
267
268
269 Since 4.03.0
270
271
272
273
274 Array layouts
275 type c_layout =
276 | C_layout_typ
277
278
279 See Bigarray.fortran_layout .
280
281
282 type fortran_layout =
283 | Fortran_layout_typ
284
285
286 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
291 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
297 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
303 Each layout style is identified at the type level by the phantom types
304 Bigarray.c_layout and Bigarray.fortran_layout respectively.
305
306
307
308
309 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
314 type 'a layout =
315 | C_layout : c_layout layout
316 | Fortran_layout : fortran_layout layout
317
318
319
320
321
322 val c_layout : c_layout layout
323
324
325
326
327 val fortran_layout : fortran_layout layout
328
329
330
331
332
333 Generic arrays (of arbitrarily many dimensions)
334 module Genarray : sig end
335
336
337
338
339
340
341 Zero-dimensional arrays
342 module Array0 : sig end
343
344
345 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
351
352 Since 4.05.0
353
354
355
356
357 One-dimensional arrays
358 module Array1 : sig end
359
360
361 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
369
370
371
372 Two-dimensional arrays
373 module Array2 : sig end
374
375
376 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
380
381
382
383 Three-dimensional arrays
384 module Array3 : sig end
385
386
387 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
391
392
393
394 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
398 Return the generic Bigarray corresponding to the given zero-dimensional
399 Bigarray.
400
401
402 Since 4.05.0
403
404
405
406 val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
407 ray.t
408
409 Return the generic Bigarray corresponding to the given one-dimensional
410 Bigarray.
411
412
413
414 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
415 ray.t
416
417 Return the generic Bigarray corresponding to the given two-dimensional
418 Bigarray.
419
420
421
422 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
423 ray.t
424
425 Return the generic Bigarray corresponding to the given three-dimen‐
426 sional Bigarray.
427
428
429
430 val array0_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
431 Array0.t
432
433 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
437
438 Since 4.05.0
439
440
441
442 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
443 Array1.t
444
445 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
449
450
451 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
452 Array2.t
453
454 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
458
459
460 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
461 Array3.t
462
463 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
467
468
469
470 Re-shaping Bigarrays
471 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
472 Genarray.t
473
474
475 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
487
488
489 val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
490
491 Specialized version of Bigarray.reshape for reshaping to zero-dimen‐
492 sional arrays.
493
494
495 Since 4.05.0
496
497
498
499 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
500
501 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
502 sional arrays.
503
504
505
506 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
507 Array2.t
508
509 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
510 sional arrays.
511
512
513
514 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
515 'b, 'c) Array3.t
516
517 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
518 sional arrays.
519
520
521
522
523
524OCamldoc 2019-07-30 Stdlib.Bigarray(3)