# rescape
[![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url]
> Escape a [regular expression][mdn-regexp] string or pattern.
## Installation
```bash
npm install @stdlib/utils-escape-regexp-string
```
## Usage
```javascript
var rescape = require( '@stdlib/utils-escape-regexp-string' );
```
#### rescape( str )
Escapes a [regular expression][mdn-regexp] `string` or pattern.
```javascript
var str = rescape( '/[A-Z]*/' );
// returns '/\\[A\\-Z\\]\\*/'
str = rescape( '[A-Z]*' );
// returns '\\[A\\-Z\\]\\*'
```
If provided a value which is not a primitive `string`, the function **throws** a `TypeError`.
```javascript
try {
rescape( null );
// throws an error...
} catch ( err ) {
console.error( err );
}
```
- The following characters have special meaning inside of regular expressions and need to be escaped in case the characters should be treated literally:
| description | value |
| ------------- | -------- |
| Backslash | `\` |
| Braces | `{ }` |
| Brackets | `[ ]` |
| Caret | `^` |
| Dollar Sign | `$` |
| Forward Slash | `/` |
| Asterisk | `*` |
| Parentheses | `( )` |
| Period | `.` |
| Plus Sign | `+` |
| Vertical Bar | `|` |
| Question Mark | `?` |
## Examples
```javascript
var rescape = require( '@stdlib/utils-escape-regexp-string' );
var out = rescape( '/beep/' );
// returns '/beep/'
out = rescape( 'beep' );
// returns 'beep'
out = rescape( '/[A-Z]*/' );
// returns '/\\[A\\-Z\\]\\*/'
out = rescape( '[A-Z]*' );
// returns '\\[A\\-Z\\]\\*'
out = rescape( '/\\\//ig' );
// returns '/\\\\\\\//ig'
out = rescape( '\\\/' );
// returns '\\\\\\\/'
out = rescape( '/[A-Z]{0,}/' );
// returns '/\\[A\\-Z\\]\\{0,\\}/'
out = rescape( '[A-Z]{0,}' );
// returns '\\[A\\-Z\\]\\{0,\\}'
out = rescape( '/^boop$/' );
// returns '/\\^boop\\$/'
out = rescape( '^boop$' );
// returns '\\^boop\\$'
out = rescape( '/(?:.*)/' );
// returns '/\\(\\?:\\.\\*\\)/'
out = rescape( '(?:.*)' );
// returns '\\(\\?:\\.\\*\\)'
out = rescape( '/(?:beep|boop)/' );
// returns '/\\(\\?:beep\\|boop\\)/'
out = rescape( '(?:beep|boop)' );
// returns '\\(\\?:beep\\|boop\\)'
```
* * *
## Notice
This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.
For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib].
#### Community
[![Chat][chat-image]][chat-url]
---
## License
See [LICENSE][stdlib-license].
## Copyright
Copyright © 2016-2022. The Stdlib [Authors][stdlib-authors].
[npm-image]: http://img.shields.io/npm/v/@stdlib/utils-escape-regexp-string.svg
[npm-url]: https://npmjs.org/package/@stdlib/utils-escape-regexp-string
[test-image]: https://github.com/stdlib-js/utils-escape-regexp-string/actions/workflows/test.yml/badge.svg?branch=v0.0.9
[test-url]: https://github.com/stdlib-js/utils-escape-regexp-string/actions/workflows/test.yml?query=branch:v0.0.9
[coverage-image]: https://img.shields.io/codecov/c/github/stdlib-js/utils-escape-regexp-string/main.svg
[coverage-url]: https://codecov.io/github/stdlib-js/utils-escape-regexp-string?branch=main
[chat-image]: https://img.shields.io/gitter/room/stdlib-js/stdlib.svg
[chat-url]: https://gitter.im/stdlib-js/stdlib/
[stdlib]: https://github.com/stdlib-js/stdlib
[stdlib-authors]: https://github.com/stdlib-js/stdlib/graphs/contributors
[umd]: https://github.com/umdjs/umd
[es-module]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
[deno-url]: https://github.com/stdlib-js/utils-escape-regexp-string/tree/deno
[umd-url]: https://github.com/stdlib-js/utils-escape-regexp-string/tree/umd
[esm-url]: https://github.com/stdlib-js/utils-escape-regexp-string/tree/esm
[branches-url]: https://github.com/stdlib-js/utils-escape-regexp-string/blob/main/branches.md
[stdlib-license]: https://raw.githubusercontent.com/stdlib-js/utils-escape-regexp-string/main/LICENSE
[mdn-regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions