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
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
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
256       array 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
259       Bigarrays.   Finally,  Bigarrays  of kind int8_unsigned_elt can also be
260       accessed as arrays of characters instead of arrays of  small  integers,
261       by 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
352       operations, 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
368       three-dimensional arrays.)  Statically knowing the number of dimensions
369       of  the  array  allows  faster  operations,  and  more  precise  static
370       type-checking.
371
372
373
374
375   Two-dimensional arrays
376       module Array2 : sig end
377
378
379       Two-dimensional arrays. The Array2 structure provides operations  simi‐
380       lar  to  those  of  Bigarray.Genarray  , but specialized to the case of
381       two-dimensional arrays.
382
383
384
385
386   Three-dimensional arrays
387       module Array3 : sig end
388
389
390       Three-dimensional arrays. The Array3 structure provides operations sim‐
391       ilar  to  those  of  Bigarray.Genarray , but specialized to the case of
392       three-dimensional arrays.
393
394
395
396
397   Coercions between generic Bigarrays and fixed-dimension Bigarrays
398       val genarray_of_array0 : ('a, 'b, 'c) Array0.t -> ('a, 'b,  'c)  Genar‐
399       ray.t
400
401       Return the generic Bigarray corresponding to the given zero-dimensional
402       Bigarray.
403
404
405       Since 4.05.0
406
407
408
409       val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b,  'c)  Genar‐
410       ray.t
411
412       Return  the generic Bigarray corresponding to the given one-dimensional
413       Bigarray.
414
415
416
417       val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b,  'c)  Genar‐
418       ray.t
419
420       Return  the generic Bigarray corresponding to the given two-dimensional
421       Bigarray.
422
423
424
425       val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b,  'c)  Genar‐
426       ray.t
427
428       Return  the  generic  Bigarray  corresponding to the given three-dimen‐
429       sional Bigarray.
430
431
432
433       val array0_of_genarray : ('a,  'b,  'c)  Genarray.t  ->  ('a,  'b,  'c)
434       Array0.t
435
436       Return the zero-dimensional Bigarray corresponding to the given generic
437       Bigarray.  Raise Invalid_argument if the generic Bigarray does not have
438       exactly zero dimension.
439
440
441       Since 4.05.0
442
443
444
445       val  array1_of_genarray  :  ('a,  'b,  'c)  Genarray.t  -> ('a, 'b, 'c)
446       Array1.t
447
448       Return the one-dimensional Bigarray corresponding to the given  generic
449       Bigarray.  Raise Invalid_argument if the generic Bigarray does not have
450       exactly one dimension.
451
452
453
454       val array2_of_genarray : ('a,  'b,  'c)  Genarray.t  ->  ('a,  'b,  'c)
455       Array2.t
456
457       Return  the two-dimensional Bigarray corresponding to the given generic
458       Bigarray.  Raise Invalid_argument if the generic Bigarray does not have
459       exactly two dimensions.
460
461
462
463       val  array3_of_genarray  :  ('a,  'b,  'c)  Genarray.t  -> ('a, 'b, 'c)
464       Array3.t
465
466       Return  the  three-dimensional  Bigarray  corresponding  to  the  given
467       generic  Bigarray.  Raise Invalid_argument if the generic Bigarray does
468       not have exactly three dimensions.
469
470
471
472
473   Re-shaping Bigarrays
474       val reshape : ('a, 'b, 'c) Genarray.t -> int  array  ->  ('a,  'b,  'c)
475       Genarray.t
476
477
478       reshape  b  [|d1;...;dN|]  converts  the Bigarray b to a N -dimensional
479       array of dimensions d1 ...  dN .  The returned array and  the  original
480       array  b  share  their  data  and  have the same layout.  For instance,
481       assuming that b is a one-dimensional array of dimension 12,  reshape  b
482       [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4.  If b
483       has C layout, the element (x,y) of b' corresponds to the element x *  3
484       +  y  of  b  .  If b has Fortran layout, the element (x,y) of b' corre‐
485       sponds to the element x + (y - 1) * 4 of b  .   The  returned  Bigarray
486       must  have exactly the same number of elements as the original Bigarray
487       b .  That is, the product of the dimensions of b must be equal to i1  *
488       ... * iN .  Otherwise, Invalid_argument is raised.
489
490
491
492       val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
493
494       Specialized  version  of  Bigarray.reshape for reshaping to zero-dimen‐
495       sional arrays.
496
497
498       Since 4.05.0
499
500
501
502       val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
503
504       Specialized version of Bigarray.reshape  for  reshaping  to  one-dimen‐
505       sional arrays.
506
507
508
509       val  reshape_2  : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
510       Array2.t
511
512       Specialized version of Bigarray.reshape  for  reshaping  to  two-dimen‐
513       sional arrays.
514
515
516
517       val  reshape_3  :  ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
518       'b, 'c) Array3.t
519
520       Specialized version of Bigarray.reshape for reshaping  to  three-dimen‐
521       sional arrays.
522
523
524
525
526
527OCamldoc                          2020-02-27                Stdlib.Bigarray(3)
Impressum