Merge in JSNumber changes.

tool/input_sdk/lib/core/int.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.core;
 
 /**
  * An arbitrarily large integer.
  *
  * **Note:** When compiling to JavaScript, integers are
@@ skipping 70 matching lines @@
   /**
    * Shift the bits of this integer to the left by [shiftAmount].
    *
    * Shifting to the left makes the number larger, effectively multiplying
    * the number by `pow(2, shiftIndex)`.
    *
    * There is no limit on the size of the result. It may be relevant to
    * limit intermediate values by using the "and" operator with a suitable
    * mask.
    *
-   * It is an error of [shiftAmount] is negative.
+   * It is an error if [shiftAmount] is negative.
    */
   int operator <<(int shiftAmount);
 
   /**
    * Shift the bits of this integer to the right by [shiftAmount].
    *
    * Shifting to the right makes the number smaller and drops the least
    * significant bits, effectively doing an integer division by
    *`pow(2, shiftIndex)`.
    *
-   * It is an error of [shiftAmount] is negative.
+   * It is an error if [shiftAmount] is negative.
    */
   int operator >>(int shiftAmount);
 
+  /**
+   * Returns this integer to the power of [exponent] modulo [modulus].
+   *
+   * The [exponent] must be non-negative and [modulus] must be
+   * positive.
+   */
+  int modPow(int exponent, int modulus);
+
+  /**
+   * Returns the modular multiplicative inverse of this integer
+   * modulo [modulus].
+   *
+   * The [modulus] must be positive.
+   *
+   * It is an error if no modular inverse exists.
+   */
+  int modInverse(int modulus);
+
+  /**
+   * Returns the greatest common divisor of this integer and [other].
+   *
+   * If either number is non-zero, the result is the numerically greatest
+   * integer dividing both `this` and `other`.
+   *
+   * The greatest common divisor is independent of the order,
+   * so `x.gcd(y)` is  always the same as `y.gcd(x)`.
+   *
+   * For any integer `x`, `x.gcd(x)` is `x.abs()`.
+   *
+   * If both `this` and `other` is zero, the result is also zero.
+   */
+  int gcd(int other);
+
   /** Returns true if and only if this integer is even. */
   bool get isEven;
 
   /** Returns true if and only if this integer is odd. */
   bool get isOdd;
 
   /**
    * Returns the minimum number of bits required to store this integer.
    *
    * The number of bits excludes the sign bit, which gives the natural length
@@ skipping 14 matching lines @@
    *      (-3).bitLength == 2;  // 11111101
    *      (-4).bitLength == 2;  // 11111100
    */
   int get bitLength;
 
   /**
    * Returns the least significant [width] bits of this integer as a
    * non-negative number (i.e. unsigned representation).  The returned value has
    * zeros in all bit positions higher than [width].
    *
-   *     (-1).toUnsigned(5) == 32   // 11111111  ->  00011111
+   *     (-1).toUnsigned(5) == 31   // 11111111  ->  00011111
    *
    * This operation can be used to simulate arithmetic from low level languages.
    * For example, to increment an 8 bit quantity:
    *
    *     q = (q + 1).toUnsigned(8);
    *
    * `q` will count from `0` up to `255` and then wrap around to `0`.
    *
    * If the input fits in [width] bits without truncation, the result is the
    * same as the input.  The minimum width needed to avoid truncation of `x` is
@@ skipping 83 matching lines @@
    * The returned string is parsable by [parse].
    * For any `int` [:i:], it is guaranteed that
    * [:i == int.parse(i.toString()):].
    */
   String toString();
 
   /**
    * Converts [this] to a string representation in the given [radix].
    *
    * In the string representation, lower-case letters are used for digits above
-   * '9'.
+   * '9', with 'a' being 10 an 'z' being 35.
    *
    * The [radix] argument must be an integer in the range 2 to 36.
    */
   String toRadixString(int radix);
 
   /**
-   * Parse [source] as an integer literal and return its value.
-   *
-   * The [radix] must be in the range 2..36. The digits used are
-   * first the decimal digits 0..9, and then the letters 'a'..'z'.
-   * Accepts capital letters as well.
-   *
-   * If no [radix] is given then it defaults to 10, unless the string starts
-   * with "0x", "-0x" or "+0x", in which case the radix is set to 16 and the
-   * "0x" is ignored.
+   * Parse [source] as a, possibly signed, integer literal and return its value.
    *
    * The [source] must be a non-empty sequence of base-[radix] digits,
    * optionally prefixed with a minus or plus sign ('-' or '+').
    *
-   * It must always be the case for an int [:n:] and radix [:r:] that
+   * The [radix] must be in the range 2..36. The digits used are
+   * first the decimal digits 0..9, and then the letters 'a'..'z' with
+   * values 10 through 35. Also accepts upper-case letters with the same
+   * values as the lower-case ones.
+   *
+   * If no [radix] is given then it defaults to 10. In this case, the [source]
+   * digits may also start with `0x`, in which case the number is interpreted
+   * as a hexadecimal literal, which effectively means that the `0x` is ignored
+   * and the radix is instead set to 16.
+   *
+   * For any int [:n:] and radix [:r:], it is guaranteed that
    * [:n == int.parse(n.toRadixString(r), radix: r):].
    *
    * If the [source] is not a valid integer literal, optionally prefixed by a
    * sign, the [onError] is called with the [source] as argument, and its return
    * value is used instead. If no [onError] is provided, a [FormatException]
    * is thrown.
    *
+   * The [onError] handler can be chosen to return `null`.  This is preferable
+   * to to throwing and then immediately catching the [FormatException].
+   * Example:
+   *
+   *     var value = int.parse(text, onError: (source) => null);
+   *     if (value == null) ... handle the problem
+   *
    * The [onError] function is only invoked if [source] is a [String]. It is
    * not invoked if the [source] is, for example, `null`.
    */
   external static int parse(String source,
                             { int radix,
                               int onError(String source) });
 }