1 # Nums
   2 
   3 Tomo has two floating point number types: `Num` (64-bit, AKA `double`) and
   4 `Num32` (32-bit, AKA `float`). Num literals can have a decimal point (e.g.
   5 `5.`), a scientific notation suffix (e.g. `1e8`) or a percent sign. Numbers
   6 that end in a percent sign are divided by 100 at compile time (i.e. `5% ==
   7 0.05`). Numbers can also use the `deg` suffix to represent degrees, which
   8 are converted to radians at compile time (i.e. `180deg == Nums.PI`).
   9 
  10 Nums support the standard math operations (`x+y`, `x-y`, `x*y`, `x/y`) as well as
  11 powers/exponentiation (`x^y`) and modulus (`x mod y` and `x mod1 y`).
  12 
  13 32-bit numbers can be constructed using the type name: `Num32(123.456)`.
  14 
  15 ## NaN
  16 
  17 IEEE-754 floating point numbers define a concept call `NaN` (Not a Number),
  18 which is the result value used to signal various operations (e.g. `0/0`) that
  19 have no mathematically defined result value. NaNs are implemented at the
  20 hardware level and propagate through floating point operations. This allows you
  21 to perform many chained operations on the assumption that it's unlikely to have
  22 NaN values, and only perform checks at the end of the chain of operations,
  23 instead of performing checks after each operation. Unfortunately, it's also
  24 easy to forget to perform any checks at all because most type systems don't
  25 differentiate between possibly-NaN values and definitely-not-NaN values.
  26 
  27 Tomo has a separate concept for expressing the lack of a defined value:
  28 optional types. Consequently, Tomo has merged these two concepts, so `NaN` is
  29 called `none` and has the type `Num?` or `Num32?`. In this way, it's no
  30 different from optional integers or optional lists. This means that if a
  31 variable has type `Num`, it is guaranteed to not hold a NaN value. This also
  32 means that operations which may produce NaN values have a result type of
  33 `Num?`. For example, division can take two non-NaN values and return a result
  34 that is NaN (zero divided by zero). Similarly, multiplication can produce NaN
  35 values (zero times infinity), and many math functions like `sqrt()` can return
  36 NaN for some inputs.
  37 
  38 Unfortunately, one of the big downsides of optional types is that explicit
  39 `none` handling can be very verbose. To make Nums actually usable, Tomo applies
  40 very liberal use of type coercion and implicit `none` checks when values are
  41 required to be non-none. Here are a few examples:
  42 
  43 ```tomo
  44 zero := 0.0
  45 assert zero == 0
  46 
  47 y := 1.0
  48 
  49 # Division might produce none:
  50 assert zero / y == 0
  51 assert zero / zero == none
  52 
  53 # Optional types and none values propagate:
  54 assert zero/y + 1 + 2 == 3
  55 assert zero/zero + 1 + 2 == none
  56 
  57 # Optional Nums can be handled explicitly using `or` and `!`:
  58 assert zero/zero or -123 == -123
  59 
  60 # This would raise a runtime error if `zero` and `y` were zero:
  61 assert (zero/y)! == 0
  62 
  63 # Assigning to a non-optional variable will do an implicit check for none and
  64 # raise a runtime error if the value is none, essentially the same as an
  65 # implicit `!`:
  66 zero = zero/y
  67 
  68 func doop(x:Num -> Num)
  69     # If a function's return type is non-optional and an optional value is
  70     # used in a return statement, an implicit none check will be inserted and
  71     # will error if the value is none:
  72     return zero / 2
  73 
  74 # Function arguments are also implicitly checked for none if the given value
  75 # is optional and the function needs a non-optional value:
  76 assert doop(zero/y) == 0
  77 ```
  78 
  79 Hopefully the end result of this system is one where users can take advantage
  80 of the performance benefits of hardware NaN propagation, while still having the
  81 compiler enforce checking for undefined values. Users who don't want automatic
  82 NaN-checking can use optional types and explicit checks where necessary. By
  83 default, automatic NaN-checking happens at interface boundaries (function
  84 arguments, return values, and variable assignments), so NaN values should be
  85 caught early when an error message would have helpful context, while
  86 eliminating conditional branching inside of compound math expressions. Users
  87 should also be able to write code that can safely assume that all values
  88 provided are not NaN.
  89 
  90 # API
  91 
  92 [API documentation](../api/nums.md)