replace

Replace search occurrences with a replacement string.

Usage

var replace = require( '@stdlib/string/base/replace' );

replace( str, search, newval )

Replaces search occurrences with a replacement string.

var out = replace( 'beep', /e/g, 'o' );
// returns 'boop'

If provided a function as the third argument, the function is invoked for each match, and the function's return value is used as the replacement string.

function replacer( match, p1 ) {
    return '/' + p1 + '/';
}
var str = 'Oranges and lemons';
var out = replace( str, /([^\s]+)/gi, replacer );
// returns '/Oranges/ /and/ /lemons/'

Notes

The function assumes that the search argument is a regular expression. Accordingly, the function should not be used as a general drop-in replacement for String.prototype.replace.

Examples

var capitalize = require( '@stdlib/string/base/capitalize' );
var replace = require( '@stdlib/string/base/replace' );

var out = replace( 'Hello World', /world/i, 'Mr. President' );
// returns 'Hello Mr. President'

function replacer( match, p1 ) {
    return capitalize( p1 );
}
var str = 'Oranges and lemons say the bells of St. Clement\'s';
out = replace( str, /([^\s]*)/gi, replacer );
// returns 'Oranges And Lemons Say The Bells Of St. Clement\'s'