README

diff --git a/README.md b/README.md
index cd333f556de10a3be76603ef83a69bdabf5bf56c..a9ca9ee200813eb87fc601c3854d11c68d53eedf 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,8 +1,7 @@
 buffer-browserify-fast
 ===============
 
-The buffer module from [node.js](http://nodejs.org/),
-but for browsers.
+The buffer module from [node.js](http://nodejs.org/), but for browsers.
 
 When you `require('buffer')` in
 [browserify](http://github.com/substack/node-browserify),
@@ -10,6 +9,28 @@ this module will be loaded.
 
 It will also be loaded if you use the global `Buffer` variable.
 
+
+## Features
+
+- Backed by `ArrayBuffer` (not `Object`, so it's fast)
+- Preserves Node API exactly
+- Faster pretty much across the board (see perf results below)
+- `.slice()` returns instances of the same type
+- Square-bracket `buf[4]` notation works!
+- Does not modify any browser prototypes.
+- All tests from the original `buffer-browserify` project pass.
+- Works in browsers **without** `Uint8Array` support (IE9 and below)
+
+
+## How does it work?
+
+The `Buffer` constructor returns instances of `Uint8Array` that are augmented with function properties for all the Buffer API functions. We use `Uint8Array` so that square bracket notation works as expected -- it returns a single octet.
+
+By augmenting the instances, we can avoid modifying the Uint8Array prototype.
+
+For browsers that don't support `Uint8Array`, we fallback to the (old) `buffer-browserify`.
+
+
 ## Performance
 
 See perf tests in `/perf`.
@@ -102,3 +123,7 @@ OldBuffer#writeFloatBE x 4,020 ops/sec ±1.04% (92 runs sampled)
 Buffer#writeFloatBE x 1,811,134 ops/sec ±0.67% (91 runs sampled)
 Fastest is Buffer#writeFloatBE
 ```
+
+## License
+
+MIT
\ No newline at end of file