datianyun
diff --git a/‎README.md
Lines changed: 135 additions & 63 deletions b/‎README.md
Lines changed: 135 additions & 63 deletions
@@ -363,93 +363,100 @@ const nested4 = nested3.updateIn([ 'a', 'b', 'c' ], list => list.push(6))
 ```
 
 
-Lazy Seq
---------
+Equality treats Collections as Values
+-------------------------------------
 
-`Seq` describes a lazy operation, allowing them to efficiently chain
-use of all the sequence methods (such as `map` and `filter`).
+Immutable.js collections are treated as pure data *values*. Two immutable
+collections are considered *value equal* (via `.equals()` or `is()`) if they
+represent the same collection of values. This differs from JavaScript's typical
+*reference equal* (via `===` or `==`) for Objects and Arrays which only
+determines if two variables represent references to the same object instance.
 
-**Seq is immutable** — Once a Seq is created, it cannot be
-changed, appended to, rearranged or otherwise modified. Instead, any mutative
-method called on a Seq will return a new Seq.
-
-**Seq is lazy** — Seq does as little work as necessary to respond to any
-method call.
-
-For example, the following does not perform any work, because the resulting
-Seq is never used:
+Consider the example below where two identical `Map` instances are not
+*reference equal* but are *value equal*.
 
+<!-- runkit:activate -->
 ```js
-const { Seq } = require('immutable')
-const oddSquares = Seq([ 1, 2, 3, 4, 5, 6, 7, 8 ])
-  .filter(x => x % 2)
-  .map(x => x * x)
-```
-
-Once the Seq is used, it performs only the work necessary. In this
-example, no intermediate arrays are ever created, filter is called three times,
-and map is only called once:
+// First consider:
+const obj1 = { a: 1, b: 2, c: 3 }
+const obj2 = { a: 1, b: 2, c: 3 }
+obj1 !== obj2 // two different instances are always not equal with ===
 
-```js
-console.log(oddSquares.get(1)); // 9
+const { Map, is } = require('immutable')
+const map1 = Map({ a: 1, b: 2, c: 3 })
+const map2 = Map({ a: 1, b: 2, c: 3 })
+map1 !== map2 // two different instances are not reference-equal
+map1.equals(map2) // but are value-equal if they have the same values
+is(map1, map2) // alternatively can use the is() function
 ```
 
-Any collection can be converted to a lazy Seq with `.toSeq()`.
+Value equality allows Immutable.js collections to be used as keys in Maps or
+values in Sets, and retrieved with different but equivalent collections:
 
 <!-- runkit:activate -->
 ```js
-const { Map } = require('immutable')
-const seq = Map({ a: 1, b: 2, c: 3 }).toSeq()
+const { Map, Set } = require('immutable')
+const map1 = Map({ a: 1, b: 2, c: 3 })
+const map2 = Map({ a: 1, b: 2, c: 3 })
+const set = Set().add(map1)
+set.has(map2) // true because these are value-equal
 ```
 
-Seq allows for the efficient chaining of sequence operations, especially when
-converting to a different concrete type (such as to a JS object):
+Note: `is()` uses the same measure of equality as [Object.is][] for scalar
+strings and numbers, but uses value equality for Immutable collections,
+determining if both are immutable and all keys and values are equal
+using the same measure of equality.
 
-```js
-seq.flip().map(key => key.toUpperCase()).flip().toObject();
-// { A: 1, B: 2, C: 3 }
-```
+[Object.is]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
 
-As well as expressing logic that would otherwise seem memory-limited:
+#### Performance tradeoffs
 
-<!-- runkit:activate -->
-```js
-const { Range } = require('immutable')
-Range(1, Infinity)
-  .skip(1000)
-  .map(n => -n)
-  .filter(n => n % 2 === 0)
-  .take(2)
-  .reduce((r, n) => r * n, 1);
-// 1006008
-```
-
-Note: A Collection is always iterated in the same order, however that order may
-not always be well defined, as is the case for the `Map`.
+While value equality is useful in many circumstances, it has different
+performance characteristics than reference equality. Understanding these
+tradeoffs may help you decide which to use in each case, especially when used
+to memoize some operation.
 
+When comparing two collections, value equality may require considering every
+item in each collection, on an `O(N)` time complexity. For large collections of
+values, this could become a costly operation. Though if the two are not equal
+and hardly similar, the inequality is determined very quickly. In contrast, when
+comparing two collections with reference equality, only the initial references
+to memory need to be compared which is not based on the size of the collections,
+which has an `O(1)` time complexity. Checking reference equality is always very
+fast, however just because two collections are not reference-equal does not rule
+out the possibility that they may be value-equal.
 
-Equality treats Collections as Data
------------------------------------
+#### Return self on no-op optimization
 
-Immutable.js provides equality which treats immutable data structures as pure
-data, performing a deep equality check if necessary.
+When possible, Immutable.js avoids creating new objects for updates where no
+change in *value* occurred, to allow for efficient *reference equality* checking
+to quickly determine if no change occurred.
 
 <!-- runkit:activate -->
 ```js
