{"id":13527080,"url":"https://github.com/tc39/proposal-number-fromstring","last_synced_at":"2025-04-19T17:35:41.574Z","repository":{"id":66007518,"uuid":"114566610","full_name":"tc39/proposal-number-fromstring","owner":"tc39","description":"{BigInt,Number}.fromString(string, radix)","archived":false,"fork":false,"pushed_at":"2019-01-11T13:51:46.000Z","size":22,"stargazers_count":65,"open_issues_count":11,"forks_count":7,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-12T21:15:06.510Z","etag":null,"topics":["ecmascript"],"latest_commit_sha":null,"homepage":"https://mathiasbynens.github.io/proposal-number-fromstring/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tc39.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-12-17T20:33:01.000Z","updated_at":"2024-07-01T15:09:28.000Z","dependencies_parsed_at":"2023-02-28T23:30:42.663Z","dependency_job_id":null,"html_url":"https://github.com/tc39/proposal-number-fromstring","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-number-fromstring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-number-fromstring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-number-fromstring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-number-fromstring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tc39","download_url":"https://codeload.github.com/tc39/proposal-number-fromstring/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246174509,"owners_count":20735413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ecmascript"],"created_at":"2024-08-01T06:01:40.544Z","updated_at":"2025-03-30T23:32:48.697Z","avatar_url":"https://github.com/tc39.png","language":"HTML","readme":"# ECMAScript proposal: `{BigInt,Number}.fromString`\n\n## Status\n\nThis proposal is at stage 1 of [the TC39 process](https://tc39.github.io/process-document/).\n\n## Background\n\n[The `BigInt` proposal](https://github.com/tc39/proposal-bigint) initially included a static `BigInt.parseInt` method. After [some discussion](https://github.com/tc39/proposal-bigint/issues/86), it was [removed](https://github.com/tc39/proposal-bigint/commit/30b5594c30bdf7973323d61504017933673df283) in favor of a separate proposal to add a static `fromString` method to both `BigInt` and `Number`. This is that proposal.\n\n## Motivation\n\n`{BigInt,Number}.prototype.toString(radix)` enables converting a numeric value into a string representation of that value. For `BigInt`s specifically, there is currently no built-in way to do the inverse, i.e. to turn a string representation of a `BigInt` with a given radix back into a `BigInt`.\n\nFor `Number` values, there is [`parseInt(string, radix = 10)`](https://tc39.github.io/ecma262/#sec-parseint-string-radix) and [`Number.parseInt(string, radix = 10)`](https://tc39.github.io/ecma262/#sec-number.parseint), but its behavior is suboptimal:\n\n- It returns `NaN` instead of throwing a `SyntaxError` exception when `string` does not represent a number.\n- It returns `NaN` instead of throwing a `RangeError` exception when `radix` is not valid (i.e. `radix !== 0 \u0026\u0026 radix \u003c 2` or `radix \u003e 36`).\n- It accepts radix `0`, treating it as `10` instead, which does not make sense.\n- It ignores leading whitespace and trailing non-digit characters.\n- It supports hexadecimal integer literal prefixes `0x` and `0X` but lacks support for octal integer literal prefixes `0o` and `0O` or binary integer literal prefixes `0b` and `0B`, which is inconsistent.\n- The fact that `parseInt` has some level of support for integer literal prefixes means that it’s not a clear counterpart to `toString`.\n\n## Proposed solution\n\nWe propose extending both `BigInt` and `Number` with a new static `fromString(string, radix = 10)` method which acts as the inverse of `{BigInt,Number}.prototype.toString(radix = 10)`. It accepts only strings that can be produced by `{BigInt,Number}.prototype.toString(radix = 10)`, and throws an exception for any other input.\n\n## High-level API\n\n```js\nNumber.fromString('42');\n// → 42\nNumber.fromString('42', 10);\n// → 42\n\nBigInt.fromString('42');\n// → 42n\nBigInt.fromString('42', 10);\n// → 42n\n```\n\n## Illustrative examples\n\nThe following examples use `Number.fromString`. The semantics for `BigInt.fromString` are identical except it returns a `BigInt` rather than a `Number`.\n\nUnlike `parseInt`, `fromString` intentionally lacks special handling for integer literal prefixes.\n\n```js\nNumber.parseInt('0xc0ffee');\n// → 12648430\nNumber.parseInt('0o755');\n// → 0\nNumber.parseInt('0b00101010');\n// → 0\n\nNumber.fromString('0xc0ffee');\n// → SyntaxError\nNumber.fromString('0o755');\n// → SyntaxError\nNumber.fromString('0b00101010');\n// → SyntaxError\n\nNumber.fromString('C0FFEE', 16);\n// → SyntaxError (toString produces lowercase digits)\nNumber.fromString('c0ffee', 16);\n// → 12648430 === 0xc0ffee\nNumber.fromString('755', 8);\n// → 493 === 0o755\nNumber.fromString('00101010', 2);\n// → 42 === 0b00101010\n```\n\nUnlike `parseInt`, `fromString` throws a `SyntaxError` exception when `string` does not represent a number.\n\n```js\nNumber.parseInt('');\n// → NaN\nNumber.parseInt(' \\n ');\n// → NaN\nNumber.parseInt('x');\n// → NaN\n\nNumber.fromString('');\n// → SyntaxError\nNumber.fromString(' \\n ');\n// → SyntaxError\nNumber.fromString('x');\n// → SyntaxError\n```\n\nUnlike `parseInt`, `fromString` throws a `RangeError` exception when `radix \u003c 2` or `radix \u003e 36`.\n\n```js\nNumber.parseInt('1234', 0);\n// → 1234\nNumber.parseInt('1234', 1);\n// → NaN\nNumber.parseInt('1234', 37);\n// → NaN\n\nNumber.fromString('1234', 0);\n// → RangeError\nNumber.fromString('1234', 1);\n// → RangeError\nNumber.fromString('1234', 37);\n// → RangeError\n```\n\nUnlike `parseInt`, `fromString` throws a `TypeError` exception when `string` is not a string.\n\n```js\nNumber.parseInt(true, 32);\n// → 978894\n\nNumber.fromString(true, 32);\n// → TypeError\n```\n\n### FAQ\n\n#### What about legacy octal integers?\n\n`fromString` intentionally lacks special handling for legacy octal integer literals, i.e. those without the explicit `0o` or `0O` prefix such as `010`. In other words, `Number.fromString('010')` throws a `SyntaxError` exception.\n\n#### What about numeric separators?\n\n`fromString` does not need to support [numeric separators](https://github.com/tc39/proposal-numeric-separator), as they cannot occur in `{BigInt,Number}.prototype.toString(radix)` output. `Number.fromString('1_000_000_000')` throws a `SyntaxError` exception.\n\n#### Does `BigInt.fromString(string)` support the `n` suffix?\n\n`BigInt.fromString` does not need to support the `n` suffix used for `BigInt` literals, as it doesn’t occur in `BigInt.prototype.toString(radix)` output. Furthermore, supporting it would introduce an ambiguity for radices where `n` is a valid digit: should `BigInt.fromString('1n', 32)` return `1` or `55`? With the current proposal, `BigInt.fromString('1n', 32)` returns `55`, and `BigInt.fromString('1n')` throws a `SyntaxError` exception.\n\n## Specification\n\n* [Ecmarkup source](https://github.com/mathiasbynens/proposal-number-fromstring/blob/master/spec.html)\n* [HTML version](https://mathiasbynens.github.io/proposal-number-fromstring/)\n\n## Implementations\n\n* none yet\n","funding_links":[],"categories":["HTML"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftc39%2Fproposal-number-fromstring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftc39%2Fproposal-number-fromstring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftc39%2Fproposal-number-fromstring/lists"}