From 2065b8e98b5b6b5aceccdf217e0d6a10b1e82668 Mon Sep 17 00:00:00 2001 From: dcodeIO Date: Sat, 3 Feb 2018 17:48:52 +0100 Subject: [PATCH] Documentation updates --- README.md | 546 +++++++++++-------------------------------------- doco/INDEX.md | 6 - doco/Long.md | 494 -------------------------------------------- package.json | 4 +- src/long.js | 135 ++++++------ tests/index.js | 6 +- 6 files changed, 200 insertions(+), 991 deletions(-) delete mode 100644 doco/INDEX.md delete mode 100644 doco/Long.md diff --git a/README.md b/README.md index f82fca6..be79062 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ The class is compatible with CommonJS and AMD loaders and is exposed globally as var Long = require("long"); var longVal = new Long(0xFFFFFFFF, 0x7FFFFFFF); + console.log(longVal.toString()); ... ``` @@ -40,490 +41,193 @@ console.log(longVal.toString()); API --- -#### new Long(low, high=, unsigned=) - -Constructs a 64 bit two's-complement integer, given its low and high 32 bit values as *signed* integers. -See the from* functions below for more convenient ways of constructing Longs. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| low | *number* | The low (signed) 32 bits of the long -| high | *number* | The high (signed) 32 bits of the long -| unsigned | *boolean* | Whether unsigned or not, defaults to `false` for signed - ---- - -#### Long.MAX_UNSIGNED_VALUE - -Maximum unsigned value. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.MAX_VALUE - -Maximum signed value. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.MIN_VALUE - -Minimum signed value. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.NEG_ONE - -Signed negative one. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.ONE - -Signed one. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.UONE - -Unsigned one. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.UZERO - -Unsigned zero. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.ZERO - -Signed zero. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.fromBits(lowBits, highBits, unsigned=) - -Returns a Long representing the 64 bit integer that comes by concatenating the given low and high bits. Each is -assumed to use 32 bits. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| lowBits | *number* | The low 32 bits -| highBits | *number* | The high 32 bits -| unsigned | *boolean* | Whether unsigned or not, defaults to `false` for signed -| **@returns** | *!Long* | The corresponding Long value - -#### Long.fromBytes(arrBytes, offset=, unsigned=, le=) - -Returns a Long representing the 64 bit integer that comes by concatenating the given bytes. - -|Parameter |Type |Description -|---------------|---------------|------------- -|arrBytes |*!Array.<number>*|Byte representation in an array of at least offset+8 bytes -|offset |*number* |The starting index from which to read 8 elements of the array, defaults to zero -|unsigned |*boolean* |Whether unsigned or not, defaults to `false` for signed -|le |*boolean* |Whether little or big endian, defaults to big endian -|**@returns** |*!Long* |The corresponding Long value - -#### Long.fromInt(value, unsigned=) - -Returns a Long representing the given 32 bit integer value. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| value | *number* | The 32 bit integer in question -| unsigned | *boolean* | Whether unsigned or not, defaults to `false` for signed -| **@returns** | *!Long* | The corresponding Long value - -#### Long.fromNumber(value, unsigned=) - -Returns a Long representing the given value, provided that it is a finite number. Otherwise, zero is returned. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| value | *number* | The number in question -| unsigned | *boolean* | Whether unsigned or not, defaults to `false` for signed -| **@returns** | *!Long* | The corresponding Long value - -#### Long.fromString(str, unsigned=, radix=) - -Returns a Long representation of the given string, written using the specified radix. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| str | *string* | The textual representation of the Long -| unsigned | *boolean | number* | Whether unsigned or not, defaults to `false` for signed -| radix | *number* | The radix in which the text is written (2-36), defaults to 10 -| **@returns** | *!Long* | The corresponding Long value - -#### Long.isLong(obj) - -Tests if the specified object is a Long. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| obj | *** | Object -| **@returns** | *boolean* | - -#### Long.fromValue(val) - -Converts the specified value to a Long. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| val | *!Long | number | string | !{low: number, high: number, unsigned: boolean}* | Value -| **@returns** | *!Long* | - ---- - -#### Long#high - -The high 32 bits as a signed value. - -| | | -|-----------------|-----------------| -| **@type** | *number* | - -#### Long#low - -The low 32 bits as a signed value. - -| | | -|-----------------|-----------------| -| **@type** | *number* | - -#### Long#unsigned - -Whether unsigned or not. - -| | | -|-----------------|-----------------| -| **@type** | *boolean* | - -#### Long#add(addend) - -Returns the sum of this and the specified Long. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| addend | *!Long | number | string* | Addend -| **@returns** | *!Long* | Sum - -#### Long#and(other) - -Returns the bitwise AND of this Long and the specified. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other Long -| **@returns** | *!Long* | - -#### Long#compare/comp(other) - -Compares this Long's value with the specified's. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *number* | 0 if they are the same, 1 if the this is greater and -1 if the given one is greater - -#### Long#divide/div(divisor) - -Returns this Long divided by the specified. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| divisor | *!Long | number | string* | Divisor -| **@returns** | *!Long* | Quotient - -#### Long#equals/eq(other) - -Tests if this Long's value equals the specified's. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | - -#### Long#getHighBits() - -Gets the high 32 bits as a signed integer. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | Signed high bits - -#### Long#getHighBitsUnsigned() - -Gets the high 32 bits as an unsigned integer. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | Unsigned high bits - -#### Long#getLowBits() - -Gets the low 32 bits as a signed integer. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | Signed low bits - -#### Long#getLowBitsUnsigned() - -Gets the low 32 bits as an unsigned integer. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | Unsigned low bits - -#### Long#getNumBitsAbs() - -Gets the number of bits needed to represent the absolute value of this Long. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | - -#### Long#greaterThan/gt(other) - -Tests if this Long's value is greater than the specified's. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | - -#### Long#greaterThanOrEqual/gte(other) - -Tests if this Long's value is greater than or equal the specified's. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | - -#### Long#isEven() - -Tests if this Long's value is even. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *boolean* | - -#### Long#isNegative() - -Tests if this Long's value is negative. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *boolean* | - -#### Long#isOdd() - -Tests if this Long's value is odd. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *boolean* | +### Constructor -#### Long#isPositive() +* new **Long**(low: `number`, high: `number`, unsigned?: `boolean`)
+ Constructs a 64 bit two's-complement integer, given its low and high 32 bit values as *signed* integers. See the from* functions below for more convenient ways of constructing Longs. -Tests if this Long's value is positive. +### Fields -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *boolean* | +* Long#**low**: `number`
+ The low 32 bits as a signed value. -#### Long#isZero() +* Long#**high**: `number`
+ The high 32 bits as a signed value. -Tests if this Long's value equals zero. +* Long#**unsigned**: `boolean`
+ Whether unsigned or not. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *boolean* | +### Constants -#### Long#lessThan/lt(other) +* Long.**ZERO**: `Long`
+ Signed zero. -Tests if this Long's value is less than the specified's. +* Long.**ONE**: `Long`
+ Signed one. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | +* Long.**NEG_ONE**: `Long`
+ Signed negative one. -#### Long#lessThanOrEqual/lte(other) +* Long.**UZERO**: `Long`
+ Unsigned zero. -Tests if this Long's value is less than or equal the specified's. +* Long.**UONE**: `Long`
+ Unsigned one. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | +* Long.**MAX_VALUE**: `Long`
+ Maximum signed value. -#### Long#modulo/mod(divisor) +* Long.**MIN_VALUE**: `Long`
+ Minimum signed value. -Returns this Long modulo the specified. +* Long.**MAX_UNSIGNED_VALUE**: `Long`
+ Maximum unsigned value. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| divisor | *!Long | number | string* | Divisor -| **@returns** | *!Long* | Remainder +### Utility -#### Long#multiply/mul(multiplier) +* Long.**isLong**(obj: `*`): `boolean`
+ Tests if the specified object is a Long. -Returns the product of this and the specified Long. +* Long.**fromBits**(lowBits: `number`, highBits: `number`, unsigned?: `boolean`): `Long`
+ Returns a Long representing the 64 bit integer that comes by concatenating the given low and high bits. Each is assumed to use 32 bits. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| multiplier | *!Long | number | string* | Multiplier -| **@returns** | *!Long* | Product +* Long.**fromBytes**(bytes: `number[]`, unsigned?: `boolean`, le?: `boolean`): `Long`
+ Creates a Long from its byte representation. -#### Long#negate/neg() +* Long.**fromBytesLE**(bytes: `number[]`, unsigned?: `boolean`): `Long`
+ Creates a Long from its little endian byte representation. -Negates this Long's value. +* Long.**fromBytesBE**(bytes: `number[]`, unsigned?: `boolean`): `Long`
+ Creates a Long from its big endian byte representation. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *!Long* | Negated Long +* Long.**fromInt**(value: `number`, unsigned?: `boolean`): `Long`
+ Returns a Long representing the given 32 bit integer value. -#### Long#not() +* Long.**fromNumber**(value: `number`, unsigned?: `boolean`): `Long`
+ Returns a Long representing the given value, provided that it is a finite number. Otherwise, zero is returned. -Returns the bitwise NOT of this Long. +* Long.**fromString**(str: `string`, unsigned?: `boolean`, radix?: `number`)
+ Long.**fromString**(str: `string`, radix: `number`)
+ Returns a Long representation of the given string, written using the specified radix. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *!Long* | +* Long.**fromValue**(val: `*`): `Long`
+ Converts the specified value to a Long using the appropriate from* function for its type. -#### Long#notEquals/neq(other) +### Methods -Tests if this Long's value differs from the specified's. +* Long#**add**(addend: `Long | number | string`): `Long`
+ Returns the sum of this and the specified Long. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | +* Long#**and**(other: `Long | number | string`): `Long`
+ Returns the bitwise AND of this Long and the specified. -#### Long#or(other) +* Long#**compare**/**comp**(other: `Long | number | string`): `number`
+ Compares this Long's value with the specified's. Returns `0` if they are the same, `1` if the this is greater and `-1` if the given one is greater. -Returns the bitwise OR of this Long and the specified. +* Long#**divide**/**div**(divisor: `Long | number | string`): `Long`
+ Returns this Long divided by the specified. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other Long -| **@returns** | *!Long* | +* Long#**equals**/**eq**(other: `Long | number | string`): `boolean`
+ Tests if this Long's value equals the specified's. -#### Long#shiftLeft/shl(numBits) +* Long#**getHighBits**(): `number`
+ Gets the high 32 bits as a signed integer. -Returns this Long with bits shifted to the left by the given amount. +* Long#**getHighBitsUnsigned**(): `number`
+ Gets the high 32 bits as an unsigned integer. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| numBits | *number | !Long* | Number of bits -| **@returns** | *!Long* | Shifted Long +* Long#**getLowBits**(): `number`
+ Gets the low 32 bits as a signed integer. -#### Long#shiftRight/shr(numBits) +* Long#**getLowBitsUnsigned**(): `number`
+ Gets the low 32 bits as an unsigned integer. -Returns this Long with bits arithmetically shifted to the right by the given amount. +* Long#**getNumBitsAbs**(): `number`
+ Gets the number of bits needed to represent the absolute value of this Long. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| numBits | *number | !Long* | Number of bits -| **@returns** | *!Long* | Shifted Long +* Long#**greaterThan**/**gt**(other: `Long | number | string`): `boolean`
+ Tests if this Long's value is greater than the specified's. -#### Long#shiftRightUnsigned/shru(numBits) +* Long#**greaterThanOrEqual**/**gte**(other: `Long | number | string`): `boolean`
+ Tests if this Long's value is greater than or equal the specified's. -Returns this Long with bits logically shifted to the right by the given amount. +* Long#**isEven**(): `boolean`
+ Tests if this Long's value is even. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| numBits | *number | !Long* | Number of bits -| **@returns** | *!Long* | Shifted Long +* Long#**isNegative**(): `boolean`
+ Tests if this Long's value is negative. -#### Long#subtract/sub(subtrahend) +* Long#**isOdd**(): `boolean`
+ Tests if this Long's value is odd. -Returns the difference of this and the specified Long. +* Long#**isPositive**(): `boolean`
+ Tests if this Long's value is positive. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| subtrahend | *!Long | number | string* | Subtrahend -| **@returns** | *!Long* | Difference +* Long#**isZero**(): `boolean`
+ Tests if this Long's value equals zero. -#### Long#toBytes(le=) +* Long#**lessThan**/**lt**(other: `Long | number | string`): `boolean`
+ Tests if this Long's value is less than the specified's. -Converts this Long to its byte representation. +* Long#**lessThanOrEqual**/**lte**(other: `Long | number | string`): `boolean`
+ Tests if this Long's value is less than or equal the specified's. -|Parameter |Type |Description -|---------------|---------------|------------- -|le |*boolean* |Whether little or big endian, defaults to big endian -|**@returns** |*!Array.<number>*|Byte representation +* Long#**modulo**/**mod**(divisor: `Long | number | string`): `Long`
+ Returns this Long modulo the specified. -#### Long#toInt() +* Long#**multiply**/**mul**(multiplier: `Long | number | string`): `Long`
+ Returns the product of this and the specified Long. -Converts the Long to a 32 bit integer, assuming it is a 32 bit integer. +* Long#**negate**/**neg**(): `Long`
+ Negates this Long's value. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | +* Long#**not**(): `Long`
+ Returns the bitwise NOT of this Long. -#### Long#toNumber() +* Long#**notEquals**/**neq**(other: `Long | number | string`): `boolean`
+ Tests if this Long's value differs from the specified's. -Converts the Long to a the nearest floating-point representation of this value (double, 53 bit mantissa). +* Long#**or**(other: `Long | number | string`): `Long`
+ Returns the bitwise OR of this Long and the specified. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | +* Long#**shiftLeft**/**shl**(numBits: `Long | number | string`): `Long`
+ Returns this Long with bits shifted to the left by the given amount. -#### Long#toSigned() +* Long#**shiftRight**/**shr**(numBits: `Long | number | string`): `Long`
+ Returns this Long with bits arithmetically shifted to the right by the given amount. -Converts this Long to signed. +* Long#**shiftRightUnsigned**/**shru**(numBits: `Long | number | string`): `Long`
+ Returns this Long with bits logically shifted to the right by the given amount. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *!Long* | Signed long +* Long#**subtract**/**sub**(subtrahend: `Long | number | string`): `Long`
+ Returns the difference of this and the specified Long. -#### Long#toString(radix=) +* Long#**toBytes**(le?: `boolean`): `number[]`
+ Converts this Long to its byte representation. -Converts the Long to a string written in the specified radix. +* Long#**toBytesLE**(): `number[]`
+ Converts this Long to its little endian byte representation. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| radix | *number* | Radix (2-36), defaults to 10 -| **@returns** | *string* | -| **@throws** | *RangeError* | If `radix` is out of range +* Long#**toBytesBE**(): `number[]`
+ Converts this Long to its big endian byte representation. -#### Long#toUnsigned() +* Long#**toInt**(): `number`
+ Converts the Long to a 32 bit integer, assuming it is a 32 bit integer. -Converts this Long to unsigned. +* Long#**toNumber**(): `number`
+ Converts the Long to a the nearest floating-point representation of this value (double, 53 bit mantissa). -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *!Long* | Unsigned long +* Long#**toSigned**(): `Long`
+ Converts this Long to signed. -#### Long#xor(other) +* Long#**toString**(radix?: `number`): `string`
+ Converts the Long to a string written in the specified radix. -Returns the bitwise XOR of this Long and the given one. +* Long#**toUnsigned**(): `Long`
+ Converts this Long to unsigned. -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other Long -| **@returns** | *!Long* | +* Long#**xor**(other: `Long | number | string`): `Long`
+ Returns the bitwise XOR of this Long and the given one. Building -------- diff --git a/doco/INDEX.md b/doco/INDEX.md deleted file mode 100644 index e76930c..0000000 --- a/doco/INDEX.md +++ /dev/null @@ -1,6 +0,0 @@ -### Class [Long](Long.md) - -A Long class for representing a 64 bit two's-complement integer value. - ---- -*Generated with [doco](https://github.com/dcodeIO/doco) v0.3.0* diff --git a/doco/Long.md b/doco/Long.md deleted file mode 100644 index dfa63f3..0000000 --- a/doco/Long.md +++ /dev/null @@ -1,494 +0,0 @@ -## Class Long - -A Long class for representing a 64 bit two's-complement integer value. - ---- - -#### new Long(low, high=, unsigned=) - -Constructs a 64 bit two's-complement integer, given its low and high 32 bit values as *signed* integers. -See the from* functions below for more convenient ways of constructing Longs. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| low | *number* | The low (signed) 32 bits of the long -| high | *number* | The high (signed) 32 bits of the long -| unsigned | *boolean* | Whether unsigned or not, defaults to `false` for signed - ---- - -#### Long.MAX_UNSIGNED_VALUE - -Maximum unsigned value. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.MAX_VALUE - -Maximum signed value. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.MIN_VALUE - -Minimum signed value. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.NEG_ONE - -Signed negative one. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.ONE - -Signed one. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.UONE - -Unsigned one. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.UZERO - -Unsigned zero. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.ZERO - -Signed zero. - -| | | -|-----------------|-----------------| -| **@type** | *!Long* | - -#### Long.fromBits(lowBits, highBits, unsigned=) - -Returns a Long representing the 64 bit integer that comes by concatenating the given low and high bits. Each is -assumed to use 32 bits. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| lowBits | *number* | The low 32 bits -| highBits | *number* | The high 32 bits -| unsigned | *boolean* | Whether unsigned or not, defaults to `false` for signed -| **@returns** | *!Long* | The corresponding Long value - -#### Long.fromBytes(arrBytes, offset=, unsigned=, le=) - -Returns a Long representing the 64 bit integer that comes by concatenating the given bytes. - -|Parameter |Type |Description -|---------------|---------------|------------- -|arrBytes |*!Array.<number>*|Byte representation in an array of at least offset+8 bytes -|offset |*number* |The starting index from which to read 8 elements of the array, defaults to zero -|unsigned |*boolean* |Whether unsigned or not, defaults to `false` for signed -|le |*boolean* |Whether little or big endian, defaults to big endian -|**@returns** |*!Long* |The corresponding Long value - -#### Long.fromInt(value, unsigned=) - -Returns a Long representing the given 32 bit integer value. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| value | *number* | The 32 bit integer in question -| unsigned | *boolean* | Whether unsigned or not, defaults to `false` for signed -| **@returns** | *!Long* | The corresponding Long value - -#### Long.fromNumber(value, unsigned=) - -Returns a Long representing the given value, provided that it is a finite number. Otherwise, zero is returned. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| value | *number* | The number in question -| unsigned | *boolean* | Whether unsigned or not, defaults to `false` for signed -| **@returns** | *!Long* | The corresponding Long value - -#### Long.fromString(str, unsigned=, radix=) - -Returns a Long representation of the given string, written using the specified radix. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| str | *string* | The textual representation of the Long -| unsigned | *boolean | number* | Whether unsigned or not, defaults to `false` for signed -| radix | *number* | The radix in which the text is written (2-36), defaults to 10 -| **@returns** | *!Long* | The corresponding Long value - -#### Long.isLong(obj) - -Tests if the specified object is a Long. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| obj | *** | Object -| **@returns** | *boolean* | - -#### Long.fromValue(val) - -Converts the specified value to a Long. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| val | *!Long | number | string | !{low: number, high: number, unsigned: boolean}* | Value -| **@returns** | *!Long* | - ---- - -#### Long#high - -The high 32 bits as a signed value. - -| | | -|-----------------|-----------------| -| **@type** | *number* | - -#### Long#low - -The low 32 bits as a signed value. - -| | | -|-----------------|-----------------| -| **@type** | *number* | - -#### Long#unsigned - -Whether unsigned or not. - -| | | -|-----------------|-----------------| -| **@type** | *boolean* | - -#### Long#add(addend) - -Returns the sum of this and the specified Long. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| addend | *!Long | number | string* | Addend -| **@returns** | *!Long* | Sum - -#### Long#and(other) - -Returns the bitwise AND of this Long and the specified. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other Long -| **@returns** | *!Long* | - -#### Long#compare(other) - -Compares this Long's value with the specified's. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *number* | 0 if they are the same, 1 if the this is greater and -1 if the given one is greater - -#### Long#div(divisor) - -Returns this Long divided by the specified. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| divisor | *!Long | number | string* | Divisor -| **@returns** | *!Long* | Quotient - -#### Long#equals(other) - -Tests if this Long's value equals the specified's. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | - -#### Long#getHighBits() - -Gets the high 32 bits as a signed integer. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | Signed high bits - -#### Long#getHighBitsUnsigned() - -Gets the high 32 bits as an unsigned integer. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | Unsigned high bits - -#### Long#getLowBits() - -Gets the low 32 bits as a signed integer. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | Signed low bits - -#### Long#getLowBitsUnsigned() - -Gets the low 32 bits as an unsigned integer. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | Unsigned low bits - -#### Long#getNumBitsAbs() - -Gets the number of bits needed to represent the absolute value of this Long. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | - -#### Long#greaterThan(other) - -Tests if this Long's value is greater than the specified's. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | - -#### Long#greaterThanOrEqual(other) - -Tests if this Long's value is greater than or equal the specified's. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | - -#### Long#isEven() - -Tests if this Long's value is even. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *boolean* | - -#### Long#isNegative() - -Tests if this Long's value is negative. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *boolean* | - -#### Long#isOdd() - -Tests if this Long's value is odd. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *boolean* | - -#### Long#isPositive() - -Tests if this Long's value is positive. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *boolean* | - -#### Long#isZero() - -Tests if this Long's value equals zero. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *boolean* | - -#### Long#lessThan(other) - -Tests if this Long's value is less than the specified's. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | - -#### Long#lessThanOrEqual(other) - -Tests if this Long's value is less than or equal the specified's. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | - -#### Long#modulo(divisor) - -Returns this Long modulo the specified. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| divisor | *!Long | number | string* | Divisor -| **@returns** | *!Long* | Remainder - -#### Long#multiply(multiplier) - -Returns the product of this and the specified Long. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| multiplier | *!Long | number | string* | Multiplier -| **@returns** | *!Long* | Product - -#### Long#negate() - -Negates this Long's value. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *!Long* | Negated Long - -#### Long#not() - -Returns the bitwise NOT of this Long. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *!Long* | - -#### Long#notEquals(other) - -Tests if this Long's value differs from the specified's. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other value -| **@returns** | *boolean* | - -#### Long#or(other) - -Returns the bitwise OR of this Long and the specified. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other Long -| **@returns** | *!Long* | - -#### Long#shiftLeft(numBits) - -Returns this Long with bits shifted to the left by the given amount. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| numBits | *number | !Long* | Number of bits -| **@returns** | *!Long* | Shifted Long - -#### Long#shiftRight(numBits) - -Returns this Long with bits arithmetically shifted to the right by the given amount. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| numBits | *number | !Long* | Number of bits -| **@returns** | *!Long* | Shifted Long - -#### Long#shiftRightUnsigned(numBits) - -Returns this Long with bits logically shifted to the right by the given amount. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| numBits | *number | !Long* | Number of bits -| **@returns** | *!Long* | Shifted Long - -#### Long#subtract(subtrahend) - -Returns the difference of this and the specified Long. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| subtrahend | *!Long | number | string* | Subtrahend -| **@returns** | *!Long* | Difference - -#### Long#toBytes(le=) - -Converts this Long to its byte representation. - -|Parameter |Type |Description -|---------------|---------------|------------- -|le |*boolean* |Whether little or big endian, defaults to big endian -|**@returns** |*!Array.<number>*|Byte representation - -#### Long#toInt() - -Converts the Long to a 32 bit integer, assuming it is a 32 bit integer. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | - -#### Long#toNumber() - -Converts the Long to a the nearest floating-point representation of this value (double, 53 bit mantissa). - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *number* | - -#### Long#toSigned() - -Converts this Long to signed. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *!Long* | Signed long - -#### Long#toString(radix=) - -Converts the Long to a string written in the specified radix. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| radix | *number* | Radix (2-36), defaults to 10 -| **@returns** | *string* | -| **@throws** | *RangeError* | If `radix` is out of range - -#### Long#toUnsigned() - -Converts this Long to unsigned. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| **@returns** | *!Long* | Unsigned long - -#### Long#xor(other) - -Returns the bitwise XOR of this Long and the given one. - -| Parameter | Type | Description -|-----------------|-----------------|--------------- -| other | *!Long | number | string* | Other Long -| **@returns** | *!Long* | - - ---- -*Generated with [doco](https://github.com/dcodeIO/doco) v0.3.0* diff --git a/package.json b/package.json index 672c241..3a955c6 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,9 @@ "keywords": [ "math" ], - "dependencies": {}, + "dependencies": { + "doco": "^0.3.0" + }, "devDependencies": { "webpack": "^3.10.0" }, diff --git a/src/long.js b/src/long.js index a81b614..4820c3f 100644 --- a/src/long.js +++ b/src/long.js @@ -7,7 +7,7 @@ module.exports = Long; * @class A Long class for representing a 64 bit two's-complement integer value. * @param {number} low The low (signed) 32 bits of the long * @param {number} high The high (signed) 32 bits of the long - * @param {boolean=} unsigned Whether unsigned or not, defaults to `false` for signed + * @param {boolean=} unsigned Whether unsigned or not, defaults to signed * @constructor */ function Long(low, high, unsigned) { @@ -56,11 +56,7 @@ function Long(low, high, unsigned) { */ Long.prototype.__isLong__; -Object.defineProperty(Long.prototype, "__isLong__", { - value: true, - enumerable: false, - configurable: false -}); +Object.defineProperty(Long.prototype, "__isLong__", { value: true }); /** * @function @@ -131,7 +127,7 @@ function fromInt(value, unsigned) { * Returns a Long representing the given 32 bit integer value. * @function * @param {number} value The 32 bit integer in question - * @param {boolean=} unsigned Whether unsigned or not, defaults to `false` for signed + * @param {boolean=} unsigned Whether unsigned or not, defaults to signed * @returns {!Long} The corresponding Long value */ Long.fromInt = fromInt; @@ -165,7 +161,7 @@ function fromNumber(value, unsigned) { * Returns a Long representing the given value, provided that it is a finite number. Otherwise, zero is returned. * @function * @param {number} value The number in question - * @param {boolean=} unsigned Whether unsigned or not, defaults to `false` for signed + * @param {boolean=} unsigned Whether unsigned or not, defaults to signed * @returns {!Long} The corresponding Long value */ Long.fromNumber = fromNumber; @@ -187,7 +183,7 @@ function fromBits(lowBits, highBits, unsigned) { * @function * @param {number} lowBits The low 32 bits * @param {number} highBits The high 32 bits - * @param {boolean=} unsigned Whether unsigned or not, defaults to `false` for signed + * @param {boolean=} unsigned Whether unsigned or not, defaults to signed * @returns {!Long} The corresponding Long value */ Long.fromBits = fromBits; @@ -255,7 +251,7 @@ function fromString(str, unsigned, radix) { * Returns a Long representation of the given string, written using the specified radix. * @function * @param {string} str The textual representation of the Long - * @param {(boolean|number)=} unsigned Whether unsigned or not, defaults to `false` for signed + * @param {(boolean|number)=} unsigned Whether unsigned or not, defaults to signed * @param {number=} radix The radix in which the text is written (2-36), defaults to 10 * @returns {!Long} The corresponding Long value */ @@ -279,7 +275,7 @@ function fromValue(val) { } /** - * Converts the specified value to a Long. + * Converts the specified value to a Long using the appropriate from* function for its type. * @function * @param {!Long|number|string|!{low: number, high: number, unsigned: boolean}} val Value * @returns {!Long} @@ -1143,14 +1139,14 @@ LongPrototype.toBytesLE = function toBytesLE() { var hi = this.high, lo = this.low; return [ - lo & 0xff, - (lo >>> 8) & 0xff, - (lo >>> 16) & 0xff, - (lo >>> 24) & 0xff, - hi & 0xff, - (hi >>> 8) & 0xff, - (hi >>> 16) & 0xff, - (hi >>> 24) & 0xff + lo & 0xff, + lo >>> 8 & 0xff, + lo >>> 16 & 0xff, + lo >>> 24 , + hi & 0xff, + hi >>> 8 & 0xff, + hi >>> 16 & 0xff, + hi >>> 24 ]; }; @@ -1162,57 +1158,64 @@ LongPrototype.toBytesBE = function toBytesBE() { var hi = this.high, lo = this.low; return [ - (hi >>> 24) & 0xff, - (hi >>> 16) & 0xff, - (hi >>> 8) & 0xff, - hi & 0xff, - (lo >>> 24) & 0xff, - (lo >>> 16) & 0xff, - (lo >>> 8) & 0xff, - lo & 0xff + hi >>> 24 , + hi >>> 16 & 0xff, + hi >>> 8 & 0xff, + hi & 0xff, + lo >>> 24 , + lo >>> 16 & 0xff, + lo >>> 8 & 0xff, + lo & 0xff ]; }; /** - * @param {!Array.} arrBytes - * @param {number=} offset - * @param {boolean=} unsigned - * @param {boolean=} le - * @returns {!Long} - * @inner + * Creates a Long from its byte representation. + * @param {!Array.} bytes Byte representation + * @param {boolean=} unsigned Whether unsigned or not, defaults to signed + * @param {boolean=} le Whether little or big endian, defaults to big endian + * @returns {Long} The corresponding Long value */ -function fromBytes(arrBytes, offset, unsigned, le) { - if (typeof(offset)!=='number') offset=0; - if (le) { - var lo = arrBytes[offset++]; - lo |= (arrBytes[offset++] << 8); - lo |= (arrBytes[offset++] << 16); - lo |= (arrBytes[offset++] << 24); - var hi = arrBytes[offset++]; - hi |= (arrBytes[offset++] << 8); - hi |= (arrBytes[offset++] << 16); - hi |= (arrBytes[offset] << 24); - } - else { - var hi = (arrBytes[offset++] << 24); - hi |= (arrBytes[offset++] << 16); - hi |= (arrBytes[offset++] << 8); - hi |= arrBytes[offset++]; - var lo = (arrBytes[offset++] << 24); - lo |= (arrBytes[offset++] << 16); - lo |= (arrBytes[offset++] << 8); - lo |= arrBytes[offset]; - } - return Long.fromBits(lo, hi, unsigned); -} +Long.fromBytes = function fromBytes(bytes, unsigned, le) { + return le ? Long.fromBytesLE(bytes, unsigned) : Long.fromBytesBE(bytes, unsigned); +}; /** - * Returns a Long representing the 64 bit integer that comes by concatenating the given bytes. - * @function - * @param {!Array.} arrBytes Byte representation in an array of at least offset+8 bytes - * @param {number=} offset The starting index from which to read 8 elements of the array, defaults to zero - * @param {boolean=} unsigned Whether unsigned or not, defaults to `false` for signed - * @param {boolean=} le Whether little or big endian, defaults to big endian - * @returns {!Long} The corresponding Long value - */ -Long.fromBytes = fromBytes; + * Creates a Long from its little endian byte representation. + * @param {!Array.} bytes Little endian byte representation + * @param {boolean=} unsigned Whether unsigned or not, defaults to signed + * @returns {Long} The corresponding Long value + */ +Long.fromBytesLE = function fromBytesLE(bytes, unsigned) { + return new Long( + bytes[0] | + bytes[1] << 8 | + bytes[2] << 16 | + bytes[3] << 24, + bytes[4] | + bytes[5] << 8 | + bytes[6] << 16 | + bytes[7] << 24, + unsigned + ); +}; + +/** + * Creates a Long from its big endian byte representation. + * @param {!Array.} bytes Big endian byte representation + * @param {boolean=} unsigned Whether unsigned or not, defaults to signed + * @returns {Long} The corresponding Long value + */ +Long.fromBytesBE = function fromBytesBE(bytes, unsigned) { + return new Long( + bytes[4] << 24 | + bytes[5] << 16 | + bytes[6] << 8 | + bytes[7], + bytes[0] << 24 | + bytes[1] << 16 | + bytes[2] << 8 | + bytes[3], + unsigned + ); +}; diff --git a/tests/index.js b/tests/index.js index 57bd4ce..e016a7f 100644 --- a/tests/index.js +++ b/tests/index.js @@ -49,9 +49,9 @@ function testFromBytes() { var ulongVal = Long.fromBits(0x01234567, 0x12345678, true); assert.deepEqual(Long.fromBytes(longVal.toBytes()), longVal); assert.deepEqual(Long.fromBytes([0x12, 0x34, 0x56, 0x78, 0x01, 0x23, 0x45, 0x67]), longVal); - assert.deepEqual(Long.fromBytes([0x12, 0x34, 0x56, 0x78, 0x01, 0x23, 0x45, 0x67], 0, false, false), longVal); - assert.deepEqual(Long.fromBytes([0xFF, 0x67, 0x45, 0x23, 0x01, 0x78, 0x56, 0x34, 0x12], 1, false, true), longVal); - assert.deepEqual(Long.fromBytes([0xFF, 0x67, 0x45, 0x23, 0x01, 0x78, 0x56, 0x34, 0x12], 1, true, true), ulongVal); + assert.deepEqual(Long.fromBytes([0x12, 0x34, 0x56, 0x78, 0x01, 0x23, 0x45, 0x67], false, false), longVal); + assert.deepEqual(Long.fromBytes([0x67, 0x45, 0x23, 0x01, 0x78, 0x56, 0x34, 0x12], false, true), longVal); + assert.deepEqual(Long.fromBytes([0x67, 0x45, 0x23, 0x01, 0x78, 0x56, 0x34, 0x12], true, true), ulongVal); }, function testUnsignedMinMax() {