From e183af7e9c8652ab6b846ed2d75f32c4da7c7a38 Mon Sep 17 00:00:00 2001
From: Cheng Lou <chenglou92@gmail.com>
Date: Fri, 11 Jul 2014 19:25:37 -0700
Subject: [PATCH] [Docs] Update addons.update

Fixes #1815.
Add the new `$apply` command, plus a few examples.

@petehunt
---
 docs/09.6-update.md | 56 +++++++++++++++++++++++++++++++++++++--------
 1 file changed, 47 insertions(+), 9 deletions(-)

diff --git a/docs/09.6-update.md b/docs/09.6-update.md
index 18f1a6f5..b3ea310d 100644
--- a/docs/09.6-update.md
+++ b/docs/09.6-update.md
@@ -14,14 +14,15 @@ Dealing with immutable data in JavaScript is more difficult than in languages de
 
 If you mutate data like this:
 
-```javascript
+```js
 myData.x.y.z = 7;
+// or...
 myData.a.b.push(9);
 ```
 
-you have no way of determining which data has changed since the previous copy is destroyed. Instead, you need to create a new copy of `myData` and change only the parts of it that need to be changed. Then you can compare the old copy of `myData` with the new one in `shouldComponentUpdate()` using triple-equals:
+you have no way of determining which data has changed since the previous copy is overriden. Instead, you need to create a new copy of `myData` and change only the parts of it that need to be changed. Then you can compare the old copy of `myData` with the new one in `shouldComponentUpdate()` using triple-equals:
 
-```javascript
+```js
 var newData = deepCopy(myData);
 newData.x.y.z = 7;
 newData.a.b.push(9);
@@ -29,7 +30,7 @@ newData.a.b.push(9);
 
 Unfortunately, deep copies are expensive, and sometimes impossible. You can alleviate this by only copying objects that need to be changed and by reusing the objects that haven't changed. Unfortunately, in today's JavaScript this can be cumbersome:
 
-```javascript
+```js
 var newData = extend(myData, {
   x: extend(myData.x, {
     y: extend(myData.x.y, {z: 7}),
@@ -42,7 +43,7 @@ While this is fairly performant (since it only shallow copies `log n` objects an
 
 `update()` provides simple syntactic sugar around this pattern to make writing this code easier. This code becomes:
 
-```javascript
+```js
 var newData = React.addons.update(myData, {
   x: {y: {z: {$set: 7}}},
   a: {b: {$push: [9]}}
@@ -55,8 +56,45 @@ The `$`-prefixed keys are called *commands*. The data structure they are "mutati
 
 ## Available commands
 
-  * `{$push: array}` `push()` all the items in `array` on the target
-  * `{$unshift: array}` `unshift()` all the items in `array` on the target
+  * `{$push: array}` `push()` all the items in `array` on the target.
+  * `{$unshift: array}` `unshift()` all the items in `array` on the target.
   * `{$splice: array of arrays}` for each item in `array()` call `splice()` on the target with the parameters provided by the item.
-  * `{$set: any}` replace the target entirely
-  * `{$merge: object}` merge the keys of `object` with the target
+  * `{$set: any}` replace the target entirely.
+  * `{$merge: object}` merge the keys of `object` with the target.
+  * `{$apply: function}` passes in the current value to the function and updates it with the new returned value.
+
+## Examples
+
+### Simple push
+
+```js
+var initialArray = [1, 2, 3];
+var newArray = update(initialArray, {$push: [4]}); // => [1, 2, 3, 4]
+```
+`initialArray` is still `[1, 2, 3]`.
+
+### Nested collections
+
+```js
+var collection = [1, 2, {a: [12, 17, 15]}];
+var newCollection = update(collection, {2: {a: {$splice: [[1, 1, 13, 14]]}}});
+// => [1, 2, {a: [12, 13, 14, 15]}]
+```
+This accesses `collection`'s index `2`, key `a`, and does a splice of one item starting from index `1` (to remove `17`) while inserting `13` and `14`.
+
+### Updating a value based on its current one
+
+```js
+var obj = {a: 5, b: 3};
+var newObj = update(obj, {b: {$apply: function(x) {return x * 2;}}});
+// => {a: 5, b: 6}
+// This is equivalent, but gets verbose for deeply nested collections:
+var newObj2 = update(obj, {b: {$set: obj.b * 2}});
+```
+
+### (Shallow) merge
+
+```js
+var obj = {a: 5, b: 3};
+var newObj = update(obj, {$merge: {b: 6, c: 7}}); // => {a: 5, b: 6, c: 7}
+```