graphemeClusters2iterator
Create an iterator which iterates over grapheme clusters.
Usage
var graphemeClusters2iterator = require( '@stdlib/string/to-grapheme-cluster-iterator' );
graphemeClusters2iterator( src[, mapFcn[, thisArg]] )
Returns an iterator which iterates over each grapheme cluster in a string.
var iter = graphemeClusters2iterator( '🌷🍕' );
var v = iter.next().value;
// returns '🌷'
v = iter.next().value;
// returns '🍕'
var bool = iter.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
valueproperty and adoneproperty having abooleanvalue indicating whether the iterator is finished. - return: function which closes an iterator and returns a single (optional) argument in an iterator protocol-compliant object.
To invoke a function for each src value, provide a callback function.
function fcn( v ) {
return v + v;
}
var it = graphemeClusters2iterator( 'beep', fcn );
// returns <Object>
var v = it.next().value;
// returns 'bb'
v = it.next().value;
// returns 'ee'
v = it.next().value;
// returns 'ee'
// ...
The invoked function is provided three arguments:
- value: grapheme cluster.
- index: iterated value index.
- src: source string.
function fcn( v, i ) {
return v + i;
}
var it = graphemeClusters2iterator( 'bar', fcn );
// returns <Object>
var v = it.next().value;
// returns 'b0'
v = it.next().value;
// returns 'a1'
v = it.next().value;
// returns 'r2'
// ...
To set the callback function execution context, provide a thisArg.
function fcn( v ) {
this.count += 1;
return v;
}
var ctx = {
'count': 0
};
var it = graphemeClusters2iterator( '🌷🍕', fcn, ctx );
// returns <Object>
var v = it.next().value;
// returns '🌷'
v = it.next().value;
// returns '🍕'
var count = ctx.count;
// returns 2
Notes
- If an environment supports
Symbol.iterator, the returned iterator is iterable. - In environments supporting
Symbol.iterator, the function explicitly does not invoke a string's@@iteratormethod, regardless of whether this method is defined. To convert a string to an implementation defined iterator, invoke this method directly.
Examples
var graphemeClusters2iterator = require( '@stdlib/string/to-grapheme-cluster-iterator' );
function repeat( str ) {
return str + str;
}
// Create an iterator which iterates over grapheme clusters:
var it = graphemeClusters2iterator( 'Iñtërnâtiônàlizætiøn', repeat );
// Perform manual iteration...
var v;
while ( true ) {
v = it.next();
if ( v.done ) {
break;
}
console.log( v.value );
}