# ReplaceSymbol
> [Symbol][mdn-symbol] which provides a method for replacing substrings matched by the current object.
## Usage
```javascript
var ReplaceSymbol = require( '@stdlib/symbol/replace' );
```
#### ReplaceSymbol
[`symbol`][mdn-symbol] which provides a method for replacing substrings matched by the current object.
```javascript
var s = typeof ReplaceSymbol;
// e.g., returns 'symbol'
```
## Notes
- The [symbol][mdn-symbol] is only supported in environments which support [symbols][mdn-symbol]. In non-supporting environments, the value is `null`.
- When calling `String.prototype.replace` and `String.prototype.replaceAll` and the `pattern` argument is an object with a `[ReplaceSymbol]()` method, this method is called with the target string and replacement as arguments.
## Examples
```javascript
var defineProperty = require( '@stdlib/utils/define-property' );
var ReplaceSymbol = require( '@stdlib/symbol/replace' );
function replace( str, replacement ) {
return replacement;
}
var obj = {};
defineProperty( obj, ReplaceSymbol, {
'configurable': true,
'value': null
});
var str = 'beep';
console.log( str.replace( obj, 'boop' ) );
defineProperty( obj, ReplaceSymbol, {
'configurable': true,
'value': replace
});
console.log( str.replace( obj, 'boop' ) );
```
[mdn-symbol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol