1 # Integers
   2 
   3 Tomo has five types of integers:
   4 
   5 - `Int`: the default integer type, which uses an efficient tagged 29-bit
   6   integer value for small numbers, and falls back to a bigint implementation
   7   when values are too large to fit in 29-bits. The bigint implementation uses
   8   the GNU MP library. These integers are fast for small numbers and guaranteed
   9   to always be correct and never overflow.
  10 - `Int8`/`Int16`/`Int32`/`Int64`: Fixed-size integers that take up `N` bits.
  11   These integers must be explicitly constructed using their type name (e.g.
  12   `Int64(5)`) and are subject to overflowing on arithmetic operations. If an
  13   overflow occurs, a runtime error will be raised.
  14 - In cases where it is possible to infer that an integer literal should be
  15   used as a fixed-size integer, the literal will be converted at compile time
  16   to the appropriate fixed-size integer type and checked to ensure that it
  17   can fit in the needed size. For example, if you declare a variable as
  18   `x := Int64(0)` and later do `x + 1`, it's inferred that the `1` is a 64-bit
  19   integer literal.
  20 
  21 Runtime conversion between integer types (casting) can be done explicitly by
  22 calling the target type as a function: `Int32(x)`. For fixed-width types, the
  23 conversion function also accepts a second parameter, `truncate`. If `truncate`
  24 is `no` (the default), conversion will create a runtime error if the value is
  25 too large to fit in the target type. If `truncate` is `yes`, then the resulting
  26 value will be a truncated form of the input value.
  27 
  28 Integers support the standard math operations (`x+y`, `x-y`, `x*y`, `x/y`) as
  29 well as powers/exponentiation (`x^y`), modulus (`x mod y` and `x mod1 y`), and
  30 bitwise operations: `x and y`, `x or y`, `x xor y`, `x << y`, `x >> y`, `x >>>
  31 y` (unsigned right shift), and `x <<< y` (unsighted left shift). The operators
  32 `and`, `or`, and `xor` are _bitwise_, not logical operators.
  33 
  34 ## Integer Literals
  35 
  36 The simplest form of integer literal is a string of digits, which is inferred
  37 to have type `Int` (unbounded size).
  38 
  39 ```tomo
  40 i := 123456789012345678901234567890
  41 ```
  42 
  43 Underscores may also be used to visually break up the integer for readability:
  44 
  45 ```tomo
  46 a_million := 1_000_000
  47 ```
  48 
  49 Hexadecimal, octal, and binary integer literals are also supported:
  50 
  51 ```tomo
  52 hex := 0x123F
  53 octal := 0o644
  54 binary := 0b10101
  55 ```
  56 
  57 For fixed-sized integers, use the type's name as a constructor:
  58 
  59 ```tomo
  60 my_int64 := Int64(12345)
  61 my_int32 := Int32(12345)
  62 my_int16 := Int32(12345)
  63 my_int8 := Int32(123)
  64 ```
  65 
  66 A compiler error will be raised if you attempt to construct a value that cannot
  67 fit in the specified integer size (e.g. `Int8(99999)`).
  68 
  69 ## A Note on Division
  70 
  71 Unlike some other languages (including C), Tomo uses a mathematically
  72 consistent definition of division called [Euclidean
  73 Division](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/divmodnote-letter.pdf)
  74 that upholds the following invariants for all inputs:
  75 
  76 ```tomo
  77 quotient := numerator / denominator
  78 remainder := numerator mod denominator
  79 
  80 # Modulus always gives a non-negative result:
  81 assert remainder >= 0
  82 
  83 # The numerator can be reconstructed sensibly:
  84 assert numerator == denominator * quotient + remainder
  85 ```
  86 
  87 Importantly, these invariants hold for both positive and negative numerators
  88 and denominators. When the numerator and denominator are both positive, you
  89 will not notice any difference from how integer division and modulus work in
  90 other programming languages. However, the behavior is a bit different when
  91 negative numbers are involved. Integer division rounds _down_ instead of
  92 rounding _towards zero_, and modulus never gives negative results:
  93 
  94 ```tomo
  95 quotient := -1 / 5
  96 assert quotient == -1
  97 
  98 remainder := -1 mod 5
  99 assert remainder == 4
 100 
 101 assert -1 == 5 * -1 + 4
 102 ```
 103 
 104 ```tomo
 105 quotient := 16 / -5
 106 assert quotient == -3
 107 
 108 remainder := -1 mod 5
 109 assert remainder == 1
 110 
 111 assert 16 == -5 * -3 + 1
 112 ```
 113 
 114 # API
 115 
 116 [API documentation](../api/integers.md)