18.4 Operations on values

18.4.1. Kind tests
18.4.2. Operations on integers
18.4.3. Accessing blocks
18.4.4. Allocating blocks
18.4.5. Raising exceptions

18.4.1 Kind tests

  • Is_long(v) is true if value v is an immediate integer, false otherwise
  • Is_block(v) is true if value v is a pointer to a block, and false if it is an immediate integer.

18.4.2 Operations on integers

  • Val_long(l) returns the value encoding the long int l.
  • Long_val(v) returns the long int encoded in value v.
  • Val_int(i) returns the value encoding the int i.
  • Int_val(v) returns the int encoded in value v.
  • Val_bool(x) returns the Caml boolean representing the truth value of the C integer x.
  • Bool_val(v) returns 0 if v is the Caml boolean false, 1 if v is true.
  • Val_true, Val_false represent the Caml booleans true and false.

18.4.3 Accessing blocks

  • Wosize_val(v) returns the size of the block v, in words, excluding the header.
  • Tag_val(v) returns the tag of the block v.
  • Field(v, n) returns the value contained in the n^th field of the structured block v. Fields are numbered from 0 to Wosize_val(v)-1.
  • Store_field(b, n, v) stores the value v in the field number n of value b, which must be a structured block.
  • Code_val(v) returns the code part of the closure v.
  • string_length(v) returns the length (number of characters) of the string v.
  • Byte(v, n) returns the n^th character of the string v, with type char.

Characters are numbered from 0 to string_length(v)-1.

  • Byte_u(v, n) returns the n^th character of the string v, with type unsigned char. Characters are numbered from 0 to string_length(v)-1.
  • String_val(v) returns a pointer to the first byte of the string v, with type char *. This pointer is a valid C string: there is a null character after the last character in the string. However, Caml strings can contain embedded null characters, that will confuse the usual C functions over strings.
  • Double_val(v) returns the floating-point number contained in value v, with type double.
  • Double_field(v, n) returns the n^th element of the array of floating-point numbers v (a block tagged Double_array_tag).
  • Store_double_field(v, n, d) stores the double precision floating-point number d in the n^th element of the array of floating-point numbers v.
  • Data_custom_val(v) returns a pointer to the data part of the custom block v.

This pointer has type void * and must be cast to the type of the data contained in the custom block.

  • Int32_val(v) returns the 32-bit integer contained in the int32 v.
  • Int64_val(v) returns the 64-bit integer contained in the int64 v.
  • Nativeint_val(v) returns the long integer contained in the nativeint v.

The expressions Field(v, n), Byte(v, n) and Byte_u(v, n) are valid l-values. Hence, they can be assigned to, resulting in an in-place modification of value v. Assigning directly to Field(v, n) must be done with care to avoid confusing the garbage collector (see below).

18.4.4 Allocating blocks

Simple interface

  • Atom(t) returns an "atom" (zero-sized block) with tag t. Zero-sized blocks are preallocated outside of the heap. It is incorrect to try and allocate a zero-sized block using the functions below. For instance, Atom(0) represents the empty array.
  • caml_alloc(n, t) returns a fresh block of size n with tag t. If t is less than No_scan_tag, then the fields of the block are initialized with a valid value in order to satisfy the GC constraints.
  • caml_alloc_tuple(n) returns a fresh block of size n words, with tag 0.
  • caml_alloc_string(n) returns a string value of length n characters. The string initially contains garbage.
  • caml_copy_string(s) returns a string value containing a copy of the null-terminated C string s (a char *).
  • caml_copy_double(d) returns a floating-point value initialized with the double d.
  • caml_copy_int32(i), copy_int64(i) and caml_copy_nativeint(i) return a value of Caml type int32, int64 and nativeint, respectively, initialized with the integer i.
  • caml_alloc_array(f, a) allocates an array of values, calling function f over each element of the input array a to transform it into a value. The array a is an array of pointers terminated by the null pointer. The function f receives each pointer as argument, and returns a value. The zero-tagged block returned by alloc_array(f, a) is filled with the values returned by the successive calls to f. (This function must not be used to build an array of floating-point numbers.)
  • caml_copy_string_array(p) allocates an array of strings, copied from the pointer to a string array p (a `char **'). p must be NULL-terminated.

Low-level interface

The following functions are slightly more efficient than caml_alloc, but also much more difficult to use.

From the standpoint of the allocation functions, blocks are divided according to their size as zero-sized blocks, small blocks (with size less than or equal to `Max_young_wosize'), and large blocks (with size greater than `Max_young_wosize'). The constant `Max_young_wosize' is declared in the include file mlvalues.h. It is guaranteed to be at least 64 (words), so that any block with constant size less than or equal to 64 can be assumed to be small. For blocks whose size is computed at run-time, the size must be compared against `Max_young_wosize' to determine the correct allocation procedure.

  • caml_alloc_small(n, t) returns a fresh small block of size n <= Max_young_wosize words, with tag t. If this block is a structured block (i.e. if t < No_scan_tag), then the fields of the block (initially containing garbage) must be initialized with legal values (using direct assignment to the fields of the block) before the next allocation.
  • caml_alloc_shr(n, t) returns a fresh block of size n, with tag t. The size of the block can be greater than `Max_young_wosize'. (It can also be smaller, but in this case it is more efficient to call caml_alloc_small instead of caml_alloc_shr.) If this block is a structured block (i.e. if t < No_scan_tag), then the fields of the block (initially containing garbage) must be initialized with legal values (using the initialize function described below) before the next allocation.

18.4.5 Raising exceptions

Two functions are provided to raise two standard exceptions:

  • caml_failwith(s), where s is a null-terminated C string (with type `char *'), raises exception Failure with argument s.
  • caml_invalid_argument(s), where s is a null-terminated C string (with type `char *'), raises exception Invalid_argument with argument s.

Raising arbitrary exceptions from C is more delicate: the exception identifier is dynamically allocated by the Caml program, and therefore must be communicated to the C function using the registration facility described below in section 18.7.3. Once the exception identifier is recovered in C, the following functions actually raise the exception:

  • caml_raise_constant(id) raises the exception id with no argument;
  • caml_raise_with_arg(id, v) raises the exception id with the Caml value v as argument;
  • caml_raise_with_string(id, s), where s is a null-terminated C string, raises the exception id with a copy of the C string s as argument.