forEach
Invokes a function for each character in a string.
Usage
var forEach = require( '@stdlib/string/for-each' );
forEach( str, [options,] clbk[, thisArg ] )
Invokes a function for each character in a string.
function log( value, index ) {
console.log( '%d: %s', index, value );
}
forEach( 'Beep!', log );
/* =>
0: B
1: e
2: e
3: p
4: !
*/
The invoked function is provided three arguments:
- value: character.
- index: starting character index.
- str: input string.
To set the function execution context, provide a thisArg.
function clbk() {
this.count += 1;
}
var str = 'Hello, world!';
var ctx = {
'count': 0
};
forEach( str, clbk, ctx );
var bool = ( str.length === ctx.count );
// returns true
The function supports the following options:
mode: type of characters over which to iterate. Must be one of the following:
'grapheme': grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji).'code_point': Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics).'code_unit': UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets).
Default:
'grapheme'.
Notes
- By default, the function assumes the general case in which an input string may contain an arbitrary number of grapheme clusters. This assumption comes with a performance cost. Accordingly, if an input string is known to only contain visual characters of a particular type (e.g., only alphanumeric), one can achieve better performance by specifying the appropriate
modeoption.
Examples
var forEach = require( '@stdlib/string/for-each' );
function log( value, index ) {
console.log( '%d: %s', index, value );
}
forEach( 'presidential election', log );
forEach( 'Iñtërnâtiônàlizætiøn', log );
forEach( '🌷🍕', log );
forEach( '\uD834\uDD1E', log );