jasonlotito / buckets

Buckets for JavaScript

Buckets

Buckets is a simple library for creating and using buckets. You simply give your buckets keys and then assign them callbacks which act as testers. Each time you add a value, we loop through all your testers, passing in the value, and add that value to any bucket that the value passes the test for.

TOC

• Buckets
  • This is the bucket_creator function
  • #addBucket
  • #addBuckets
  • #add
  • #addList
  • #empty
  • #deleteBucket
  • #getBucket
  • #whichBuckets

Buckets

This is the bucket_creator function

It returns a creator, making it easy to create tests.

bucket_creator = function(min, max){
  return function(number){
    return min <= number && number <= max;
  };
};

#addBucket

Will allow you to add a bucket to it..

var buckets = new Buckets();
buckets.addBucket('test bucket', bucket_creator(0,10));
assert.ok(buckets.buckets['test bucket']);

Will allow you to add more than one bucket.

var buckets = new Buckets();
buckets.addBucket('bucket one', bucket_creator(0,10));
assert.ok(buckets.buckets['bucket one']);
assert.ok(!buckets.buckets['bucket two']);
buckets.addBucket('bucket two', bucket_creator(11,20));
assert.ok(buckets.buckets['bucket two']);

Will override an existing bucket.

var buckets = new Buckets();
buckets.addBucket('bucket one', bucket_creator(0,10));
assert.ok(buckets.buckets['bucket one']);
buckets.addBucket('bucket one', bucket_creator(10,20));
assert.ok(buckets.buckets['bucket one']);
// This should not get added
buckets.add(5);
assert.equal(0, buckets.buckets['bucket one'].length);
// This will get added
buckets.add(15);
assert.equal(1, buckets.buckets['bucket one'].length);

#addBuckets

Will allow you to add a list of buckets.

var buckets = new Buckets();
buckets.addBuckets([
  {name: 'bucket one', test: bucket_creator(0,10)},
  {name: 'bucket two', test: bucket_creator(11,20)},
  {name: 'bucket three', test: bucket_creator(21,30)}
]);
assert.ok(buckets.buckets['bucket one']);
assert.ok(buckets.buckets['bucket two']);
assert.ok(buckets.buckets['bucket three']);

#add

Will allow you to add data to buckets based on the test provided with the bucket.

buckets.add(5);
buckets.add(15);
buckets.add(16);
buckets.add(17);
assert.equal(1, buckets.buckets['bucket one'].length);
assert.equal(3, buckets.buckets['bucket two'].length);
assert.equal(0, buckets.buckets['bucket three'].length);

Will add the same value multiple times.

buckets.add(5);
buckets.add(5);
buckets.add(15);
buckets.add(15);
buckets.add(27);
buckets.add(27);
buckets.add(27);
assert.equal(2, buckets.buckets['bucket one'].length);
assert.equal(2, buckets.buckets['bucket two'].length);
assert.equal(3, buckets.buckets['bucket three'].length);

Will stop early by default given multiple available buckets.

buckets.addBucket('bucket one and a half', bucket_creator(5,15));
// This should only appear in bucket one
buckets.add(7);
assert.equal(1, buckets.buckets['bucket one'].length);
assert.equal(0, buckets.buckets['bucket one and a half'].length);

Will place in multiple buckets if the option stop_on_match is false.

var buckets = new Buckets({stop_on_match:false});
buckets.addBuckets([
  {name: 'bucket one', test: bucket_creator(0,10)},
  {name: 'bucket one and a half', test: bucket_creator(5, 15)},
  {name: 'bucket two', test: bucket_creator(11,20)},
  {name: 'bucket three', test: bucket_creator(21,30)}
]);
// This should appear in both buckets
buckets.add(7);
assert.equal(1, buckets.buckets['bucket one'].length);
assert.equal(1, buckets.buckets['bucket one and a half'].length);

Will return the buckets that the data was added to.

var buckets = new Buckets({stop_on_match: false});
buckets.addBuckets([
  {name: 'bucket one', test: bucket_creator(0, 10)},
  {name: 'bucket two', test: bucket_creator(11, 20)},
  {name: 'bucket three', test: bucket_creator(21, 30)}
]);
assert.equal('bucket one', buckets.add(5).pop());
buckets.addBucket('bucket one and a half', bucket_creator(5, 15));
assert.equal(2, buckets.add(5).length);
// Buckets are returned in the order they are checked, which is the order they are added
assert.equal('bucket one and a half', buckets.add(5)[1]);

#addList

Will add the same value multiple times.

buckets.addList([5, 5, 15, 15, 27, 27, 27]);
assert.equal(2, buckets.buckets['bucket one'].length);
assert.equal(2, buckets.buckets['bucket two'].length);
assert.equal(3, buckets.buckets['bucket three'].length);

#empty

Will empty all buckets of any data.

buckets.add(5);
buckets.add(15);
buckets.add(16);
buckets.add(17);
assert.equal(1, buckets.buckets['bucket one'].length);
assert.equal(3, buckets.buckets['bucket two'].length);
assert.equal(0, buckets.buckets['bucket three'].length);
buckets.empty();
assert.equal(0, buckets.buckets['bucket one'].length);
assert.equal(0, buckets.buckets['bucket two'].length);
assert.equal(0, buckets.buckets['bucket three'].length);

#deleteBucket

Will remove a bucket.

buckets.deleteBucket('bucket two');
buckets.add(5);
buckets.add(15);
assert.equal(1, buckets.buckets['bucket one'].length);
assert.ok(!buckets.buckets['bucket two']);

#getBucket

Will return a bucket's contents..

var bucketOne = buckets.getBucket("bucket one")
assert.equal(4, bucketOne.length);
assert.equal(0, bucketOne.indexOf(5));

Will return an empty array if the bucket doesn't exist.

assert.equal(0, buckets.getBucket("I don't exist").length);

#whichBuckets

Will put determine with bucket the data should be put in and return the name of the buckets.

// One bucket returned
assert.equal('bucket two', buckets.whichBucket(17));
assert.equal(1, buckets.whichBucket(17).length);
// Multiple buckets returned
var bucketList = buckets.whichBucket(19);
assert.equal(2, bucketList.length);
assert.ok(bucketList.indexOf('bucket two') >= 0);
assert.ok(bucketList.indexOf('bucket two and a half') >= 0);

License

The MIT License (MIT)

Copyright (c) 2014 Jason Lotito

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.