1# wtf-8 [![Build status](https://travis-ci.org/mathiasbynens/wtf-8.svg?branch=master)](https://travis-ci.org/mathiasbynens/wtf-8) [![Dependency status](https://gemnasium.com/mathiasbynens/wtf-8.svg)](https://gemnasium.com/mathiasbynens/wtf-8)
  2
  3_wtf-8_ is a well-tested [WTF-8](https://simonsapin.github.io/wtf-8/) encoder/decoder written in JavaScript. WTF-8 is a superset of UTF-8: it can encode/decode any given Unicode code point, including those of (unpaired) surrogates. [Here’s an online demo.](https://mothereff.in/wtf-8)
  4
  5Feel free to fork if you see possible improvements!
  6
  7## Installation
  8
  9Via [npm](http://npmjs.org/):
 10
 11```bash
 12npm install wtf-8
 13```
 14
 15Via [Bower](http://bower.io/):
 16
 17```bash
 18bower install wtf-8
 19```
 20
 21Via [Component](https://github.com/component/component):
 22
 23```bash
 24component install mathiasbynens/wtf-8
 25```
 26
 27In a browser:
 28
 29```html
 30<script src="wtf-8.js"></script>
 31```
 32
 33In [Narwhal](http://narwhaljs.org/), [Node.js](http://nodejs.org/), and [RingoJS ≥ v0.8.0](http://ringojs.org/):
 34
 35```js
 36var wtf8 = require('wtf-8');
 37```
 38
 39In [Rhino](http://www.mozilla.org/rhino/):
 40
 41```js
 42load('wtf-8.js');
 43```
 44
 45Using an AMD loader like [RequireJS](http://requirejs.org/):
 46
 47```js
 48require(
 49  {
 50    'paths': {
 51      'wtf-8': 'path/to/wtf-8'
 52    }
 53  },
 54  ['wtf-8'],
 55  function(wtf8) {
 56    console.log(wtf8);
 57  }
 58);
 59```
 60
 61## API
 62
 63### `wtf8.encode(string)`
 64
 65Encodes any given JavaScript string (`string`) as WTF-8, and returns the WTF-8-encoded version of the string.
 66
 67```js
 68// U+00A9 COPYRIGHT SIGN; see http://codepoints.net/U+00A9
 69wtf8.encode('\xA9');
 70// → '\xC2\xA9'
 71// U+10001 LINEAR B SYLLABLE B038 E; see http://codepoints.net/U+10001
 72wtf8.encode('\uD800\uDC01');
 73// → '\xF0\x90\x80\x81'
 74```
 75
 76### `wtf8.decode(byteString)`
 77
 78Decodes any given WTF-8-encoded string (`byteString`) as WTF-8, and returns the WTF-8-decoded version of the string. It throws an error when malformed WTF-8 is detected.
 79
 80```js
 81wtf8.decode('\xC2\xA9');
 82// → '\xA9'
 83
 84wtf8.decode('\xF0\x90\x80\x81');
 85// → '\uD800\uDC01'
 86// → U+10001 LINEAR B SYLLABLE B038 E
 87```
 88
 89### `wtf8.version`
 90
 91A string representing the semantic version number.
 92
 93## Support
 94
 95_wtf-8_ has been tested in (at least) the latest versions of Chrome, Opera, Firefox, Safari, IE, Node.js, Narwhal, RingoJS, PhantomJS, and Rhino.
 96
 97## Author
 98
 99| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
100|---|
101| [Mathias Bynens](https://mathiasbynens.be/) |
102
103## License
104
105_wtf-8_ is available under the [MIT](https://mths.be/mit) license.