buffer: add Buffer.prototype.compare by offset

Adds additional `targetStart`, `targetEnd`, `sourceStart,
and `sourceEnd` arguments to `Buffer.prototype.compare`
to allow comparison of sub-ranges of two Buffers without
requiring Buffer.prototype.slice()
Fixes: #521
PR-URL: #5880
Reviewed-By: Trevor Norris <trev.norris@gmail.com>

Author: jasnell

benchmark/buffers/buffer-compare-offset.js

@@ -0,0 +1,58 @@
+'use strict';
+constcommon=require('../common.js');
+constv8=require('v8');
+
+constbench=common.createBenchmark(main,{
+method: ['offset','slice'],
+size: [16,512,1024,4096,16386],
+millions: [1]
+});
+
+functioncompareUsingSlice(b0,b1,len,iter){
+
+// Force optimization before starting the benchmark
+Buffer.compare(b0.slice(1,len),b1.slice(1,len));
+v8.setFlagsFromString('--allow_natives_syntax');
+eval('%OptimizeFunctionOnNextCall(Buffer.compare)');
+eval('%OptimizeFunctionOnNextCall(b0.slice)');
+eval('%OptimizeFunctionOnNextCall(b1.slice)');
+Buffer.compare(b0.slice(1,len),b1.slice(1,len));
+doCompareUsingSlice(b0,b1,len,iter);
+}
+
+functiondoCompareUsingSlice(b0,b1,len,iter){
+vari;
+bench.start();
+for(i=0;i<iter;i++)
+Buffer.compare(b0.slice(1,len),b1.slice(1,len));
+bench.end(iter/1e6);
+}
+
+functioncompareUsingOffset(b0,b1,len,iter){
+len=len+1;
+// Force optimization before starting the benchmark
+b0.compare(b1,1,len,1,len);
+v8.setFlagsFromString('--allow_natives_syntax');
+eval('%OptimizeFunctionOnNextCall(b0.compare)');
+b0.compare(b1,1,len,1,len);
+doCompareUsingOffset(b0,b1,len,iter);
+}
+
+functiondoCompareUsingOffset(b0,b1,len,iter){
+vari;
+bench.start();
+for(i=0;i<iter;i++)
+b0.compare(b1,1,len,1,len);
+bench.end(iter/1e6);
+}
+
+functionmain(conf){
+constiter=(conf.millions>>>0)*1e6;
+constsize=(conf.size>>>0);
+constmethod=conf.method==='slice' ?
+compareUsingSlice : compareUsingOffset;
+method(Buffer.alloc(size,'a'),
+Buffer.alloc(size,'b'),
+size>>1,
+iter);
+}

doc/api/buffer.markdown

@@ -657,18 +657,26 @@ console.log(buf.toString('ascii'));
 // Prints: Node.js
 ```
 
-### buf.compare(otherBuffer)
-
-*`otherBuffer` {Buffer}
+### buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])
+
+*`target` {Buffer}
+*`targetStart` {Integer} The offset within `target` at which to begin
+ comparison. default = `0`.
+*`targetEnd` {Integer} The offset with `target` at which to end comparison.
+ Ignored when `targetStart` is `undefined`. default = `target.byteLength`.
+*`sourceStart` {Integer} The offset within `buf` at which to begin comparison.
+ Ignored when `targetStart` is `undefined`. default = `0`
+*`sourceEnd` {Integer} The offset within `buf` at which to end comparison.
+ Ignored when `targetStart` is `undefined`. default = `buf.byteLength`.
 * Return: {Number}
 
 Compares two Buffer instances and returns a number indicating whether `buf`
-comes before, after, or is the same as the `otherBuffer` in sort order.
+comes before, after, or is the same as the `target` in sort order.
 Comparison is based on the actual sequence of bytes in each Buffer.
 
-*`0` is returned if `otherBuffer` is the same as `buf`
-*`1` is returned if `otherBuffer` should come *before*`buf` when sorted.
-*`-1` is returned if `otherBuffer` should come *after*`buf` when sorted.
+*`0` is returned if `target` is the same as `buf`
+*`1` is returned if `target` should come *before*`buf` when sorted.
+*`-1` is returned if `target` should come *after*`buf` when sorted.
 
 ```js
 constbuf1=Buffer.from('ABC');
@@ -690,6 +698,25 @@ console.log(buf2.compare(buf3));
 // produces sort order [buf1, buf3, buf2]
 ```
 
