Skip to content

unique-by-hash

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

unique-by-hash

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
benchmark
benchmark
 
 
docs
docs
 
 
examples
examples
 
 
lib
lib
 
 
test
test
 
 
README.md
README.md
 
 
package.json
package.json
 
 

README.md

iterUniqueByHash

Create an iterator which returns unique values according to a hash function.

Usage

var iterUniqueByHash = require( '@stdlib/iter/unique-by-hash' );

iterUniqueByHash( iterator, hashFcn[, thisArg] )

Returns an iterator which returns unique values according to a hash function.

var array2iterator = require( '@stdlib/array/to-iterator' );

function hashFcn( v ) {
    return v;
}

var src = array2iterator( [ 2, 1, 1, 2, 4, 3, 4, 3 ] );

var it = iterUniqueByHash( src, hashFcn );
// returns <Object>

var v = it.next().value;
// returns 2

v = it.next().value;
// returns 1

v = it.next().value;
// returns 4

v = it.next().value;
// returns 3

var bool = it.next().done;
// returns true

The returned iterator protocol-compliant object has the following properties:

  • next: function which returns an iterator protocol-compliant object containing the next iterated value (if one exists) assigned to a value property and a done property having a boolean value indicating whether the iterator is finished.
  • return: function which closes an iterator and returns a single (optional) argument in an iterator protocol-compliant object.

A hash function is provided one argument:

  • v: the current iterated value.

To set the execution context of the hash function, provide a thisArg.

var array2iterator = require( '@stdlib/array/to-iterator' );

function hashFcn( v ) {
    this.count += 1;
    return JSON.stringify( v );
}

var values = [
    { 'v': 2 },
    { 'v': 1 },
    { 'v': 1 },
    { 'v': 2 },
    { 'v': 4 },
    { 'v': 3 },
    { 'v': 4 },
    { 'v': 3 }
];

var src = array2iterator( values );

var ctx = {
    'count': 0
};

var it = iterUniqueByHash( src, hashFcn, ctx );
// returns <Object>

var v = it.next().value;
// returns { 'v': 2 }

v = it.next().value;
// returns { 'v': 1 }

v = it.next().value;
// returns { 'v': 4 }

v = it.next().value;
// returns { 'v': 3 }

var bool = it.next().done;
// returns true

bool = ( ctx.count > 0 );
// returns true

Notes

  • A returned iterator internally buffers unique hashes and, thus, has O(N) memory requirements.
  • An iterated value is considered "unique" if a hash function returns a unique hash value for that iterated value. Beware that this may result in unexpected behavior. Namely, only the first iterated value mapping to a particular hash function result is returned, even if subsequent values, while mapping to the same hash, are different. Accordingly, iteration order does matter.
  • If an environment supports Symbol.iterator and a provided iterator is iterable, the returned iterator is iterable.

Examples

var discreteUniform = require( '@stdlib/random/iter/discrete-uniform' );
var iterMap = require( '@stdlib/iter/map' );
var iterUniqueByHash = require( '@stdlib/iter/unique-by-hash' );

function mapFcn( v ) {
    return {
        'v': v
    };
}

function hashFcn( v ) {
    return JSON.stringify( v );
}

// Create a seeded iterator which can generate 1000 pseudorandom numbers:
var rand = discreteUniform( 1, 10, {
    'seed': 1234,
    'iter': 1000
});

// Create an iterator which maps each number to an object:
var miter = iterMap( rand, mapFcn );

// Create an iterator which returns unique (object) values:
var it = iterUniqueByHash( miter, hashFcn );

// Perform manual iteration...
var v;
while ( true ) {
    v = it.next();
    if ( v.done ) {
        break;
    }
    console.log( v.value );
}

See Also