# Replace
> Replace search occurrences with a replacement string.
## Usage
```javascript
var replace = require( '@stdlib/string/replace' );
```
#### replace( str, search, newval )
Replaces search occurrences with a replacement `string`.
```javascript
var out = replace( 'beep', 'e', 'o' );
// returns 'boop'
```
If provided a `function` as the [third argument][replacer], the function is invoked for each match, and the function's return value is used as the replacement `string`.
```javascript
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`][mdn]. When provided a `string` as the `search` value, the function replaces **all** occurrences. To remove only the first match, use a regular expression.
```javascript
var out = replace( 'beep', /e/, 'o' );
// returns 'boep'
```
## Examples
```javascript
var capitalize = require( '@stdlib/string/capitalize' );
var replace = require( '@stdlib/string/replace' );
var out;
var str;
out = replace( 'beep', 'e', 'o' );
// returns 'boop'
out = replace( 'Hello World', /world/i, 'Mr. President' );
// returns 'Hello Mr. President'
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'
function replacer( match, p1 ) {
return capitalize( p1 );
}
```
* * *
## CLI
### Usage
```text
Usage: replace [options] [] --search= --newval=
Options:
-h, --help Print this message.
-V, --version Print the package version.
--search string Search string.
--newval string Replacement string.
```
### Examples
```bash
$ replace --search='/[eo]/' --newval=a beep
baap
```
To use as a [standard stream][standard-streams],
```bash
$ echo -n 'boop' | replace --search='o' newval='e'
beep
```
[mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace
[replacer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_function_as_a_parameter
[standard-streams]: https://en.wikipedia.org/wiki/Standard_streams