+The optional `targetStart`, `targetEnd`, `sourceStart`, and `sourceEnd`
+arguments can be used to limit the comparison to specific ranges within the two
+`Buffer` objects.
+
+```js
+constbuf1=Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+constbuf2=Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4]);
+
+console.log(buf1.compare(buf2, 5, 9, 0, 4));
+// Prints: 0
+console.log(buf1.compare(buf2, 0, 6, 4));
+// Prints: -1
+console.log(buf1.compare(buf2, 5, 6, 5));
+// Prints: 1
+```
+
+A `RangeError` will be thrown if: `targetStart < 0`, `sourceStart < 0`,
+`targetEnd > target.byteLength` or `sourceEnd > source.byteLength`.
+
 ### buf.copy(targetBuffer[, targetStart[, sourceStart[, sourceEnd]]])
 
 *`targetBuffer` {Buffer} Buffer to copy into

lib/buffer.js

@@ -513,15 +513,44 @@ Buffer.prototype.inspect = function inspect() {
 return'<'+this.constructor.name+' '+str+'>';
 };
 
+Buffer.prototype.compare=functioncompare(target,
+start,
+end,
+thisStart,
+thisEnd){
 
-Buffer.prototype.compare=functioncompare(b){
-if(!(binstanceofBuffer))
+if(!(targetinstanceofBuffer))
 thrownewTypeError('Argument must be a Buffer');
 
-if(this===b)
+if(start===undefined)
+start=0;
+if(end===undefined)
+end=target ? target.length : 0;
+if(thisStart===undefined)
+thisStart=0;
+if(thisEnd===undefined)
+thisEnd=this.length;
+
+if(start<0||
+end>target.length||
+thisStart<0||
+thisEnd>this.length){
+thrownewRangeError('out of range index');
+}
+
+if(thisStart>=thisEnd&&start>=end)
 return0;
+if(thisStart>=thisEnd)
+return-1;
+if(start>=end)
+return1;
+
+start>>>=0;
+end>>>=0;
+thisStart>>>=0;
+thisEnd>>>=0;
 
-returnbinding.compare(this,b);
+returnbinding.compareOffset(this,target,start,thisStart,end,thisEnd);
 };
 
 functionslowIndexOf(buffer,val,byteOffset,encoding){

src/node_buffer.cc

@@ -880,6 +880,62 @@ void ByteLengthUtf8(const FunctionCallbackInfo<Value> &args) {
  args.GetReturnValue().Set(args[0].As<String>()->Utf8Length());
 }
 
+// Normalize val to be an integer in the range of [1, -1] since
+// implementations of memcmp() can vary by platform.
+staticintnormalizeCompareVal(int val, size_t a_length, size_t b_length) {
+if (val == 0) {
+if (a_length > b_length)
+return1;
+elseif (a_length < b_length)
+return -1;
+ } else {
+if (val > 0)
+return1;
+else
+return -1;
+ }
+return val;
+}
+
+voidCompareOffset(const FunctionCallbackInfo<Value> &args) {
+ Environment* env = Environment::GetCurrent(args);
+
+THROW_AND_RETURN_UNLESS_BUFFER(env, args[0]);
+THROW_AND_RETURN_UNLESS_BUFFER(env, args[1]);
+SPREAD_ARG(args[0], ts_obj);
+SPREAD_ARG(args[1], target);
+
+size_t target_start;
+size_t source_start;
+size_t source_end;
+size_t target_end;
+
+CHECK_NOT_OOB(ParseArrayIndex(args[2], 0, &target_start));
+CHECK_NOT_OOB(ParseArrayIndex(args[3], 0, &source_start));
+CHECK_NOT_OOB(ParseArrayIndex(args[4], target_length, &target_end));
+CHECK_NOT_OOB(ParseArrayIndex(args[5], ts_obj_length, &source_end));
+
+if (source_start > ts_obj_length)
+return env->ThrowRangeError("out of range index");
+if (target_start > target_length)
+return env->ThrowRangeError("out of range index");
+
+CHECK_LE(source_start, source_end);
+CHECK_LE(target_start, target_end);
+
+size_t to_cmp = MIN(MIN(source_end - source_start,
+ target_end - target_start),
+ ts_obj_length - source_start);
+
+int val = normalizeCompareVal(to_cmp > 0 ?
+memcmp(ts_obj_data + source_start,
+ target_data + target_start,
+ to_cmp) : 0,
+ source_end - source_start,
+ target_end - target_start);
+
+ args.GetReturnValue().Set(val);
+}
 
 voidCompare(const FunctionCallbackInfo<Value> &args) {
  Environment* env = Environment::GetCurrent(args);
@@ -891,22 +947,9 @@ void Compare(const FunctionCallbackInfo<Value> &args) {
 
 size_t cmp_length = MIN(obj_a_length, obj_b_length);
 
-int val = cmp_length > 0 ? memcmp(obj_a_data, obj_b_data, cmp_length) : 0;
-
-// Normalize val to be an integer in the range of [1, -1] since
-// implementations of memcmp() can vary by platform.
-if (val == 0) {
-if (obj_a_length > obj_b_length)
- val = 1;
-elseif (obj_a_length < obj_b_length)
- val = -1;
- } else {
-if (val > 0)
- val = 1;
-else
- val = -1;
- }
-
+int val = normalizeCompareVal(cmp_length > 0 ?
+memcmp(obj_a_data, obj_b_data, cmp_length) : 0,
+ obj_a_length, obj_b_length);
  args.GetReturnValue().Set(val);
 }
 
@@ -1182,6 +1225,7 @@ void Initialize(Local<Object> target,
 
  env->SetMethod(target, "byteLengthUtf8", ByteLengthUtf8);
  env->SetMethod(target, "compare", Compare);
+ env->SetMethod(target, "compareOffset", CompareOffset);
  env->SetMethod(target, "fill", Fill);
  env->SetMethod(target, "indexOfBuffer", IndexOfBuffer);
  env->SetMethod(target, "indexOfNumber", IndexOfNumber);

test/parallel/test-buffer-compare-offset.js

@@ -0,0 +1,63 @@
+'use strict';
+
+require('../common');
+constassert=require('assert');
+
+consta=Buffer.from([1,2,3,4,5,6,7,8,9,0]);
+constb=Buffer.from([5,6,7,8,9,0,1,2,3,4]);
+
+assert.equal(-1,a.compare(b));
+
+// Equivalent to a.compare(b).
+assert.equal(-1,a.compare(b,0));
+assert.equal(-1,a.compare(b,'0'));
+
+// Equivalent to a.compare(b).
+assert.equal(-1,a.compare(b,0,undefined,0));
+
+// Zero-length targer, return 1
+assert.equal(1,a.compare(b,0,0,0));
+assert.equal(1,a.compare(b,'0','0','0'));
+
+// Equivalent to Buffer.compare(a, b.slice(6, 10))
+assert.equal(1,a.compare(b,6,10));
+
+// Zero-length source, return -1
+assert.equal(-1,a.compare(b,6,10,0,0));
+
+// Equivalent to Buffer.compare(a.slice(4), b.slice(0, 5))
+assert.equal(1,a.compare(b,0,5,4));
+
+// Equivalent to Buffer.compare(a.slice(1), b.slice(5))
+assert.equal(1,a.compare(b,5,undefined,1));
+
+// Equivalent to Buffer.compare(a.slice(2), b.slice(2, 4))
+assert.equal(-1,a.compare(b,2,4,2));
+
+// Equivalent to Buffer.compare(a.slice(4), b.slice(0, 7))
+assert.equal(-1,a.compare(b,0,7,4));
+
+// Equivalent to Buffer.compare(a.slice(4, 6), b.slice(0, 7));
+assert.equal(-1,a.compare(b,0,7,4,6));
+
+// zero length target
+assert.equal(1,a.compare(b,0,null));
+
+// coerces to targetEnd == 5
+assert.equal(-1,a.compare(b,0,{valueOf: ()=>5}));
+
+// zero length target
+assert.equal(1,a.compare(b,Infinity,-Infinity));
+
+// zero length target because default for targetEnd <= targetSource
+assert.equal(1,a.compare(b,'0xff'));
+
+constoor=/outofrangeindex/;
+
+assert.throws(()=>a.compare(b,0,100,0),oor);
+assert.throws(()=>a.compare(b,0,1,0,100),oor);
+assert.throws(()=>a.compare(b,-1),oor);
+assert.throws(()=>a.compare(b,0,'0xff'),oor);
+assert.throws(()=>a.compare(b,0,Infinity),oor);
+assert.throws(()=>a.compare(b,-Infinity,Infinity),oor);
+assert.throws(()=>a.compare(),/ArgumentmustbeaBuffer/);