node_modules/websocket/node_modules/typedarray-to-buffer/README.md

   1 # typedarray-to-buffer [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]
   2
   3 [travis-image]: https://img.shields.io/travis/feross/typedarray-to-buffer/master.svg
   4 [travis-url]: https://travis-ci.org/feross/typedarray-to-buffer
   5 [npm-image]: https://img.shields.io/npm/v/typedarray-to-buffer.svg
   6 [npm-url]: https://npmjs.org/package/typedarray-to-buffer
   7 [downloads-image]: https://img.shields.io/npm/dm/typedarray-to-buffer.svg
   8 [downloads-url]: https://npmjs.org/package/typedarray-to-buffer
   9 [standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
  10 [standard-url]: https://standardjs.com
  11
  12 #### Convert a typed array to a [Buffer](https://github.com/feross/buffer) without a copy.
  13
  14 [![saucelabs][saucelabs-image]][saucelabs-url]
  15
  16 [saucelabs-image]: https://saucelabs.com/browser-matrix/typedarray-to-buffer.svg
  17 [saucelabs-url]: https://saucelabs.com/u/typedarray-to-buffer
  18
  19 Say you're using the ['buffer'](https://github.com/feross/buffer) module on npm, or
  20 [browserify](http://browserify.org/) and you're working with lots of binary data.
  21
  22 Unfortunately, sometimes the browser or someone else's API gives you a typed array like
  23 `Uint8Array` to work with and you need to convert it to a `Buffer`. What do you do?
  24
  25 Of course: `Buffer.from(uint8array)`
  26
  27 But, alas, every time you do `Buffer.from(uint8array)` **the entire array gets copied**.
  28 The `Buffer` constructor does a copy; this is
  29 defined by the [node docs](http://nodejs.org/api/buffer.html) and the 'buffer' module
  30 matches the node API exactly.
  31
  32 So, how can we avoid this expensive copy in
  33 [performance critical applications](https://github.com/feross/buffer/issues/22)?
  34
  35 ***Simply use this module, of course!***
  36
  37 If you have an `ArrayBuffer`, you don't need this module, because
  38 `Buffer.from(arrayBuffer)`
  39 [is already efficient](https://nodejs.org/api/buffer.html#buffer_class_method_buffer_from_arraybuffer_byteoffset_length).
  40
  41 ## install
  42
  43 ```bash
  44 npm install typedarray-to-buffer
  45 ```
  46
  47 ## usage
  48
  49 To convert a typed array to a `Buffer` **without a copy**, do this:
  50
  51 ```js
  52 var toBuffer = require('typedarray-to-buffer')
  53
  54 var arr = new Uint8Array([1, 2, 3])
  55 arr = toBuffer(arr)
  56
  57 // arr is a buffer now!
  58
  59 arr.toString()  // '\u0001\u0002\u0003'
  60 arr.readUInt16BE(0)  // 258
  61 ```
  62
  63 ## how it works
  64
  65 If the browser supports typed arrays, then `toBuffer` will **augment the typed array** you
  66 pass in with the `Buffer` methods and return it. See [how does Buffer
  67 work?](https://github.com/feross/buffer#how-does-it-work) for more about how augmentation
  68 works.
  69
  70 This module uses the typed array's underlying `ArrayBuffer` to back the new `Buffer`. This
  71 respects the "view" on the `ArrayBuffer`, i.e. `byteOffset` and `byteLength`. In other
  72 words, if you do `toBuffer(new Uint32Array([1, 2, 3]))`, then the new `Buffer` will
  73 contain `[1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0]`, **not** `[1, 2, 3]`. And it still doesn't
  74 require a copy.
  75
  76 If the browser doesn't support typed arrays, then `toBuffer` will create a new `Buffer`
  77 object, copy the data into it, and return it. There's no simple performance optimization
  78 we can do for old browsers. Oh well.
  79
  80 If this module is used in node, then it will just call `Buffer.from`. This is just for
  81 the convenience of modules that work in both node and the browser.
  82
  83 ## license
  84
  85 MIT. Copyright (C) [Feross Aboukhadijeh](http://feross.org).