proposal-bigint

BigInt: Arbitrary precision integers in JavaScript Daniel Ehrenberg, Igalia. Stage 4 This proposal is complete and already merged into ECMA262 specification. See the specification text here. Thanks for help and feedback on this effort from Brendan Eich, Waldemar Horwat, Jaro Sevcik, Benedikt Meurer, Michael Saboff, Adam Klein, Sarah Groff-Palermo and others. Contents What Is It? How Does It Work? Syntax Example: Calculating Primes Operators Comparisons Conditionals Other API Notes Gotchas & Exceptions Interoperation with Number and String Rounding Cryptography Other Exceptions Usage Recommendations About the Proposal Motivation, Or Why Do We Need Such Big Numbers? Design Philosophy, Or Why Is This Like This? State of the Proposal What Is It? BigInt is a new primitive that provides a way to represent whole numbers larger than 253, which is the largest number Javascript can reliably represent with the Number primitive. const x = Number.MAX_SAFE_INTEGER; // ↪ 9007199254740991, this is 1 less than 2^53 const y = x + 1; // ↪ 9007199254740992, ok, checks out const z = x + 2 // ↪ 9007199254740992, wait, that’s the same as above! Learn more about how numbers are represented in Javascript in the slides from Daniel's talk at JSConfEU. How Does It Work? The following sections show BigInt in action. A number have been influenced by or taken outright from Mathias Bynens's BigInt v8 update, which includes more details than this page. Syntax A BigInt is created by appending n to the end of the integer or by calling the constructor. const theBiggestInt = 9007199254740991n; const alsoHuge = BigInt(9007199254740991); // ↪ 9007199254740991n const hugeButString = BigInt('9007199254740991'); // ↪ 9007199254740991n Example: Calculating Primes function isPrime(p) { for (let i = 2n; i * i <= p; i++) { if (p % i === 0n) return false; } return true; } // Takes a BigInt as an argument and returns a BigInt function nthPrime(nth) { let maybePrime = 2n; let prime = 0n; while (nth >= 0n) { if (isPrime(maybePrime)) { nth -= 1n; prime = maybePrime; } maybePrime += 1n; } return prime; } Operators You can use +, *, -, ** and % with BigInts, just like with Numbers. const previousMaxSafe = BigInt(Number.MAX_SAFE_INTEGER); // ↪ 9007199254740991 const maxPlusOne = previousMaxSafe + 1n; // ↪ 9007199254740992n const theFuture = previousMaxSafe + 2n; // ↪ 9007199254740993n, this works now! const multi = previousMaxSafe * 2n; // ↪ 18014398509481982n const subtr = multi – 10n; // ↪ 18014398509481972n const mod = multi % 10n; // ↪ 2n const bigN = 2n ** 54n; // ↪ 18014398509481984n bigN * -1n // ↪ –18014398509481984n The / operator also work as expected with whole numbers. However, since these are BigInts and not BigDecimals, this operation will round towards 0, which is to say, it will not return any fractional digits. const expected = 4n / 2n; // ↪ 2n const rounded = 5n / 2n; // ↪ 2n, not 2.5n See the advanced documentation for use with bitwise operators. Comparisons A BigInt is not strictly equal to a Number, but it is loosely so. 0n === 0 // ↪ false 0n == 0 // ↪ true Numbers and BigInts may be compared as usual. 1n < 2 // ↪ true 2n > 1 // ↪ true 2 > 2 // ↪ false 2n > 2 // ↪ false 2n >= 2 // ↪ true They may be mixed in arrays and sorted. const mixed = [4n, 6, -12n, 10, 4, 0, 0n]; // ↪  [4n, 6, -12n, 10, 4, 0, 0n] mixed.sort(); // ↪ [-12n, 0, 0n, 10, 4n, 4, 6] Conditionals A BigInt behaves like a Number in cases where it is converted to a Boolean: if, ||, &&, Boolean, !. if (0n) { console.log('Hello from the if!'); } else { console.log('Hello from the else!'); } // ↪ "Hello from the else!" 0n || 12n // ↪ 12n 0n && 12n // ↪ 0n Boolean(0n) // ↪ false Boolean(12n) // ↪ true !12n // ↪ false !0n // ↪ true Other API Notes BigInts may also be used in BigInt64Array and BigUint64Array typed arrays for 64-bit integers. const view = new BigInt64Array(4); // ↪ [0n, 0n, 0n, 0n] view.length; // ↪ 4 view[0]; // ↪ 0n view[0] = 42n; view[0]; // ↪ 42n // Highest possible BigInt value that can be represented as a // signed 64-bit integer. const max = 2n ** (64n - 1n) - 1n; view[0] = max; view[0]; // ↪ 9_223_372_036_854_775_807n view[0] = max + 1n; view[0]; // ↪ -9_223_372_036_854_775_808n // ^ negative because of overflow For more about BigInt library functions, see the advanced section. Gotchas & Exceptions Interoperation with Number and String The biggest surprise may be that BigInts cannot be operated on interchangeably with Numbers. Instead a TypeError will be thrown. (Read the design philosophy for more about why this decision was made.) 1n + 2 // ↪ TypeError: Cannot mix BigInt and other types, use explicit conversions 1n * 2 // ↪ TypeError: Cannot mix BigInt and other types, use explicit conversions BigInts also cannot be converted to Numbers using the unary +. Number must be used. +1n // ↪ TypeError: Cannot convert a BigInt value to a number Number(1n) // ↪ 1 The BigInt can however be concatenated with a String. 1n + '2' // ↪ "12" '2' + 1n // ↪ "21" For this reason, it is recommended to continue using Number for code which will only encounter values under 253. Reserve BigInt for cases where large values are expected. Otherwise, by converting back and forth, you may lose the very precision you are hoping to preserve. const largeFriend = 900719925474099267n; const alsoLarge = largeFriend + 2n; const sendMeTheBiggest = (n, m) => Math.max(Number(n), Number(m)); sendMeTheBiggest(largeFriend, alsoLarge) // ↪900719925474099300 // This is neither argument! Reserve Number values for cases when they are integers up to 253, for other cases, using a string (or a BigInt literal) would be advisable to not lose precision. const badPrecision = BigInt(9007199254740993); // ↪9007199254740992n const goodPrecision = BigInt('9007199254740993'); // ↪9007199254740993n const alsoGoodPrecision = 9007199254740993n; // ↪9007199254740993n Rounding As noted above, the B