13.5 Fixnum objects

Fixnums are “small” exact integers which fit in a single machine word:

• On 32-bit platforms the word size is 4 bytes, 30 bits are used for fixnum representation:

  (greatest-fixnum)       ⇒ +536870911
  (expt 2 29)             ⇒ +536870912
  (- (expt 2 29) 1)       ⇒ +536870911
  
  (least-fixnum)          ⇒ -536870912
  (- (expt 2 29))         ⇒ -536870912
  

  the representation of a fixnum is:

   30 bits fixnum representation
        |........................|00
  
        |-----|-----|-----|------+--|
         byte3 byte2 byte1   byte0
  

  the two least significant bits are set to zero: this “tags” the machine words which embed fixnums.

• On 64-bit platforms the word size is 8 bytes, 61 bits are used for fixnum representation:

  (greatest-fixnum)       ⇒ +1152921504606846975
  (expt 2 60)             ⇒ +1152921504606846976
  (- (expt 2 60) 1)       ⇒ +1152921504606846975
  
  (least-fixnum)          ⇒ -1152921504606846976
  (- (expt 2 60))         ⇒ -1152921504606846976
  

  the representation of a fixnum is:

           61 bits fixnum representation
  |...............................................|000
  
  |-----|-----|-----|-----|-----|-----|-----|-----+---|
   byte7 byte6 byte5 byte4 byte3 byte2 byte1  byte0
  

  the three least significant bits are set to zero: this “tags” the machine words which embed fixnums.

The fixnums tag is 00 on 32-bit platforms and 000 on 64-bit platforms; given the symbols:

fx_shift

Set to the number of bits in the tag: 2 on 32-bit platforms; 3 on 64-bit platforms.

fx_scale

Set to the number of bytes in a machine word.

let’s consider a memory block whose size in bytes is an exact multiple of a word size in bytes; the value representing the memory block length is such that:

length_in_bytes = number_of_words *  fx_scale
                = number_of_words *  wordsize
                = number_of_words << fx_shift

this allows us, for example, to take the fixnum representing the number of items in a vector and, at the C language level, consider it directly as size of the vector’s data area in bytes.

Basic operations

Given an exact integer stored in a iksword_t value with the right amount of bits, we encode a fixnum as follows:

iksword_t  the_value  = ...;
ikptr_t    the_fixnum = (ikptr_t)(the_value << fx_shift);

and we decode it as follows:

ikptr_t    the_fixnum = ...;
iksword_t  the_value  = (iksword_t)(the_fixnum >> fx_shift);

to verify if a ikptr_t is a fixnum we do:

ikptr_t   the_fixnum = ...;

if (fx_tag == ((iksword_t)the_fixnum & fx_mask))
  it_is_a_fixnum();
else
  it_is_not();

it is better to use the convenience macros described below.

Macro: fx_tag 0

The fixnums tag.

Macro: fx_shift

The number of bits in the fixnums tag. It is the amount of bits to left–shift a machine word to encode its value as fixnum.

Macro: fx_mask

Bit mask used to isolate the tag bits of a fixnum.

Convenience preprocessor macros

Examples:

iksword_t  N = 123L;
ikptr_t    S = IK_FIX(N);
iksword_t  M = IK_UNFIX(S);

Preprocessor Macro: ikptr_t IK_FIX (iksword_t num)

Convert a small exact integer in the correct range for a fixnum, into a ikptr_t value. num is cast to iksword_t.

Preprocessor Macro: iksword_t IK_UNFIX (ikptr_t ref)

Convert an ikptr_t value holding a fixnum into a fixnum of type iksword_t.

Preprocessor Macro: int IK_IS_FIXNUM (ikptr_t ref)

Evaluate to true if ref is an ikptr_t embedding a fixnum. It just tests if the least significant bits in the tag are set to zero.