-const { Map, is } = require('immutable')
-const map1 = Map({ a: 1, b: 2, c: 3 })
-const map2 = Map({ a: 1, b: 2, c: 3 })
-assert.equal(map1 !== map2, true) // two different instances
-assert.equal(is(map1, map2), true) // have equivalent values
-assert.equal(map1.equals(map2), true) // alternatively use the equals method
+const { Map } = require('immutable')
+const originalMap = Map({ a: 1, b: 2, c: 3 })
+const updatedMap = originalMap.set('b', 2)
+updatedMap === originalMap // No-op .set() returned the original reference.
 ```
 
-`Immutable.is()` uses the same measure of equality as [Object.is][]
-including if both are immutable and all keys and values are equal
-using the same measure of equality.
-
-[Object.is]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
+However updates which do result in a change will return a new reference. Each
+of these operations occur independently, so two similar updates will not return
+the same reference:
 
+<!-- runkit:activate -->
+```js
+const { Map } = require('immutable')
+const originalMap = Map({ a: 1, b: 2, c: 3 })
+const updatedMap = originalMap.set('b', 1000)
+// New instance, leaving the original immutable.
+updatedMap !== originalMap
+const anotherUpdatedMap = originalMap.set('b', 1000)
+// Despite both the results of the same operation, each created a new reference.
+anotherUpdatedMap !== updatedMap
+// However the two are value equal.
+anotherUpdatedMap.equals(updatedMap)
+```
 
 Batching Mutations
 ------------------
@@ -493,6 +500,71 @@ and `splice` will always return new immutable data-structures and never mutate
 a mutable collection.
 
 
+Lazy Seq
+--------
+
+`Seq` describes a lazy operation, allowing them to efficiently chain
+use of all the sequence methods (such as `map` and `filter`).
+
+**Seq is immutable** — Once a Seq is created, it cannot be
+changed, appended to, rearranged or otherwise modified. Instead, any mutative
+method called on a Seq will return a new Seq.
+
+**Seq is lazy** — Seq does as little work as necessary to respond to any
+method call.
+
+For example, the following does not perform any work, because the resulting
+Seq is never used:
+
+```js
+const { Seq } = require('immutable')
+const oddSquares = Seq([ 1, 2, 3, 4, 5, 6, 7, 8 ])
+  .filter(x => x % 2)
+  .map(x => x * x)
+```
+
+Once the Seq is used, it performs only the work necessary. In this
+example, no intermediate arrays are ever created, filter is called three times,
+and map is only called once:
+
+```js
+console.log(oddSquares.get(1)); // 9
+```
+
+Any collection can be converted to a lazy Seq with `.toSeq()`.
+
+<!-- runkit:activate -->
+```js
+const { Map } = require('immutable')
+const seq = Map({ a: 1, b: 2, c: 3 }).toSeq()
+```
+
+Seq allows for the efficient chaining of sequence operations, especially when
+converting to a different concrete type (such as to a JS object):
+
+```js
+seq.flip().map(key => key.toUpperCase()).flip().toObject();
+// { A: 1, B: 2, C: 3 }
+```
+
+As well as expressing logic that would otherwise seem memory-limited:
+
+<!-- runkit:activate -->
+```js
+const { Range } = require('immutable')
+Range(1, Infinity)
+  .skip(1000)
+  .map(n => -n)
+  .filter(n => n % 2 === 0)
+  .take(2)
+  .reduce((r, n) => r * n, 1);
+// 1006008
+```
+
+Note: A Collection is always iterated in the same order, however that order may
+not always be well defined, as is the case for the `Map`.
+
+
 Documentation
 -------------