{"id":16916311,"url":"https://github.com/joshuawise/integer","last_synced_at":"2025-03-22T10:32:45.734Z","repository":{"id":57139202,"uuid":"92960677","full_name":"JoshuaWise/integer","owner":"JoshuaWise","description":"Native 64-bit integers with overflow protection.","archived":false,"fork":false,"pushed_at":"2020-04-21T23:11:28.000Z","size":115,"stargazers_count":19,"open_issues_count":2,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-02T02:25:37.364Z","etag":null,"topics":["64-bit","integer","native"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JoshuaWise.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-31T15:27:58.000Z","updated_at":"2023-12-07T07:11:07.000Z","dependencies_parsed_at":"2022-09-04T17:01:44.420Z","dependency_job_id":null,"html_url":"https://github.com/JoshuaWise/integer","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoshuaWise%2Finteger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoshuaWise%2Finteger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoshuaWise%2Finteger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoshuaWise%2Finteger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JoshuaWise","download_url":"https://codeload.github.com/JoshuaWise/integer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244944418,"owners_count":20536290,"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":["64-bit","integer","native"],"created_at":"2024-10-13T19:26:19.936Z","updated_at":"2025-03-22T10:32:45.463Z","avatar_url":"https://github.com/JoshuaWise.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# integer [![Build Status](https://travis-ci.org/JoshuaWise/integer.svg?branch=master)](https://travis-ci.org/JoshuaWise/integer)\n\nNative 64-bit signed integers in Node.js.\n\n- All standard operators (arithmetic, bitwise, logical)\n- Protection from overflow and unsafe numbers\n- Always immutable\n- Other useful utilities\n\n## Installation\n\n```bash\nnpm install --save integer\n```\n\n\u003e You must be using Node.js v10 or above. Prebuilt binaries are available for [LTS versions](https://nodejs.org/en/about/releases/) + Linux/OSX.\n\n## Usage\n\n```js\nvar Integer = require('integer');\n\nvar a = Integer('7129837312139827189');\nvar b = a.subtract(1).shiftRight(3);\nassert(b.equals('891229664017478398'));\n```\n\n## Overflow protection\n\nWe will not let you perform operations that would result in overflow. If you try to create an `Integer` that cannot be represented in 64-bits (signed), we will throw a `RangeError`.\n\n```js\n// These will each throw a RangeError\nvar tooBig = Integer(13897283129).multiply(13897283129);\nvar tooSmall = Integer.MIN_VALUE.subtract(1);\nvar divideByZero = Integer(123).divide(0);\nvar alsoTooBig = Integer('4029384203948203948923');\n\n// You are also protected against two's complement overflow (this will throw a RangeError)\nvar twosComplement = Integer.MIN_VALUE.divide(-1);\n```\n\n## Unsafe number protection\n\nIt's easy to convert between me and regular JavaScript numbers.\n\n```js\nvar int = Integer(12345);\nassert(int instanceof Integer);\n\nvar num = Number(int); // same as int.toNumber()\nassert(typeof num === 'number');\n```\n\nHowever, we will prevent you from converting an `Integer` to an unsafe number, and vice-versa. To learn more about unsafe numbers, [click here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger).\n\n```js\n// This will throw a RangeError\nvar unsafe = Integer(Number.MAX_SAFE_INTEGER + 1);\n\n// This is okay\nvar int = Integer(Number.MAX_SAFE_INTEGER).plus(1);\n\n// But this will throw a RangeError\nvar unsafe = int.toNumber();\n```\n\n# API\n\n### Integer(*value*) -\u003e *Integer*\n\nCasts a value to an `Integer`. If the value cannot be converted safely and losslessly, a `RangeError` is thrown.\n\n```js\nvar a = Integer();\nvar b = Integer(12345);\nvar c = Integer('12345');\nassert(a.equals(0));\nassert(b.equals(c));\n```\n\n### Integer.fromNumber(*number*, [*defaultValue*]) -\u003e *Integer*\n\nCasts a regular number to an `Integer`.\n\nIf the number is unsafe the `defaultValue` is used instead (or a `RangeError` is thrown if no `defaultValue` was provided).\n\n```js\nInteger.fromNumber(12345, 0); // results in Integer(12345)\nInteger.fromNumber(Number.MAX_SAFE_INTEGER + 1, 0); // results in Integer(0)\n```\n\n### Integer.fromString(*string*, [*radix*, [*defaultValue*]]) -\u003e *Integer*\n\nCasts a string to an `Integer`. The string is assumed to be [base-10](https://en.wikipedia.org/wiki/Radix) unless a different `radix` is specified.\n\nIf conversions fails the `defaultValue` is used instead (or a `RangeError` is thrown if no `defaultValue` was provided).\n\n```js\nvar hexColor = 'ff55dd';\nvar int = Integer.fromString(hexColor, 16, 'ffffff');\n```\n\n### Integer.fromBits(*lowBits*, [*highBits*]) -\u003e *Integer*\n\nCreates an `Integer` by concatenating two regular 32-bit signed integers. The `highBits` are optional and default to `0`.\n\n```js\nvar int = Integer.fromBits(0x40, 0x20);\nint.toString(16); // =\u003e '2000000040'\n```\n\n## Arithmetic operations\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.add/plus(*other*) -\u003e *Integer*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.subtract/sub/minus(*other*) -\u003e *Integer*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.multiply/mul/times(*other*) -\u003e *Integer*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.divide/div/divideBy/dividedBy/over(*other*) -\u003e *Integer*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.modulo/mod(*other*) -\u003e *Integer*\n\nPerforms the arithmetic operation and returns a new `Integer`. The argument must either be a number, a base-10 string, or an `Integer`. If the operation results in overflow, a `RangeError` is thrown.\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.negate/neg() -\u003e *Integer*\n\nReturns the unary negation (`-value`) of the `Integer`.\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.abs/absoluteValue() -\u003e *Integer*\n\nReturns the absolute value of the `Integer`.\n\n## Bitwise operations\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.and(*other*) -\u003e *Integer*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.or(*other*) -\u003e *Integer*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.xor(*other*) -\u003e *Integer*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.not() -\u003e *Integer*\n\nPerforms the bitwise operation and returns a new `Integer`. The argument must either be a number, a base-10 string, or an `Integer`.\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.shiftLeft/shl(*numberOfBits*) -\u003e *Integer*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.shiftRight/shr(*numberOfBits*) -\u003e *Integer*\n\nShifts the `Integer` by specified number of bits and returns the result.\n\n## Logical operations\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.equals/eq/isEqualTo(*other*) -\u003e *boolean*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.notEquals/neq/isNotEqualTo/doesNotEqual(*other*) -\u003e *boolean*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.greaterThan/gt/isGreaterThan(*other*) -\u003e *boolean*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.lessThan/lt/isLessThan(*other*) -\u003e *boolean*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.greaterThanOrEquals/gte/isGreaterThanOrEqualTo(*other*) -\u003e *boolean*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.lessThanOrEquals/lte/isLessThanOrEqualTo(*other*) -\u003e *boolean*\n\nPerforms the logical operation and returns `true` or `false`. The argument must either be a number, a base-10 string, or an `Integer`.\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.compare(*other*) -\u003e *number*\n\nCompares the value of the `Integer` and `other`, resulting in:\n- `-1` if `this` is less than `other`\n- `1` if `this` is greater than `other`\n- `0` if `this` is equal to `other`\n\n## Converting to other values\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.toString([*radix*]) -\u003e *string*\n\nConverts the `Integer` to a string. A base-10 string is returned unless a different `radix` is specified.\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.valueOf/toNumber() -\u003e *number*\n\nConverts the `Integer` to a regular number. If the `Integer` is not within the safe range, a `RangeError` is thrown.\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.toNumberUnsafe() -\u003e *number*\n\nConverts the `Integer` to a regular number, **even if the conversion would result in a loss of precision**. This method will never throw an error.\n\n## Other utility\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.bitSizeAbs() -\u003e *number*\n\nReturns the number of bits necessary to hold the absolute value of the `Integer`.\n\n```js\nInteger(0).bitSizeAbs(); // =\u003e 1\nInteger(128).bitSizeAbs(); // =\u003e 8\nInteger(-255).bitSizeAbs(); // =\u003e 8\nInteger.fromString('4fffffffffff', 16).bitSizeAbs(); // =\u003e 47\n```\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.isEven() -\u003e *boolean*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.isOdd() -\u003e *boolean*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.isPositive() -\u003e *boolean*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.isNegative() -\u003e *boolean*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.isZero() -\u003e *boolean*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.isNonZero/isNotZero() -\u003e *boolean*\n\nThese methods are self-explanatory.\n\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.isSafe() -\u003e *boolean*\n#### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;.isUnsafe() -\u003e *boolean*\n\nReturns whether or not the `Integer` is within the safe range. If it's not within the safe range, trying to convert it to a regular number would result in a `RangeError` being thrown.\n\nThe safe range is defined as `n \u003e= Number.MIN_SAFE_INTEGER \u0026\u0026 n \u003c= Number.MAX_SAFE_INTEGER`.\n\n#### Integer.isInstance(*value*) -\u003e *boolean*\n\nDetermines if the given value is an `Integer` object.\n\n#### Getters\n\n- **.low -\u003e _number_** - the lower 32-bits of the `Integer`\n- **.high -\u003e _number_** - the upper 32-bits of the `Integer`\n\n#### Constants\n\n- **Integer.MAX_VALUE** - maximum value of an `Integer`\n- **Integer.MIN_VALUE** - minimum value of an `Integer`\n- **Integer.ZERO** - an `Integer` with a value of `0`\n- **Integer.ONE** - an `Integer` with a value of `1`\n- **Integer.NEG_ONE** - an `Integer` with a value of `-1`\n\n## License\n\n[MIT](https://github.com/JoshuaWise/integer/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshuawise%2Finteger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshuawise%2Finteger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshuawise%2Finteger/lists"}