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 mode option.

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 );

---

See Also

• @stdlib/utils/for-each: invoke a function for each element in a collection.