1Stdlib.Bigarray(3)               OCaml library              Stdlib.Bigarray(3)
2
3
4

NAME

6       Stdlib.Bigarray - no description
7

Module

9       Module   Stdlib.Bigarray
10

Documentation

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 Bi‐
39       garray.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  ab‐
56       stract 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
166           | Float32 -> 0.0 | Complex32 -> Complex.zero
167           | Float64 -> 0.0 | Complex64 -> Complex.zero
168           | Int8_signed -> 0 | Int8_unsigned -> 0
169           | Int16_signed -> 0 | Int16_unsigned -> 0
170           | Int32 -> 0l | Int64 -> 0L
171           | Int -> 0 | Nativeint -> 0n
172           | Char -> '\000'
173
174
175
176
177       val float32 : (float, float32_elt) kind
178
179       See Bigarray.char .
180
181
182
183       val float64 : (float, float64_elt) kind
184
185       See Bigarray.char .
186
187
188
189       val complex32 : (Complex.t, complex32_elt) kind
190
191       See Bigarray.char .
192
193
194
195       val complex64 : (Complex.t, complex64_elt) kind
196
197       See Bigarray.char .
198
199
200
201       val int8_signed : (int, int8_signed_elt) kind
202
203       See Bigarray.char .
204
205
206
207       val int8_unsigned : (int, int8_unsigned_elt) kind
208
209       See Bigarray.char .
210
211
212
213       val int16_signed : (int, int16_signed_elt) kind
214
215       See Bigarray.char .
216
217
218
219       val int16_unsigned : (int, int16_unsigned_elt) kind
220
221       See Bigarray.char .
222
223
224
225       val int : (int, int_elt) kind
226
227       See Bigarray.char .
228
229
230
231       val int32 : (int32, int32_elt) kind
232
233       See Bigarray.char .
234
235
236
237       val int64 : (int64, int64_elt) kind
238
239       See Bigarray.char .
240
241
242
243       val nativeint : (nativeint, nativeint_elt) kind
244
245       See Bigarray.char .
246
247
248
249       val char : (char, int8_unsigned_elt) kind
250
251       As  shown  by  the  types  of  the  values  above,  Bigarrays  of  kind
252       float32_elt and float64_elt are accessed using the OCaml type  float  .
253       Bigarrays  of  complex kinds complex32_elt , complex64_elt are accessed
254       with the OCaml type Complex.t . Bigarrays of integer kinds are accessed
255       using the smallest OCaml integer type large enough to represent the ar‐
256       ray elements: int for 8- and  16-bit  integer  Bigarrays,  as  well  as
257       OCaml-integer  Bigarrays; int32 for 32-bit integer Bigarrays; int64 for
258       64-bit integer Bigarrays; and nativeint for platform-native integer Bi‐
259       garrays.   Finally, Bigarrays of kind int8_unsigned_elt can also be ac‐
260       cessed as arrays of characters instead of arrays of small integers,  by
261       using the kind value char instead of int8_unsigned .
262
263
264
265       val kind_size_in_bytes : ('a, 'b) kind -> int
266
267
268       kind_size_in_bytes k is the number of bytes used to store an element of
269       type k .
270
271
272       Since 4.03.0
273
274
275
276
277   Array layouts
278       type c_layout =
279        | C_layout_typ
280
281
282       See Bigarray.fortran_layout .
283
284
285       type fortran_layout =
286        | Fortran_layout_typ
287
288
289       To facilitate interoperability with existing C and Fortran  code,  this
290       library  supports  two different memory layouts for Bigarrays, one com‐
291       patible with the C conventions, the other compatible with  the  Fortran
292       conventions.
293
294       In  the C-style layout, array indices start at 0, and multi-dimensional
295       arrays are laid out in row-major format.  That  is,  for  a  two-dimen‐
296       sional  array, all elements of row 0 are contiguous in memory, followed
297       by all elements of row 1, etc.  In other terms, the array  elements  at
298       (x,y) and (x, y+1) are adjacent in memory.
299
300       In the Fortran-style layout, array indices start at 1, and multi-dimen‐
301       sional arrays are laid out in column-major  format.   That  is,  for  a
302       two-dimensional  array, all elements of column 0 are contiguous in mem‐
303       ory, followed by all elements of column 1, etc.  In  other  terms,  the
304       array elements at (x,y) and (x+1, y) are adjacent in memory.
305
306       Each  layout style is identified at the type level by the phantom types
307       Bigarray.c_layout and Bigarray.fortran_layout respectively.
308
309
310
311
312   Supported layouts
313       The GADT type 'a layout represents one of the two supported memory lay‐
314       outs:  C-style  or  Fortran-style.  Its constructors are re-exported as
315       values below for backward-compatibility reasons.
316
317       type 'a layout =
318        | C_layout : c_layout layout
319        | Fortran_layout : fortran_layout layout
320
321
322
323
324
325       val c_layout : c_layout layout
326
327
328
329
330       val fortran_layout : fortran_layout layout
331
332
333
334
335
336   Generic arrays (of arbitrarily many dimensions)
337       module Genarray : sig end
338
339
340
341
342
343
344   Zero-dimensional arrays
345       module Array0 : sig end
346
347
348       Zero-dimensional arrays. The Array0 structure provides operations simi‐
349       lar  to  those  of  Bigarray.Genarray  , but specialized to the case of
350       zero-dimensional arrays that only contain a single scalar value.  Stat‐
351       ically  knowing the number of dimensions of the array allows faster op‐
352       erations, and more precise static type-checking.
353
354
355       Since 4.05.0
356
357
358
359
360   One-dimensional arrays
361       module Array1 : sig end
362
363
364       One-dimensional arrays. The Array1 structure provides operations  simi‐
365       lar  to  those  of  Bigarray.Genarray  , but specialized to the case of
366       one-dimensional  arrays.   (The  Bigarray.Array2  and   Bigarray.Array3
367       structures  below provide operations specialized for two- and three-di‐
368       mensional arrays.)  Statically knowing the number of dimensions of  the
369       array allows faster operations, and more precise static type-checking.
370
371
372
373
374   Two-dimensional arrays
375       module Array2 : sig end
376
377
378       Two-dimensional  arrays. The Array2 structure provides operations simi‐
379       lar to those of Bigarray.Genarray , but  specialized  to  the  case  of
380       two-dimensional arrays.
381
382
383
384
385   Three-dimensional arrays
386       module Array3 : sig end
387
388
389       Three-dimensional arrays. The Array3 structure provides operations sim‐
390       ilar to those of Bigarray.Genarray , but specialized  to  the  case  of
391       three-dimensional arrays.
392
393
394
395
396   Coercions between generic Bigarrays and fixed-dimension Bigarrays
397       val  genarray_of_array0  : ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genar‐
398       ray.t
399
400       Return the generic Bigarray corresponding to the given zero-dimensional
401       Bigarray.
402
403
404       Since 4.05.0
405
406
407
408       val  genarray_of_array1  : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
409       ray.t
410
411       Return the generic Bigarray corresponding to the given  one-dimensional
412       Bigarray.
413
414
415
416       val  genarray_of_array2  : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
417       ray.t
418
419       Return the generic Bigarray corresponding to the given  two-dimensional
420       Bigarray.
421
422
423
424       val  genarray_of_array3  : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
425       ray.t
426
427       Return the generic Bigarray corresponding  to  the  given  three-dimen‐
428       sional Bigarray.
429
430
431
432       val  array0_of_genarray  :  ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
433       ray0.t
434
435       Return the zero-dimensional Bigarray corresponding to the given generic
436       Bigarray.
437
438
439       Since 4.05.0
440
441
442       Raises  Invalid_argument  if the generic Bigarray does not have exactly
443       zero dimension.
444
445
446
447       val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a,  'b,  'c)  Ar‐
448       ray1.t
449
450       Return  the one-dimensional Bigarray corresponding to the given generic
451       Bigarray.
452
453
454       Raises Invalid_argument if the generic Bigarray does not  have  exactly
455       one dimension.
456
457
458
459       val  array2_of_genarray  :  ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
460       ray2.t
461
462       Return the two-dimensional Bigarray corresponding to the given  generic
463       Bigarray.
464
465
466       Raises  Invalid_argument  if the generic Bigarray does not have exactly
467       two dimensions.
468
469
470
471       val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a,  'b,  'c)  Ar‐
472       ray3.t
473
474       Return  the  three-dimensional  Bigarray  corresponding  to  the  given
475       generic Bigarray.
476
477
478       Raises Invalid_argument if the generic Bigarray does not  have  exactly
479       three dimensions.
480
481
482
483
484   Re-shaping Bigarrays
485       val  reshape  :  ('a,  'b,  'c) Genarray.t -> int array -> ('a, 'b, 'c)
486       Genarray.t
487
488
489       reshape b [|d1;...;dN|] converts the Bigarray b to a N -dimensional ar‐
490       ray of dimensions d1 ...  dN .  The returned array and the original ar‐
491       ray b share their data and have the same layout.  For instance,  assum‐
492       ing  that  b  is  a  one-dimensional  array  of dimension 12, reshape b
493       [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4.  If b
494       has  C layout, the element (x,y) of b' corresponds to the element x * 3
495       + y of b .  If b has Fortran layout, the element  (x,y)  of  b'  corre‐
496       sponds  to  the  element  x + (y - 1) * 4 of b .  The returned Bigarray
497       must have exactly the same number of elements as the original  Bigarray
498       b  .  That is, the product of the dimensions of b must be equal to i1 *
499       ... * iN .  Otherwise, Invalid_argument is raised.
500
501
502
503       val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
504
505       Specialized version of Bigarray.reshape for  reshaping  to  zero-dimen‐
506       sional arrays.
507
508
509       Since 4.05.0
510
511
512
513       val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
514
515       Specialized  version  of  Bigarray.reshape  for reshaping to one-dimen‐
516       sional arrays.
517
518
519
520       val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a,  'b,  'c)
521       Array2.t
522
523       Specialized  version  of  Bigarray.reshape  for reshaping to two-dimen‐
524       sional arrays.
525
526
527
528       val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int ->  int  ->  ('a,
529       'b, 'c) Array3.t
530
531       Specialized  version  of Bigarray.reshape for reshaping to three-dimen‐
532       sional arrays.
533
534
535
536
537
538OCamldoc                          2021-01-26                Stdlib.Bigarray(3)
Impressum