replace

Replace search occurrences with a replacement string.

Usage

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

replace( str, search, newval )

Replaces search occurrences with a replacement string.

var out = replace( 'beep', 'e', '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 has one notable difference from String.prototype.replace. When provided a string as the search value, the function replaces all occurrences. To remove only the first match, use a regular expression.
```
var out = replace( 'beep', /e/, 'o' );
// returns 'boep'
```

Examples

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

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

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'

CLI

Usage

Usage: replace [options] [<string>] --search=<string> --newval=<string>

Options:

  -h,    --help                Print this message.
  -V,    --version             Print the package version.
         --search string       Search string.
         --newval string       Replacement string.
         --split sep           Delimiter for stdin data. Default: '/\\r?\\n/'.

Notes

If the split separator is a regular expression, ensure that the split option is either properly escaped or enclosed in quotes.

# Not escaped...
$ echo -n $'foo\nbar' | replace --search='o' --newval='e' --split /\r?\n/

# Escaped...
$ echo -n $'foo\nbar' | replace --search='o' --newval='e' --split /\\r?\\n/

The implementation ignores trailing delimiters.

Examples

$ replace --search='/[eo]/' --newval=a beep
baap

To use as a standard stream,

$ echo -n 'boop' | replace --search='o' --newval='e'
beep

By default, when used as a standard stream, the implementation assumes newline-delimited data. To specify an alternative delimiter, set the split option.

$ echo -n 'boop\tfoo' | replace --search='o' --newval='e' --split '\t'
beep
fee