Change documentation of modInverse to not specify error thrown.

Change documentation of modInverse to not specify error thrown.

R=ricow@google.com, sgjesse@google.com

Committed: https://github.com/dart-lang/sdk/commit/3300a005f28426adaa1f5b44415a82e644ee237d

[Lasse Reichstein Nielsen, 2015-06-24 09:03:28]

lrn@google.com changed reviewers:
+ ricow@google.com, sgjesse@google.com

[Lasse Reichstein Nielsen, 2015-06-24 09:03:28]

lrn@google.com changed required reviewers:
+ sgjesse@google.com

[Søren Gjesse, 2015-06-24 09:03:54]

lgtm

[ricow1, 2015-06-24 09:04:21]

lgtm

[Lasse Reichstein Nielsen, 2015-06-24 09:04:32]

Committed patchset #1 (id:1) manually as
3300a005f28426adaa1f5b44415a82e644ee237d (presubmit successful).

[regis, 2015-06-24 18:29:54]

regis@google.com changed reviewers:
+ regis@google.com

[regis, 2015-06-24 18:29:54]

DBC

https://codereview.chromium.org/1204993002/diff/1/sdk/lib/core/int.dart
File sdk/lib/core/int.dart (right):

https://codereview.chromium.org/1204993002/diff/1/sdk/lib/core/int.dart#newco...
sdk/lib/core/int.dart:91: * It is an error of [shiftAmount] is negative.
of -> if

https://codereview.chromium.org/1204993002/diff/1/sdk/lib/core/int.dart#newco...
sdk/lib/core/int.dart:102: * It is an error of [shiftAmount] is negative.
of -> if

https://codereview.chromium.org/1204993002/diff/1/sdk/lib/core/int.dart#newco...
sdk/lib/core/int.dart:119: * Throws if no modular inverse exists.
For consistency, "It is an error if ..." would have been better.

[Lasse Reichstein Nielsen, 2015-06-30 12:39:15]

https://codereview.chromium.org/1204993002/diff/1/sdk/lib/core/int.dart
File sdk/lib/core/int.dart (right):

https://codereview.chromium.org/1204993002/diff/1/sdk/lib/core/int.dart#newco...
sdk/lib/core/int.dart:119: * Throws if no modular inverse exists.
True.
I haven't yet decided on whether it should be documented which error it throws
in this case. It's not generally something the user can detect before calling,
so they need to catch the error. For that reason we might want to specify which
error object is thrown.
The actual error would probably be UnsupportedError (ArgumentError could be
argued, but it's not that the argument is bad, it just that there is no solution
to the question you are asking, RangeError doesn't fit). Maybe we should even
have an ArithmeticException - because its something the user will want to catch,
so it should be an exception.

Or we could just return 0, which is never a valid inverse.

[regis, 2015-06-30 16:50:39]

On 2015/06/30 12:39:15, Lasse Reichstein Nielsen wrote:
> https://codereview.chromium.org/1204993002/diff/1/sdk/lib/core/int.dart
> File sdk/lib/core/int.dart (right):
> 
>
https://codereview.chromium.org/1204993002/diff/1/sdk/lib/core/int.dart#newco...
> sdk/lib/core/int.dart:119: * Throws if no modular inverse exists.
> True.
> I haven't yet decided on whether it should be documented which error it throws
> in this case. It's not generally something the user can detect before calling,
> so they need to catch the error. For that reason we might want to specify
which
> error object is thrown.

It is why I had specified RangeError (a bad choice of exception) in the
description.

> The actual error would probably be UnsupportedError (ArgumentError could be
> argued, but it's not that the argument is bad, it just that there is no
solution
> to the question you are asking, RangeError doesn't fit). Maybe we should even
> have an ArithmeticException - because its something the user will want to
catch,
> so it should be an exception.
> 
> Or we could just return 0, which is never a valid inverse.

As I mentioned elsewhere, 0 is a valid answer:
x.modInverse(1) = 0 for any x, because x*0 mod 1 == 1.

But -1 would work. I'd still prefer throwing an exception.