13.16 Flonum objects

Flonums are double–precision floating point numbers (8 bytes wide) implemented as specified by IEEE 754 on the hosting platform. A flonum is a fixed length memory block referenced by machine words tagged as vectors. The first machine word of a flonum block is tagged has flonum in its least significant bits and it has the most significant bits set to zero.

|------------------------|-------------| reference to flonum
      heap pointer         vector tag

|------------------------|-------------| flonum first word
   all set to zero         flonum tag

To allow for the same binary layout: a flonum memory block is 16 bytes wide on both 32-bit and 64-bit platforms; on a 32-bit platform the actual number is stored in the last two words:

   1st word     2nd word     3rd word     4th word
|------------|------------|------------|------------|
 tagged word     unused           data words
                          |.........................|
                                    flonum

on a 64-bit platform the actual number is stored in the second word:

          1st word                 2nd word
|-------------------------|-------------------------|
         tagged word               data word
                          |.........................|
                                    flonum

Basic operations

Flonums are allocated on the heap as follows:

ikpcb_t * pcb  = ik_the_pcb();
ikptr_t   s_fl;

s_fl = ik_safe_alloc(pcb, flonum_size) | vector_tag;
IK_FLONUM_TAG(s_fl) = flonum_tag;

to extract the double number we do:

ikptr_t  s_fl = the_flonum;
double   data = IK_FLONUM_DATA(s_fl);

to obtain a pointer to the data area we do:

ikptr_t   s_fl = the_flonum;
double *  data = IK_FLONUM_VOIDP(s_fl);

Preprocessor Symbol: flonum_size

The number of bytes to allocate to hold a flonum memory block.

Preprocessor Symbol: flonum_tag

The tag of ikptr_t values used as first words in bignum memory blocks.

Preprocessor Symbol: disp_flonum_tag

Displacement of secondary tag word. The number of bytes to add to an untagged pointer to flonum to get the pointer to the first byte in the word holding the flonum tag.

Preprocessor Symbol: disp_flonum_data

Displacement of data area. The number of bytes to add to an untagged pointer to flonum to get the pointer to the first byte in the data area holding the actual double value.

Preprocessor Symbol: off_flonum_tag

An integer to add to add to a tagged ikptr_t pointer to flonum to get the pointer to the first byte in the word holding the flonum tag.

Preprocessor Symbol: off_flonum_data

An integer to add to a tagged ikptr_t pointer to flonum to get the pointer to the first byte in the data area holding the actual double value.

Convenience preprocessor macros

Preprocessor Macro: int IK_IS_FLONUM (ikptr_t obj)

Return true if obj is a flonum object; otherwise return false.

Preprocessor Macro: ikptr_t IK_FLONUM_TAG (ikptr_t fl)

Evaluate to the location of the first word in a flonum block. fl must be a tagged pointer to flonum object. A use of this macro can appear both as operand or left–side of assignment.

Preprocessor Macro: double IK_FLONUM_DATA (ikptr_t fl)

Set or retrieve the floating point number; fl must be a tagged pointer to flonum object. A use of this macro can appear both as operand or left–side of assignment:

ikptr_t  s_fl = the_flonum;
double num;

IK_FLONUM_DATA(s_fl) = 1.2;
num = IK_FLONUM_DATA(s_fl);

Preprocessor Macro: void * IK_FLONUM_VOIDP (ikptr_t fl)

Evaluate to a pointer to the data area of a flonum object. fl must be a tagged pointer to flonum object.

Operations on flonums

Function: int ik_is_flonum (ikptr_t obj)

Return non–zero if obj is a flonum object; otherwise return zero.

Function: ikptr_t iku_flonum_alloc (ikpcb_t * pcb, double N)

Allocate and return a new flonum object, using ik_unsafe_alloc(), intialised with N.

Function: ikptr_t ika_flonum_from_double (ikpcb_t * pcb, double N)

Allocate and return a new flonum object, using ik_safe_alloc(), intialised with N.