Previous Up Next
Chapter 29 The bigarray library

The bigarray library implements large, multi-dimensional, numerical arrays. These arrays are called ``big arrays'' to distinguish them from the standard Caml arrays described in Module Array. The main differences between ``big arrays'' and standard Caml arrays are as follows: Programs that use the bigarray library must be linked as follows:
        ocamlc other options bigarray.cma other files
        ocamlopt other options bigarray.cmxa other files
For interactive use of the bigarray library, do:
        ocamlmktop -o mytop bigarray.cma
or (if dynamic linking of C libraries is supported on your platform), start ocaml and type #load "bigarray.cma";;.

29.1 Module Bigarray: large, multi-dimensional, numerical arrays

Module Bigarray

29.2 Big arrays in the Caml-C interface

C stub code that interface C or Fortran code with Caml code, as described in chapter 18, can exploit big arrays as follows.

29.2.1 Include file

The include file <caml/bigarray.h> must be included in the C stub file. It declares the functions, constants and macros discussed below.

29.2.2 Accessing a Caml bigarray from C or Fortran

If v is a Caml value representing a big array, the expression Data_bigarray_val(v) returns a pointer to the data part of the array. This pointer is of type void * and can be cast to the appropriate C type for the array (e.g. double [], char [][10], etc).

Various characteristics of the Caml big array can be consulted from C as follows:
C expression Returns
Bigarray_val(v)->num_dims number of dimensions
Bigarray_val(v)->dim[i] i-th dimension
Bigarray_val(v)->flags & BIGARRAY_KIND_MASK kind of array elements

The kind of array elements is one of the following constants:
Constant Element kind
BIGARRAY_FLOAT32 32-bit single-precision floats
BIGARRAY_FLOAT64 64-bit double-precision floats
BIGARRAY_SINT8 8-bit signed integers
BIGARRAY_UINT8 8-bit unsigned integers
BIGARRAY_SINT16 16-bit signed integers
BIGARRAY_UINT16 16-bit unsigned integers
BIGARRAY_INT32 32-bit signed integers
BIGARRAY_INT64 64-bit signed integers
BIGARRAY_CAML_INT 31- or 63-bit signed integers
BIGARRAY_NATIVE_INT 32- or 64-bit (platform-native) integers

The following example shows the passing of a two-dimensional big array to a C function and a Fortran function.
    extern void my_c_function(double * data, int dimx, int dimy);
    extern void my_fortran_function_(double * data, int * dimx, int * dimy);

    value caml_stub(value bigarray)
      int dimx = Bigarray_val(bigarray)->dim[0];
      int dimy = Bigarray_val(bigarray)->dim[1];
      /* C passes scalar parameters by value */
      my_c_function(Data_bigarray_val(bigarray), dimx, dimy);
      /* Fortran passes all parameters by reference */
      my_fortran_function_(Data_bigarray_val(bigarray), &dimx, &dimy);
      return Val_unit;
29.2.3 Wrapping a C or Fortran array as a Caml big array

A pointer p to an already-allocated C or Fortran array can be wrapped and returned to Caml as a big array using the alloc_bigarray or alloc_bigarray_dims functions. The following example illustrates how statically-allocated C and Fortran arrays can be made available to Caml.
    extern long my_c_array[100][200];
    extern float my_fortran_array_[300][400];

    value caml_get_c_array(value unit)
      long dims[2];
      dims[0] = 100; dims[1] = 200;
      return alloc_bigarray(BIGARRAY_NATIVEINT | BIGARRAY_C_LAYOUT,
                            2, my_c_array, dims);

    value caml_get_fortran_array(value unit)
      return alloc_bigarray_dims(BIGARRAY_FLOAT32 | BIGARRAY_FORTRAN_LAYOUT,
                                 2, my_fortran_array_, 300L, 400L);

Previous Up Next