buffer: add{read|write}Big[U]Int64{BE|LE} methods

Backport-PR-URL: #30361 PR-URL: #19691 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: Tiancheng "Timothy" Gu <[email protected]> Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Matteo Collina <[email protected]>

Author: GaryGSC

benchmark/buffers/buffer-read.js

@@ -2,6 +2,10 @@
 constcommon=require('../common.js');
 
 consttypes=[
+'BigUInt64LE',
+'BigUInt64BE',
+'BigInt64LE',
+'BigInt64BE',
 'UInt8',
 'UInt16LE',
 'UInt16BE',

benchmark/buffers/buffer-write.js

@@ -2,6 +2,10 @@
 constcommon=require('../common.js');
 
 consttypes=[
+'BigUInt64LE',
+'BigUInt64BE',
+'BigInt64LE',
+'BigInt64BE',
 'UInt8',
 'UInt16LE',
 'UInt16BE',
@@ -32,11 +36,17 @@ const INT8 = 0x7f;
 constINT16=0x7fff;
 constINT32=0x7fffffff;
 constINT48=0x7fffffffffff;
+constINT64=0x7fffffffffffffffn;
 constUINT8=0xff;
 constUINT16=0xffff;
 constUINT32=0xffffffff;
+constUINT64=0xffffffffffffffffn;
 
 constmod={
+writeBigInt64BE: INT64,
+writeBigInt64LE: INT64,
+writeBigUInt64BE: UINT64,
+writeBigUInt64LE: UINT64,
 writeInt8: INT8,
 writeInt16BE: INT16,
 writeInt16LE: INT16,
@@ -67,12 +77,23 @@ function main({n, buf, type }){
 
 if(!/\d/.test(fn))
 benchSpecialInt(buff,fn,n);
+elseif(/BigU?Int/.test(fn))
+benchBigInt(buff,fn,BigInt(n));
 elseif(/Int/.test(fn))
 benchInt(buff,fn,n);
 else
 benchFloat(buff,fn,n);
 }
 
+functionbenchBigInt(buff,fn,n){
+constm=mod[fn];
+bench.start();
+for(vari=0n;i!==n;i++){
+buff[fn](i&m,0);
+}
+bench.end(Number(n));
+}
+
 functionbenchInt(buff,fn,n){
 constm=mod[fn];
 bench.start();

doc/api/buffer.md

@@ -1529,6 +1529,47 @@ deprecated: v8.0.0
 
 The `buf.parent` property is a deprecated alias for `buf.buffer`.
 
+### buf.readBigInt64BE(offset)
+### buf.readBigInt64LE(offset)
+<!-- YAML
+added: REPLACEME
+-->
+
+*`offset`{integer} Number of bytes to skip before starting to read. Must
+ satisfy: `0 <= offset <= buf.length - 8`. **Default:**`0`.
+* Returns:{bigint}
+
+Reads a signed 64-bit integer from `buf` at the specified `offset` with
+the specified endian format (`readBigInt64BE()` returns big endian,
+`readBigInt64LE()` returns little endian).
+
+Integers read from a `Buffer` are interpreted as two's complement signed values.
+
+### buf.readBigUInt64BE(offset)
+### buf.readBigUInt64LE(offset)
+<!-- YAML
+added: REPLACEME
+-->
+
+*`offset`{integer} Number of bytes to skip before starting to read. Must
+ satisfy: `0 <= offset <= buf.length - 8`. **Default:**`0`.
+* Returns:{bigint}
+
+Reads an unsigned 64-bit integer from `buf` at the specified `offset` with
+specified endian format (`readBigUInt64BE()` returns big endian,
+`readBigUInt64LE()` returns little endian).
+
+```js
+constbuf=Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]);
+
+console.log(buf.readBigUInt64BE(0));
+// Prints: 4294967295n
+
+console.log(buf.readBigUInt64LE(0));
+// Prints: 18446744069414584320n
+```
+
+
 ### buf.readDoubleBE(offset)
 ### buf.readDoubleLE(offset)
 <!-- YAML
@@ -2132,6 +2173,56 @@ console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
 // Prints: 12 bytes: ½ + ¼ = ¾
 ```
 
+### buf.writeBigInt64BE(value, offset)
+### buf.writeBigInt64LE(value, offset)
+<!-- YAML
+added: REPLACEME
+-->
+
+*`value`{bigint} Number to be written to `buf`.
+*`offset`{integer} Number of bytes to skip before starting to write. Must
+ satisfy: `0 <= offset <= buf.length - 8`. **Default:**`0`.
+* Returns:{integer} `offset` plus the number of bytes written.
+
+Writes `value` to `buf` at the specified `offset` with specified endian
+format (`writeBigInt64BE()` writes big endian, `writeBigInt64LE()` writes little
+endian).
+
+`value` is interpreted and written as a two's complement signed integer.
+
+```js
+constbuf=Buffer.allocUnsafe(8);
+
+buf.writeBigInt64BE(0x0102030405060708n, 0);
+
+console.log(buf);
+// Prints: <Buffer 01 02 03 04 05 06 07 08>
+```
+
+### buf.writeBigUInt64BE(value, offset)
+### buf.writeBigUInt64LE(value, offset)
+<!-- YAML
+added: REPLACEME
+-->
+
+*`value`{bigint} Number to be written to `buf`.
+*`offset`{integer} Number of bytes to skip before starting to write. Must
+ satisfy: `0 <= offset <= buf.length - 8`. **Default:**`0`.
+* Returns:{integer} `offset` plus the number of bytes written.
+
+Writes `value` to `buf` at the specified `offset` with specified endian
+format (`writeBigUInt64BE()` writes big endian, `writeBigUInt64LE()` writes
+little endian).
+
+```js
+constbuf=Buffer.allocUnsafe(8);
+
+buf.writeBigUInt64LE(0xdecafafecacefaden, 0);
+
+console.log(buf);
+// Prints: <Buffer de fa ce ca fe fa ca de>
+```
+
 ### buf.writeDoubleBE(value, offset)
 ### buf.writeDoubleLE(value, offset)
 <!-- YAML

lib/internal/buffer.js

@@ -52,6 +52,82 @@ function boundsError(value, length, type){
 }
 
 // Read integers.
+functionreadBigUInt64LE(offset=0){
+validateNumber(offset,'offset');
+constfirst=this[offset];
+constlast=this[offset+7];
+if(first===undefined||last===undefined)
+boundsError(offset,this.length-8);
+
+constlo=first+
+this[++offset]*2**8+
+this[++offset]*2**16+
+this[++offset]*2**24;
+
+consthi=this[++offset]+
+this[++offset]*2**8+
+this[++offset]*2**16+
+last*2**24;
+
+returnBigInt(lo)+(BigInt(hi)<<32n);
+}
+
+functionreadBigUInt64BE(offset=0){
+validateNumber(offset,'offset');
+constfirst=this[offset];
+constlast=this[offset+7];
+if(first===undefined||last===undefined)
+boundsError(offset,this.length-8);
+
+consthi=first*2**24+
+this[++offset]*2**16+
+this[++offset]*2**8+
+this[++offset];
+
+constlo=this[++offset]*2**24+
+this[++offset]*2**16+
+this[++offset]*2**8+
+last;
+
+return(BigInt(hi)<<32n)+BigInt(lo);
+}
+
+functionreadBigInt64LE(offset=0){
+validateNumber(offset,'offset');
+constfirst=this[offset];
+constlast=this[offset+7];
+if(first===undefined||last===undefined)
+boundsError(offset,this.length-8);
+
+constval=this[offset+4]+
+this[offset+5]*2**8+
+this[offset+6]*2**16+
+(last<<24);// Overflow
+return(BigInt(val)<<32n)+
+BigInt(first+
+this[++offset]*2**8+
+this[++offset]*2**16+
+this[++offset]*2**24);
+}
+
+functionreadBigInt64BE(offset=0){
+validateNumber(offset,'offset');
+constfirst=this[offset];
+constlast=this[offset+7];
+if(first===undefined||last===undefined)
+boundsError(offset,this.length-8);
+
+constval=(first<<24)+// Overflow
+this[++offset]*2**16+
+this[++offset]*2**8+
+this[++offset];
+return(BigInt(val)<<32n)+
+BigInt(this[++offset]*2**24+
+this[++offset]*2**16+
+this[++offset]*2**8+
+last);
+}
+
 functionreadUIntLE(offset,byteLength){
 if(byteLength===6)
 returnreadUInt48LE(this,offset);
@@ -454,6 +530,68 @@ function readDoubleForwards(offset = 0){
 }
 
 // Write integers.
+functionwriteBigU_Int64LE(buf,value,offset,min,max){
+checkInt(value,min,max,buf,offset,7);
+
+letlo=Number(value&0xffffffffn);
+buf[offset++]=lo;
+lo=lo>>8;
+buf[offset++]=lo;
+lo=lo>>8;
+buf[offset++]=lo;
+lo=lo>>8;
+buf[offset++]=lo;
+lethi=Number(value>>32n&0xffffffffn);
+buf[offset++]=hi;
+hi=hi>>8;
+buf[offset++]=hi;
+hi=hi>>8;
+buf[offset++]=hi;
+hi=hi>>8;
+buf[offset++]=hi;
+returnoffset;
+}
+
+functionwriteBigUInt64LE(value,offset=0){
+returnwriteBigU_Int64LE(this,value,offset,0n,0xffffffffffffffffn);
+}
+
+functionwriteBigU_Int64BE(buf,value,offset,min,max){
+checkInt(value,min,max,buf,offset,7);
+
+letlo=Number(value&0xffffffffn);
+buf[offset+7]=lo;
+lo=lo>>8;
+buf[offset+6]=lo;
+lo=lo>>8;
+buf[offset+5]=lo;
+lo=lo>>8;
+buf[offset+4]=lo;
+lethi=Number(value>>32n&0xffffffffn);
+buf[offset+3]=hi;
+hi=hi>>8;
+buf[offset+2]=hi;
+hi=hi>>8;
+buf[offset+1]=hi;
+hi=hi>>8;
+buf[offset]=hi;
+returnoffset+8;
+}
+
+functionwriteBigUInt64BE(value,offset=0){
+returnwriteBigU_Int64BE(this,value,offset,0n,0xffffffffffffffffn);
+}
+
+functionwriteBigInt64LE(value,offset=0){
+returnwriteBigU_Int64LE(
+this,value,offset,-0x8000000000000000n,0x7fffffffffffffffn);
+}
+
+functionwriteBigInt64BE(value,offset=0){
+returnwriteBigU_Int64BE(
+this,value,offset,-0x8000000000000000n,0x7fffffffffffffffn);
+}
+
 functionwriteUIntLE(value,offset=0,byteLength){
 if(byteLength===6)
 returnwriteU_Int48LE(this,value,offset,0,0xffffffffffff);
@@ -773,6 +911,14 @@ module.exports ={
  setupBufferJS,
 // Container to export all read write functions.
 readWrites: {
+ readBigUInt64LE,
+ readBigUInt64BE,
+ readBigInt64LE,
+ readBigInt64BE,
+ writeBigUInt64LE,
+ writeBigUInt64BE,
+ writeBigInt64LE,
+ writeBigInt64BE,
  readUIntLE,
  readUInt32LE,
  readUInt16LE,

test/parallel/test-buffer-bigint64.js

@@ -0,0 +1,51 @@
+'use strict';
+require('../common');
+constassert=require('assert');
+
+constbuf=Buffer.allocUnsafe(8);
+
+['LE','BE'].forEach(function(endianness){
+// Should allow simple BigInts to be written and read
+letval=123456789n;
+buf['writeBigInt64'+endianness](val,0);
+letrtn=buf['readBigInt64'+endianness](0);
+assert.strictEqual(val,rtn);
+
+// Should allow INT64_MAX to be written and read
+val=0x7fffffffffffffffn;
+buf['writeBigInt64'+endianness](val,0);
+rtn=buf['readBigInt64'+endianness](0);
+assert.strictEqual(val,rtn);
+
+// Should read and write a negative signed 64-bit integer
+val=-123456789n;
+buf['writeBigInt64'+endianness](val,0);
+assert.strictEqual(val,buf['readBigInt64'+endianness](0));
+
+// Should read and write an unsigned 64-bit integer
+val=123456789n;
+buf['writeBigUInt64'+endianness](val,0);
+assert.strictEqual(val,buf['readBigUInt64'+endianness](0));
+
+// Should throw a RangeError upon INT64_MAX+1 being written
+assert.throws(function(){
+constval=0x8000000000000000n;
+buf['writeBigInt64'+endianness](val,0);
+},RangeError);
+
+// Should throw a RangeError upon UINT64_MAX+1 being written
+assert.throws(function(){
+constval=0x10000000000000000n;
+buf['writeBigUInt64'+endianness](val,0);
+},RangeError);
+
+// Should throw a TypeError upon invalid input
+assert.throws(function(){
+buf['writeBigInt64'+endianness]('bad',0);
+},TypeError);
+
+// Should throw a TypeError upon invalid input
+assert.throws(function(){
+buf['writeBigUInt64'+endianness]('bad',0);
+},TypeError);
+});