This PR adds overflow to integer arithmetics, adds new language constructs to allow user
to choose where overflowing (checked) or wrapping (unchecked) semantic is desired in a given lexical scope.

It also updates the STD where unchecked semantic is required. Or at least, where specs began to fail if run with --overflow-checked.

Updates in the compiler options

There are two compiler options --overflow-checked and --overflow-unchecked to change the
default overflow policy to be used. Currently the default is --overflow-unchecked to keep the current
semantic and allow code to be updated more easily. In future versions I think the default should be --overflow-checked in favor of safety.

After building a crystal compiler you build with --overflow-checked option and run specs as follows.

$ ./bin/crystal foo.cr --overflow-checked
$ ./bin/crystal build foo.cr --overflow-checked
$ ./bin/crystal spec --overflow-checked

Updates in the language

The operations affected by the overflow policy are only +,-,* between integers.

The new language constructs are:

checked { <expr> }
unchecked { <expr> }

The type and value of the whole [un]checked { <expr> } matches the type and value of <expr> or it raise an OverflowError.

When an OverflowError is raised the location advertised by the exception is/should be the location of the operator that generate the overflow.

Lexical Scope

The intention of using a lexical scope is that it would make as easy as possible to know how the operation is performed.

When compiled with --overflow-checked,

def foo(v)
  unchecked { 
    # the * will not raise on overflow
    bar(v) * 2 
  }
end

def bar(v)
  # the + will raise on overflow
  v + 2
end

Regarding blocks the idea is the same, when compiled with --overflow-unchecked,

def bar(v)
  # all operations here would be unchecked due to default policy
  yield v
end

def foo
  checked {
    bar(127_i8) do |v| 
      # Although the block is yielded from bar, the + is
      # performed as checked since it is written lexically
      # inside a checked section
      v + 1_i8
    end
  }
  1
rescue OverflowError
  0
end

foo # => 0

Implementation details

Given that +,-,* for Int are primitives they are always inlined and the codegen stage knows what to do along the way.
It is easy to change the semantic of the operation give some context, in this case the lexical scope information.

The current behaviour and under the unchecked policy the + is translated to add IR.

def inc(v)
  v + 1
end

define i32 @"*inc<Int32>:Int32"(i32 %v) #0 {
entry:
  %0 = add i32 %v, 1
  ret i32 %0
}

Under the checked policy the + is translated to llvm.sadd.with.overflow.* a LLVM with Overflow Intrinsics.

define i32 @"*inc<Int32>:Int32"(i32 %v) #0 {
entry:
  %0 = call { i32, i1 } @llvm.sadd.with.overflow.i32(i32 %v, i32 1)
  %1 = extractvalue { i32, i1 } %0, 0
  %2 = extractvalue { i32, i1 } %0, 1
  br i1 %2, label %overflow, label %normal

overflow:                                         ; preds = %entry
  %3 = call %OverflowError* @"*OverflowError::new:OverflowError"()
  call void @"*raise<OverflowError>:NoReturn"(%OverflowError* %3)
  unreachable

normal:                                           ; preds = %entry
  ret i32 %1
}

Note: In both situations when the operands do not belong to the same type some expansion, truncation and additional checks for overflow are done. This is because the operation is carried on the "bigger" type, and the result is always translated to the type of the left operand. This is the current semantic.

Limitations of the scopes

While developing the feature I came across two operations that would be nice to overflow along with +,-,*.

1. Int#**(exponent : Int)
2. Int#-()

This operation are not primitives as the others, but they are operators. I think it would be nicer if their overflow semantic is changed together with the current overflow scope policy.

Maybe for now, Int#**(exponent : Int) got its counterpart Int#unchecked_pow(exponent : Int) since the former will match the compiler policy that will eventually be checked.

The second one was used in one single place
as -info.value.to_{{method}} and changed to unchecked { 0.to_{{method}} - info.value.to_{{method}} }.

These two cases are methods and they are not inlined, so the mechanism described in "Implementation details" does not longer apply.

If we want them to be affected by the overflow policy the possible paths to go are:

1. Make them @[AlwaysInline] and make the inline methods be affected by the policy.
2. Add another annotation to specify the method is affected by the overflow policy. If not inlined then the code gen should make the call to the checked or the unchecked version directly.

Inlining the ** might not be that nice since it's ~10 lines and used it in many places. Adding the annotation seems a bit to much for a first round.

Another usage of forwarding the policy to other methods I can imagine is for example in matrix operations: If * is to be applied between matrices or matrix-scalar the user might have fine-grained control beyond the global policy (--overflow-[un]checked). But I found that either the packages always wrap silently or use floats.

So, all in all, up to here the only real candidate was **, hence the unchecked_pow method.

Standard Library changes

As a migration technique a temporal macro __next_unchecked is added and should be replaced with unchecked on the release after merge.

These changes are marked as Random: Mark required unchecked code blocks or different std-lib sections. All of these change can be changed later specially Time and JSON. They are focused of keeping the current behavior mostly. In the case of Time, there was some manual overflow check.

All of these changes were pushed due to existing specs that failed otherwise.

Pending

• Add [un]checked do; end notation also. I like that { } fits better to be used inside expressions.
• Overflow on type casts (eg: 256.to_u8 should raise in checked context)
• Fix/Test some cases of variables shadowing if they are first declared in a [un]checked scope
• Fix/Test lexical scope and anonymous functions declaration
• Formatter (Same rules as method, but with the OverflowCheckScope ast node)
• Track highlighters to add the new keywords

Feedback is welcome