[SR-16066] dividingFullWidth preconditions not clearly documented

[dabrahams]

Previous ID	SR-16066
Radar	None
Original Reporter	@dabrahams
Type	Bug

Additional Detail from JIRA

Votes	0
Component/s	Standard Library
Labels	Bug
Assignee	None
Priority	Medium

md5: d0cfa803a636a5b8dc72870f5d9b7cb9

Issue Description:

The resulting quotient must be representable within the bounds of the type. If the quotient of dividing dividend by this value is too large to represent in the type, a runtime error may occur.

"Runtime error" in Swift would naturally imply a thrown Error, but in fact what happens is that this function traps… and “may” suggests that it will only trap sometimes. Representability should be stated as a precondition; it's not acceptable that this supposedly-safe function has unspecified behavior in case of an unrepresentable result. In fact, it's not really clear what the result of

(0 as Int).dividingFullWidth((high: 0, low: 0))

should be; in math, there is no resulting quotient for 0/0. In fact, AFAICT aside from divisions by zero, there is only one other division that should trap due to non-representability,

(-1).dividingFullWidth((high: .min, low: .min))

which is the double-width version of:

Int.min / -1
expression failed to parse:
error: repl.swift:10:9: error: division '-9223372036854775808 / -1' results in an overflow
Int.min / -1
        ^

But of course that one does not trap. Looks like a different bug report…