# Percent-encoding
> [Percent-encode][percent-encoding] a [UTF-16][utf-16] encoded string according to [RFC 3986][rfc-3986-percent-encoding].
## Usage
```javascript
var percentEncode = require( '@stdlib/string/percent-encode' );
```
#### percentEncode( str )
[Percent-encodes][percent-encoding] a [UTF-16][utf-16] encoded string according to [RFC 3986][rfc-3986-percent-encoding].
```javascript
var out = percentEncode( '☃' );
// returns '%E2%98%83'
```
## Notes
- The function [percent-encodes][percent-encoding] an **entire** `string`. Hence, if provided a URI, the function [percent-encodes][percent-encoding] the entire URI.
```javascript
var out = percentEncode( 'https://en.wikipedia.org/wiki/Mode_(statistics)' );
// returns 'https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FMode_%28statistics%29'
```
To [percent-encode][percent-encoding] a URI, split the URI into separate components, [percent-encode][percent-encoding] relevant components, and then reassemble.
## Examples
```javascript
var percentEncode = require( '@stdlib/string/percent-encode' );
var values;
var out;
var i;
values = [
'Ladies + Gentlemen',
'An encoded string!',
'Dogs, Cats & Mice',
'☃',
'æ',
'𐐷'
];
for ( i = 0; i < values.length; i++ ) {
out = percentEncode( values[ i ] );
console.log( '%s: %s', values[ i ], out );
}
```
* * *
## CLI
### Usage
```text
Usage: percent-encode [options] []
Options:
-h, --help Print this message.
-V, --version Print the package version.
```
### Examples
```bash
$ percent-encode ☃
%E2%98%83
```
To use as a [standard stream][standard-streams],
```bash
$ echo -n '☃' | percent-encode
%E2%98%83
```
[percent-encoding]: https://en.wikipedia.org/wiki/Percent-encoding
[rfc-3986-percent-encoding]: https://tools.ietf.org/html/rfc3986#section-2.1
[utf-16]: https://en.wikipedia.org/wiki/UTF-16
[standard-streams]: https://en.wikipedia.org/wiki/Standard_streams