{"action":"created","comment":{"url":"https://api.github.com/repos/ramda/ramda.github.io/pulls/comments/35649818","id":35649818,"diff_hunk":"@@ -1,4 +1,168 @@\n Immutability\n ============\n \n-TODO\n+Often in Javascript we pair field accessors and field mutators for our\n+data structures.  We might see\n+\n+```js\n+person.setName('Fred');\n+person.getName(); //=> \"Fred\"\n+```\n+\n+This is done in many different ways.  Of course fields themselves are\n+most commonly both readable and writable:\n+\n+```js\n+person.name = 'Fred';\n+person.name; //=> \"Fred\"\n+```\n+\n+And there are more convoluted means involving `Object.defineProperty`.\n+In each of these techniques, there is a straightforward pairing.  Those\n+things you can _read_ from an object, you can also _write_ to it.\n+\n+In functional programming, such mutable state is considered extremely\n+dangerous, making programs hard to reason about, difficult to debug,\n+and almost impossible to grow correctly into large, consistent systems.\n+\n+Ramda helps avoid this by refusing to ever mutate input data.  We have\n+equivalents of the accessors above:\n+\n+```js\n+var getName = R.prop('name');\n+getName(person); //=> \"Fred\"\n+// or \n+R.prop('name', person); //=> \"Fred\"\n+```\n+\n+But the closest equivalents we have to mutators are functions like \n+`assoc`.  And they're not all that close.  `assoc` creates a copy of\n+your object with a new value associated with a field name:\n+\n+```js\n+var barney = {name: \"Barney\", age: 27}\n+var fred = {name: \"Fred\", age: 29}\n+barney.bestFriend = fred;\n+fred.bestFriend = barney;\n+\n+var fred2 = R.assoc('age', 30, fred);\n+\n+fred2.age; //=> 30\n+fred.age; //> 29\n+fred2.bestFriend === barney; //=> true\n+```\n+\n+Note that `assoc` retuns a new object, but note also the last line; the\n+returned structure shares as much of its internals with the original as\n+possible.  This is not a deep clone of the original object.\n+\n+This is true across all of Ramda.  Nothing you pass to Ramda will be \n+altered.  If a function acts like a mutator, it instead creates a copy\n+of the structure with the changes applied:\n+\n+For example, the native `sort` and `reverse` methods on`Array.prototype`, \n+mutate the underlying object.  Ramda's equivalents just return new lists:\n+\n+```js\n+var a1 = [1, 2, 3];\n+var b1 = a1.reverse(); //=> [3, 2, 1]\n+a1; //=> [3, 2, 1]\n+\n+var a2 = [1, 2, 3];\n+var b2 = R.reverse(a2); //=> [3, 2, 1]\n+a2; //=> [1, 2, 3]\n+\n+// and similarly for `sort`\n+```\n+\n+We won't discuss in depth all the reasons that immutability is desirable.\n+That's easily available [on the web][go].  But there are many important\n+reasons having to do with how well anyone can understand our code, how\n+well it stands up to parallelization, how many fewer ways in which it can\n+actually fail.\n+\n+We also will not talk about how you might make more of our own data\n+immutable (although in [Chapter 10][im], we do discuss how Ramda will\n+integrate with some immutable data libraries but not others.)  But we do\n+want to stress that _none_ of Ramda's functions mutate user data.\n+\n+For those used to functional programming, we should point out that this \n+is not done through deeply recursive algorithms.  We have plenty of \n+internal mutation.  But at our function boundaries, everything can be \n+seen as immutable.\n+\n+The basic point is simple: Don't expect Ramda to mutate your data for\n+you:\n+\n+```js\n+var numbers = [8, 6, 7, 5, 3, 0];\n+var jenny = R.append(9, numbers);\n+numbers; //=> [8, 6, 7, 5, 3, 0]\n+jenny; //=> [8, 6, 7, 5, 3, 0, 9]\n+```\n+\n+Ramda does not take any special pains to prevent you from mutating\n+your own data when using its functions.  For intance you could build \n+up an ouput object by continually mutating the accumulator passed to\n+[`reduce`][re].  Ramda would not prevent you:\n+\n+```js\n+var states = [\n+    {symbol: 'CT', name: 'Connecticut', pop: 3574097},\n+    {symbol: 'ME', name: 'Maine', pop: 1328361},\n+    {symbol: 'MA', name: 'Massachusetts', pop: 6547629},\n+    {symbol: 'NH', name: 'New Hampshire', pop: 1316470},\n+    {symbol: 'RI', name: 'Rhode Island', pop: 1052567},\n+    {symbol: 'VT', name: 'Vermont', pop: 623741},\n+];\n+\n+var notSmall = (state) => state.pop >= 2000000;\n+\n+R.reduce((accum, state) => {\n+    if (notSmall(state)) {\n+        accum[state.symbol] = state.pop;\n+    }\n+    return accum;\n+}, {}, states); //=> {\"CT\": 3574097, \"MA\": 6547629}\n+```\n+\n+Notice the continual mutation of the accumulator in this sample.  This\n+is not in any way prohibited by Ramda.  But it is perhaps not the most\n+idiomatic way to use Ramda.  The `assoc` we used earlier would cover \n+the same case without introducing such continual mutation:\n+\n+```js\n+R.reduce((accum, state) => notSmall(state) ? \n+                           R.assoc(state.symbol, state.pop, accum) : \n+                           accum,\n+{}, states),  //=> {\"CT\": 3574097, \"MA\": 6547629}\n+```\n+\n+And, unless it caused performance concerns, many Ramda users would\n+prefer to do this by piping the data through a few simpler \n+transformations:\n+\n+```js\n+R.pipe(\n+    R.filter(notSmall), \n+    R.map((state) => [state.symbol, state.pop]), ","path":"manual/01-intro/Immutability.md","position":149,"original_position":149,"commit_id":"a277f328fe12ed37c3f45db23a52cd6d8e73d813","original_commit_id":"a277f328fe12ed37c3f45db23a52cd6d8e73d813","user":{"login":"CrossEye","id":151263,"avatar_url":"https://avatars.githubusercontent.com/u/151263?v=3","gravatar_id":"","url":"https://api.github.com/users/CrossEye","html_url":"https://github.com/CrossEye","followers_url":"https://api.github.com/users/CrossEye/followers","following_url":"https://api.github.com/users/CrossEye/following{/other_user}","gists_url":"https://api.github.com/users/CrossEye/gists{/gist_id}","starred_url":"https://api.github.com/users/CrossEye/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/CrossEye/subscriptions","organizations_url":"https://api.github.com/users/CrossEye/orgs","repos_url":"https://api.github.com/users/CrossEye/repos","events_url":"https://api.github.com/users/CrossEye/events{/privacy}","received_events_url":"https://api.github.com/users/CrossEye/received_events","type":"User","site_admin":false},"body":"I'd have to think that one through a bit.  It's certainly a nicer use of Ramda, but I actually wanted to have a lambda somewhere here to show that they can be mixed and matched, without particularly calling attention to it.  That probably makes more sense, though in the section on composition than here.","created_at":"2015-07-28T13:57:37Z","updated_at":"2015-07-28T13:57:37Z","html_url":"https://github.com/ramda/ramda.github.io/pull/23#discussion_r35649818","pull_request_url":"https://api.github.com/repos/ramda/ramda.github.io/pulls/23","_links":{"self":{"href":"https://api.github.com/repos/ramda/ramda.github.io/pulls/comments/35649818"},"html":{"href":"https://github.com/ramda/ramda.github.io/pull/23#discussion_r35649818"},"pull_request":{"href":"https://api.github.com/repos/ramda/ramda.github.io/pulls/23"}}},"pull_request":{"url":"https://api.github.com/repos/ramda/ramda.github.io/pulls/23","id":40856393,"html_url":"https://github.com/ramda/ramda.github.io/pull/23","diff_url":"https://github.com/ramda/ramda.github.io/pull/23.diff","patch_url":"https://github.com/ramda/ramda.github.io/pull/23.patch","issue_url":"https://api.github.com/repos/ramda/ramda.github.io/issues/23","number":23,"state":"closed","locked":false,"title":"Adding immutability section","user":{"login":"CrossEye","id":151263,"avatar_url":"https://avatars.githubusercontent.com/u/151263?v=3","gravatar_id":"","url":"https://api.github.com/users/CrossEye","html_url":"https://github.com/CrossEye","followers_url":"https://api.github.com/users/CrossEye/followers","following_url":"https://api.github.com/users/CrossEye/following{/other_user}","gists_url":"https://api.github.com/users/CrossEye/gists{/gist_id}","starred_url":"https://api.github.com/users/CrossEye/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/CrossEye/subscriptions","organizations_url":"https://api.github.com/users/CrossEye/orgs","repos_url":"https://api.github.com/users/CrossEye/repos","events_url":"https://api.github.com/users/CrossEye/events{/privacy}","received_events_url":"https://api.github.com/users/CrossEye/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-07-26T17:19:46Z","updated_at":"2015-07-28T13:57:37Z","closed_at":"2015-07-26T17:31:42Z","merged_at":"2015-07-26T17:31:42Z","merge_commit_sha":"f60554d377762635850b7b38ee5c5603345e9047","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/ramda/ramda.github.io/pulls/23/commits","review_comments_url":"https://api.github.com/repos/ramda/ramda.github.io/pulls/23/comments","review_comment_url":"https://api.github.com/repos/ramda/ramda.github.io/pulls/comments{/number}","comments_url":"https://api.github.com/repos/ramda/ramda.github.io/issues/23/comments","statuses_url":"https://api.github.com/repos/ramda/ramda.github.io/statuses/a277f328fe12ed37c3f45db23a52cd6d8e73d813","head":{"label":"CrossEye:master","ref":"master","sha":"a277f328fe12ed37c3f45db23a52cd6d8e73d813","user":{"login":"CrossEye","id":151263,"avatar_url":"https://avatars.githubusercontent.com/u/151263?v=3","gravatar_id":"","url":"https://api.github.com/users/CrossEye","html_url":"https://github.com/CrossEye","followers_url":"https://api.github.com/users/CrossEye/followers","following_url":"https://api.github.com/users/CrossEye/following{/other_user}","gists_url":"https://api.github.com/users/CrossEye/gists{/gist_id}","starred_url":"https://api.github.com/users/CrossEye/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/CrossEye/subscriptions","organizations_url":"https://api.github.com/users/CrossEye/orgs","repos_url":"https://api.github.com/users/CrossEye/repos","events_url":"https://api.github.com/users/CrossEye/events{/privacy}","received_events_url":"https://api.github.com/users/CrossEye/received_events","type":"User","site_admin":false},"repo":{"id":39733789,"name":"ramda.github.io","full_name":"CrossEye/ramda.github.io","owner":{"login":"CrossEye","id":151263,"avatar_url":"https://avatars.githubusercontent.com/u/151263?v=3","gravatar_id":"","url":"https://api.github.com/users/CrossEye","html_url":"https://github.com/CrossEye","followers_url":"https://api.github.com/users/CrossEye/followers","following_url":"https://api.github.com/users/CrossEye/following{/other_user}","gists_url":"https://api.github.com/users/CrossEye/gists{/gist_id}","starred_url":"https://api.github.com/users/CrossEye/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/CrossEye/subscriptions","organizations_url":"https://api.github.com/users/CrossEye/orgs","repos_url":"https://api.github.com/users/CrossEye/repos","events_url":"https://api.github.com/users/CrossEye/events{/privacy}","received_events_url":"https://api.github.com/users/CrossEye/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/CrossEye/ramda.github.io","description":"Documentation for Ramda.js","fork":true,"url":"https://api.github.com/repos/CrossEye/ramda.github.io","forks_url":"https://api.github.com/repos/CrossEye/ramda.github.io/forks","keys_url":"https://api.github.com/repos/CrossEye/ramda.github.io/keys{/key_id}","collaborators_url":"https://api.github.com/repos/CrossEye/ramda.github.io/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/CrossEye/ramda.github.io/teams","hooks_url":"https://api.github.com/repos/CrossEye/ramda.github.io/hooks","issue_events_url":"https://api.github.com/repos/CrossEye/ramda.github.io/issues/events{/number}","events_url":"https://api.github.com/repos/CrossEye/ramda.github.io/events","assignees_url":"https://api.github.com/repos/CrossEye/ramda.github.io/assignees{/user}","branches_url":"https://api.github.com/repos/CrossEye/ramda.github.io/branches{/branch}","tags_url":"https://api.github.com/repos/CrossEye/ramda.github.io/tags","blobs_url":"https://api.github.com/repos/CrossEye/ramda.github.io/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/CrossEye/ramda.github.io/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/CrossEye/ramda.github.io/git/refs{/sha}","trees_url":"https://api.github.com/repos/CrossEye/ramda.github.io/git/trees{/sha}","statuses_url":"https://api.github.com/repos/CrossEye/ramda.github.io/statuses/{sha}","languages_url":"https://api.github.com/repos/CrossEye/ramda.github.io/languages","stargazers_url":"https://api.github.com/repos/CrossEye/ramda.github.io/stargazers","contributors_url":"https://api.github.com/repos/CrossEye/ramda.github.io/contributors","subscribers_url":"https://api.github.com/repos/CrossEye/ramda.github.io/subscribers","subscription_url":"https://api.github.com/repos/CrossEye/ramda.github.io/subscription","commits_url":"https://api.github.com/repos/CrossEye/ramda.github.io/commits{/sha}","git_commits_url":"https://api.github.com/repos/CrossEye/ramda.github.io/git/commits{/sha}","comments_url":"https://api.github.com/repos/CrossEye/ramda.github.io/comments{/number}","issue_comment_url":"https://api.github.com/repos/CrossEye/ramda.github.io/issues/comments{/number}","contents_url":"https://api.github.com/repos/CrossEye/ramda.github.io/contents/{+path}","compare_url":"https://api.github.com/repos/CrossEye/ramda.github.io/compare/{base}...{head}","merges_url":"https://api.github.com/repos/CrossEye/ramda.github.io/merges","archive_url":"https://api.github.com/repos/CrossEye/ramda.github.io/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/CrossEye/ramda.github.io/downloads","issues_url":"https://api.github.com/repos/CrossEye/ramda.github.io/issues{/number}","pulls_url":"https://api.github.com/repos/CrossEye/ramda.github.io/pulls{/number}","milestones_url":"https://api.github.com/repos/CrossEye/ramda.github.io/milestones{/number}","notifications_url":"https://api.github.com/repos/CrossEye/ramda.github.io/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/CrossEye/ramda.github.io/labels{/name}","releases_url":"https://api.github.com/repos/CrossEye/ramda.github.io/releases{/id}","created_at":"2015-07-26T17:07:40Z","updated_at":"2015-07-26T17:07:41Z","pushed_at":"2015-07-26T17:17:44Z","git_url":"git://github.com/CrossEye/ramda.github.io.git","ssh_url":"git@github.com:CrossEye/ramda.github.io.git","clone_url":"https://github.com/CrossEye/ramda.github.io.git","svn_url":"https://github.com/CrossEye/ramda.github.io","homepage":"http://ramdajs.com","size":3563,"stargazers_count":0,"watchers_count":0,"language":"HTML","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"ramda:master","ref":"master","sha":"a4c6058aa5cfae8e1f983907cef69fee650a2ad0","user":{"login":"ramda","id":5298359,"avatar_url":"https://avatars.githubusercontent.com/u/5298359?v=3","gravatar_id":"","url":"https://api.github.com/users/ramda","html_url":"https://github.com/ramda","followers_url":"https://api.github.com/users/ramda/followers","following_url":"https://api.github.com/users/ramda/following{/other_user}","gists_url":"https://api.github.com/users/ramda/gists{/gist_id}","starred_url":"https://api.github.com/users/ramda/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ramda/subscriptions","organizations_url":"https://api.github.com/users/ramda/orgs","repos_url":"https://api.github.com/users/ramda/repos","events_url":"https://api.github.com/users/ramda/events{/privacy}","received_events_url":"https://api.github.com/users/ramda/received_events","type":"Organization","site_admin":false},"repo":{"id":24790523,"name":"ramda.github.io","full_name":"ramda/ramda.github.io","owner":{"login":"ramda","id":5298359,"avatar_url":"https://avatars.githubusercontent.com/u/5298359?v=3","gravatar_id":"","url":"https://api.github.com/users/ramda","html_url":"https://github.com/ramda","followers_url":"https://api.github.com/users/ramda/followers","following_url":"https://api.github.com/users/ramda/following{/other_user}","gists_url":"https://api.github.com/users/ramda/gists{/gist_id}","starred_url":"https://api.github.com/users/ramda/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ramda/subscriptions","organizations_url":"https://api.github.com/users/ramda/orgs","repos_url":"https://api.github.com/users/ramda/repos","events_url":"https://api.github.com/users/ramda/events{/privacy}","received_events_url":"https://api.github.com/users/ramda/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ramda/ramda.github.io","description":"Documentation for Ramda.js","fork":false,"url":"https://api.github.com/repos/ramda/ramda.github.io","forks_url":"https://api.github.com/repos/ramda/ramda.github.io/forks","keys_url":"https://api.github.com/repos/ramda/ramda.github.io/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ramda/ramda.github.io/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ramda/ramda.github.io/teams","hooks_url":"https://api.github.com/repos/ramda/ramda.github.io/hooks","issue_events_url":"https://api.github.com/repos/ramda/ramda.github.io/issues/events{/number}","events_url":"https://api.github.com/repos/ramda/ramda.github.io/events","assignees_url":"https://api.github.com/repos/ramda/ramda.github.io/assignees{/user}","branches_url":"https://api.github.com/repos/ramda/ramda.github.io/branches{/branch}","tags_url":"https://api.github.com/repos/ramda/ramda.github.io/tags","blobs_url":"https://api.github.com/repos/ramda/ramda.github.io/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ramda/ramda.github.io/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ramda/ramda.github.io/git/refs{/sha}","trees_url":"https://api.github.com/repos/ramda/ramda.github.io/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ramda/ramda.github.io/statuses/{sha}","languages_url":"https://api.github.com/repos/ramda/ramda.github.io/languages","stargazers_url":"https://api.github.com/repos/ramda/ramda.github.io/stargazers","contributors_url":"https://api.github.com/repos/ramda/ramda.github.io/contributors","subscribers_url":"https://api.github.com/repos/ramda/ramda.github.io/subscribers","subscription_url":"https://api.github.com/repos/ramda/ramda.github.io/subscription","commits_url":"https://api.github.com/repos/ramda/ramda.github.io/commits{/sha}","git_commits_url":"https://api.github.com/repos/ramda/ramda.github.io/git/commits{/sha}","comments_url":"https://api.github.com/repos/ramda/ramda.github.io/comments{/number}","issue_comment_url":"https://api.github.com/repos/ramda/ramda.github.io/issues/comments{/number}","contents_url":"https://api.github.com/repos/ramda/ramda.github.io/contents/{+path}","compare_url":"https://api.github.com/repos/ramda/ramda.github.io/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ramda/ramda.github.io/merges","archive_url":"https://api.github.com/repos/ramda/ramda.github.io/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ramda/ramda.github.io/downloads","issues_url":"https://api.github.com/repos/ramda/ramda.github.io/issues{/number}","pulls_url":"https://api.github.com/repos/ramda/ramda.github.io/pulls{/number}","milestones_url":"https://api.github.com/repos/ramda/ramda.github.io/milestones{/number}","notifications_url":"https://api.github.com/repos/ramda/ramda.github.io/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ramda/ramda.github.io/labels{/name}","releases_url":"https://api.github.com/repos/ramda/ramda.github.io/releases{/id}","created_at":"2014-10-04T13:38:57Z","updated_at":"2015-04-22T13:36:41Z","pushed_at":"2015-07-26T17:31:44Z","git_url":"git://github.com/ramda/ramda.github.io.git","ssh_url":"git@github.com:ramda/ramda.github.io.git","clone_url":"https://github.com/ramda/ramda.github.io.git","svn_url":"https://github.com/ramda/ramda.github.io","homepage":"http://ramdajs.com","size":3563,"stargazers_count":0,"watchers_count":0,"language":"HTML","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":9,"mirror_url":null,"open_issues_count":6,"forks":9,"open_issues":6,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/ramda/ramda.github.io/pulls/23"},"html":{"href":"https://github.com/ramda/ramda.github.io/pull/23"},"issue":{"href":"https://api.github.com/repos/ramda/ramda.github.io/issues/23"},"comments":{"href":"https://api.github.com/repos/ramda/ramda.github.io/issues/23/comments"},"review_comments":{"href":"https://api.github.com/repos/ramda/ramda.github.io/pulls/23/comments"},"review_comment":{"href":"https://api.github.com/repos/ramda/ramda.github.io/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/ramda/ramda.github.io/pulls/23/commits"},"statuses":{"href":"https://api.github.com/repos/ramda/ramda.github.io/statuses/a277f328fe12ed37c3f45db23a52cd6d8e73d813"}}}}