{"action":"created","comment":{"url":"https://api.github.com/repos/rust-lang/book/pulls/comments/49690701","id":49690701,"diff_hunk":"@@ -1,238 +1,467 @@\n # Ownership\n \n-This guide is one of three presenting Rust’s ownership system. This is one of\n-Rust’s most unique and compelling features, with which Rust developers should\n-become quite acquainted. Ownership is how Rust achieves its largest goal,\n-memory safety. There are a few distinct concepts, each with its own\n-chapter:\n+Rust’s central feature is called ‘ownership’. It is a feature that is\n+straightforward to explain, but has deep implications for the rest of the\n+language. \n \n-* ownership, which you’re reading now\n-* [borrowing][borrowing], and their associated feature ‘references’\n-* [lifetimes][lifetimes], an advanced concept of borrowing\n+Rust is committed to both safety and speed. One of the key tools for balancing\n+between them is “zero-cost abstractions”: the various abstractions in Rust do\n+not pose a global performance penalty. The ownership system is a prime example\n+of a zero-cost abstraction. All of the analysis we’ll talk about in this guide\n+is done at compile time. You do not pay any run-time cost for any of these\n+features.\n \n-These three chapters are related, and in order. You’ll need all three to fully\n-understand the ownership system.\n+However, this system does have a certain cost: learning curve. Many new\n+Rustaceans experience something we like to call ‘fighting with the borrow\n+checker’, where the Rust compiler refuses to compile a program that the author\n+thinks is valid. This can happen because the programmer isn’t used to thinking\n+carefully about ownership, or is thinking about it differently from the way\n+that Rust does. You probably will experience similar things at first. There is\n+good news, however: more experienced Rust developers report that once they work\n+with the rules of the ownership system for a period of time, they fight the\n+borrow checker less and less. Keep at it!\n \n-[borrowing]: references-and-borrowing.html\n-[lifetimes]: lifetimes.html\n+This chapter will give you a foundation for understanding the rest of the\n+language. To do so, we’re going to learn through examples, focused around a\n+very common data structure: strings.\n \n-# Meta\n+## Variable binding scope\n \n-Before we get to the details, two important notes about the ownership system.\n+Let’s take a step back and look at the very basics again. Now that we’re past\n+basic syntax, we won’t include all of the `fn main() {` stuff in examples, so\n+if you’re following along, you will have to add that yourself. It will be a bit\n+more concise, letting us focus on the actual example.\n \n-Rust has a focus on safety and speed. It accomplishes these goals through many\n-‘zero-cost abstractions’, which means that in Rust, abstractions cost as little\n-as possible in order to make them work. The ownership system is a prime example\n-of a zero-cost abstraction. All of the analysis we’ll talk about in this guide\n-is _done at compile time_. You do not pay any run-time cost for any of these\n-features.\n+Anyway, here it is:\n \n-However, this system does have a certain cost: learning curve. Many new users\n-to Rust experience something we like to call ‘fighting with the borrow\n-checker’, where the Rust compiler refuses to compile a program that the author\n-thinks is valid. This often happens because the programmer’s mental model of\n-how ownership should work doesn’t match the actual rules that Rust implements.\n-You probably will experience similar things at first. There is good news,\n-however: more experienced Rust developers report that once they work with the\n-rules of the ownership system for a period of time, they fight the borrow\n-checker less and less.\n+```rust\n+let s = \"hello\";\n+```\n \n-With that in mind, let’s learn about ownership.\n+This variable binding refers to a string literal. It’s valid from the point at\n+which it’s declared, until the end of the current _scope_. That is:\n \n-# Ownership\n+```rust\n+{                      // s is not valid here, it’s not yet in scope\n+    let s = \"hello\";   // s is valid from this point forward\n+\n+    // do stuff with s\n+}                      // this scope is now over, and s is no longer valid\n+```\n+\n+In other words, there are two important points in time here:\n+\n+- When `s` comes ‘into scope’, it is valid.\n+- It remains so until it ‘goes out of scope’.\n+\n+At this point, things are similar to other programming languages. Let’s build\n+on top of this understanding by introducing a new type: `String`.\n+\n+## Strings\n+\n+String literals are convenient, but they aren’t the only way that you use strings.\n+For one thing, they’re immutable. This will not work:\n+\n+```rust,ignore\n+let mut s = \"hello\";\n+\n+s = s + \", world!\";\n+```\n+\n+It gives us an error:\n+\n+```text\n+4:10 error: binary operation `+` cannot be applied to type `&str` [E0369]\n+ s = s + \", world!\";\n+     ^\n+```\n+\n+No dice. Also, not every string is literal: what about taking user input and\n+storing it in a string?\n \n-[Variable bindings][bindings] have a property in Rust: they ‘have ownership’\n-of what they’re bound to. This means that when a binding goes out of scope,\n-Rust will free the bound resources. For example:\n+For this, Rust has a second string type, `String`. You can create a `String` from\n+a string literal using the `from` function:\n \n ```rust\n-fn foo() {\n-    let v = vec![1, 2, 3];\n-}\n+let s = String::from(\"hello\");\n+```\n+\n+The double colon (`::`) is a kind of scope operator, allowing us to namespace this\n+particular `from()` function under the `String` type itself, rather than using\n+some sort of name like `string_from()`.\n+\n+This kind of string can be mutated:\n+\n+```rust\n+let mut s = String::from(\"hello\");\n+\n+s = s + \", world!\";\n ```\n \n-When `v` comes into scope, a new [`Vec<T>`][vect] is created. In this case, the\n-vector also allocates space on [the heap][heap], for the three elements. When\n-`v` goes out of scope at the end of `foo()`, Rust will clean up everything\n-related to the vector, even the heap-allocated memory. This happens\n-deterministically, at the end of the scope.\n+## Memory and allocation\n+\n+So, what’s the difference here? Why can `String` be mutated, but literals\n+cannot? The difference comes down to how these two types deal with memory.\n+\n+In the case of a string literal, because we know the contents of the string at\n+compile time, we can put the text of the string directly into the final\n+executable. This means that string literals are quite fast and efficient. But\n+these properties only come from its immutability; we can’t put an\n+arbitrary-sized blob of memory into the binary for each string!\n \n-[vect]: ../std/vec/struct.Vec.html\n-[heap]: the-stack-and-the-heap.html\n-[bindings]: variable-bindings.html\n+With `String`, to support a mutable, growable string, we need to allocate an\n+un-known chunk of memory to hold the contents. This means two things:\n \n-# Move semantics\n+1. The memory must be requested from the operating system at runtime.\n+2. We need a way of giving this memory back to the operating system when we’re\n+   done with our `String`.\n \n-There’s some more subtlety here, though: Rust ensures that there is _exactly\n-one_ binding to any given resource. For example, if we have a vector, we can\n-assign it to another binding:\n+That first part is done by us: when we call `String::from()`, its\n+implementation requests the memory it needs. This is pretty much universal in\n+programming languages.","path":"src/ownership.md","position":170,"original_position":170,"commit_id":"1045fa2c7b2420fb8abede6eab137c5b539f4ac5","original_commit_id":"1045fa2c7b2420fb8abede6eab137c5b539f4ac5","user":{"login":"Gankro","id":1136864,"avatar_url":"https://avatars.githubusercontent.com/u/1136864?v=3","gravatar_id":"","url":"https://api.github.com/users/Gankro","html_url":"https://github.com/Gankro","followers_url":"https://api.github.com/users/Gankro/followers","following_url":"https://api.github.com/users/Gankro/following{/other_user}","gists_url":"https://api.github.com/users/Gankro/gists{/gist_id}","starred_url":"https://api.github.com/users/Gankro/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Gankro/subscriptions","organizations_url":"https://api.github.com/users/Gankro/orgs","repos_url":"https://api.github.com/users/Gankro/repos","events_url":"https://api.github.com/users/Gankro/events{/privacy}","received_events_url":"https://api.github.com/users/Gankro/received_events","type":"User","site_admin":false},"body":"What is universal, exactly? Allocating memory being \"a thing\"?","created_at":"2016-01-14T06:03:18Z","updated_at":"2016-01-14T06:03:18Z","html_url":"https://github.com/rust-lang/book/pull/58#discussion_r49690701","pull_request_url":"https://api.github.com/repos/rust-lang/book/pulls/58","_links":{"self":{"href":"https://api.github.com/repos/rust-lang/book/pulls/comments/49690701"},"html":{"href":"https://github.com/rust-lang/book/pull/58#discussion_r49690701"},"pull_request":{"href":"https://api.github.com/repos/rust-lang/book/pulls/58"}}},"pull_request":{"url":"https://api.github.com/repos/rust-lang/book/pulls/58","id":55829617,"html_url":"https://github.com/rust-lang/book/pull/58","diff_url":"https://github.com/rust-lang/book/pull/58.diff","patch_url":"https://github.com/rust-lang/book/pull/58.patch","issue_url":"https://api.github.com/repos/rust-lang/book/issues/58","number":58,"state":"open","locked":false,"title":"first draft of 'ownership'","user":{"login":"steveklabnik","id":27786,"avatar_url":"https://avatars.githubusercontent.com/u/27786?v=3","gravatar_id":"","url":"https://api.github.com/users/steveklabnik","html_url":"https://github.com/steveklabnik","followers_url":"https://api.github.com/users/steveklabnik/followers","following_url":"https://api.github.com/users/steveklabnik/following{/other_user}","gists_url":"https://api.github.com/users/steveklabnik/gists{/gist_id}","starred_url":"https://api.github.com/users/steveklabnik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/steveklabnik/subscriptions","organizations_url":"https://api.github.com/users/steveklabnik/orgs","repos_url":"https://api.github.com/users/steveklabnik/repos","events_url":"https://api.github.com/users/steveklabnik/events{/privacy}","received_events_url":"https://api.github.com/users/steveklabnik/received_events","type":"User","site_admin":false},"body":"r? @aturon \r\n\r\nRendered: https://github.com/rust-lang/book/blob/ownership/src/ownership.md\r\n\r\nI should add the diagrams before we merge this. EDIT: diagrams added","created_at":"2016-01-12T22:50:27Z","updated_at":"2016-01-14T06:03:18Z","closed_at":null,"merged_at":null,"merge_commit_sha":"5e7a2d05974aa3860b54326622e2a2a2fd40359d","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/rust-lang/book/pulls/58/commits","review_comments_url":"https://api.github.com/repos/rust-lang/book/pulls/58/comments","review_comment_url":"https://api.github.com/repos/rust-lang/book/pulls/comments{/number}","comments_url":"https://api.github.com/repos/rust-lang/book/issues/58/comments","statuses_url":"https://api.github.com/repos/rust-lang/book/statuses/1045fa2c7b2420fb8abede6eab137c5b539f4ac5","head":{"label":"rust-lang:ownership","ref":"ownership","sha":"1045fa2c7b2420fb8abede6eab137c5b539f4ac5","user":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=3","gravatar_id":"","url":"https://api.github.com/users/rust-lang","html_url":"https://github.com/rust-lang","followers_url":"https://api.github.com/users/rust-lang/followers","following_url":"https://api.github.com/users/rust-lang/following{/other_user}","gists_url":"https://api.github.com/users/rust-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/rust-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rust-lang/subscriptions","organizations_url":"https://api.github.com/users/rust-lang/orgs","repos_url":"https://api.github.com/users/rust-lang/repos","events_url":"https://api.github.com/users/rust-lang/events{/privacy}","received_events_url":"https://api.github.com/users/rust-lang/received_events","type":"Organization","site_admin":false},"repo":{"id":47854924,"name":"book","full_name":"rust-lang/book","owner":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=3","gravatar_id":"","url":"https://api.github.com/users/rust-lang","html_url":"https://github.com/rust-lang","followers_url":"https://api.github.com/users/rust-lang/followers","following_url":"https://api.github.com/users/rust-lang/following{/other_user}","gists_url":"https://api.github.com/users/rust-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/rust-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rust-lang/subscriptions","organizations_url":"https://api.github.com/users/rust-lang/orgs","repos_url":"https://api.github.com/users/rust-lang/repos","events_url":"https://api.github.com/users/rust-lang/events{/privacy}","received_events_url":"https://api.github.com/users/rust-lang/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/rust-lang/book","description":"The Rust Programming Language","fork":false,"url":"https://api.github.com/repos/rust-lang/book","forks_url":"https://api.github.com/repos/rust-lang/book/forks","keys_url":"https://api.github.com/repos/rust-lang/book/keys{/key_id}","collaborators_url":"https://api.github.com/repos/rust-lang/book/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/rust-lang/book/teams","hooks_url":"https://api.github.com/repos/rust-lang/book/hooks","issue_events_url":"https://api.github.com/repos/rust-lang/book/issues/events{/number}","events_url":"https://api.github.com/repos/rust-lang/book/events","assignees_url":"https://api.github.com/repos/rust-lang/book/assignees{/user}","branches_url":"https://api.github.com/repos/rust-lang/book/branches{/branch}","tags_url":"https://api.github.com/repos/rust-lang/book/tags","blobs_url":"https://api.github.com/repos/rust-lang/book/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/rust-lang/book/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/rust-lang/book/git/refs{/sha}","trees_url":"https://api.github.com/repos/rust-lang/book/git/trees{/sha}","statuses_url":"https://api.github.com/repos/rust-lang/book/statuses/{sha}","languages_url":"https://api.github.com/repos/rust-lang/book/languages","stargazers_url":"https://api.github.com/repos/rust-lang/book/stargazers","contributors_url":"https://api.github.com/repos/rust-lang/book/contributors","subscribers_url":"https://api.github.com/repos/rust-lang/book/subscribers","subscription_url":"https://api.github.com/repos/rust-lang/book/subscription","commits_url":"https://api.github.com/repos/rust-lang/book/commits{/sha}","git_commits_url":"https://api.github.com/repos/rust-lang/book/git/commits{/sha}","comments_url":"https://api.github.com/repos/rust-lang/book/comments{/number}","issue_comment_url":"https://api.github.com/repos/rust-lang/book/issues/comments{/number}","contents_url":"https://api.github.com/repos/rust-lang/book/contents/{+path}","compare_url":"https://api.github.com/repos/rust-lang/book/compare/{base}...{head}","merges_url":"https://api.github.com/repos/rust-lang/book/merges","archive_url":"https://api.github.com/repos/rust-lang/book/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/rust-lang/book/downloads","issues_url":"https://api.github.com/repos/rust-lang/book/issues{/number}","pulls_url":"https://api.github.com/repos/rust-lang/book/pulls{/number}","milestones_url":"https://api.github.com/repos/rust-lang/book/milestones{/number}","notifications_url":"https://api.github.com/repos/rust-lang/book/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/rust-lang/book/labels{/name}","releases_url":"https://api.github.com/repos/rust-lang/book/releases{/id}","created_at":"2015-12-11T22:49:49Z","updated_at":"2016-01-14T00:42:18Z","pushed_at":"2016-01-14T06:02:14Z","git_url":"git://github.com/rust-lang/book.git","ssh_url":"git@github.com:rust-lang/book.git","clone_url":"https://github.com/rust-lang/book.git","svn_url":"https://github.com/rust-lang/book","homepage":"http://rust-lang.github.io/book/","size":1627,"stargazers_count":73,"watchers_count":73,"language":"HTML","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":16,"mirror_url":null,"open_issues_count":31,"forks":16,"open_issues":31,"watchers":73,"default_branch":"master"}},"base":{"label":"rust-lang:master","ref":"master","sha":"40c93504ddc35415b55626f067fd8883cae66ff6","user":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=3","gravatar_id":"","url":"https://api.github.com/users/rust-lang","html_url":"https://github.com/rust-lang","followers_url":"https://api.github.com/users/rust-lang/followers","following_url":"https://api.github.com/users/rust-lang/following{/other_user}","gists_url":"https://api.github.com/users/rust-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/rust-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rust-lang/subscriptions","organizations_url":"https://api.github.com/users/rust-lang/orgs","repos_url":"https://api.github.com/users/rust-lang/repos","events_url":"https://api.github.com/users/rust-lang/events{/privacy}","received_events_url":"https://api.github.com/users/rust-lang/received_events","type":"Organization","site_admin":false},"repo":{"id":47854924,"name":"book","full_name":"rust-lang/book","owner":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=3","gravatar_id":"","url":"https://api.github.com/users/rust-lang","html_url":"https://github.com/rust-lang","followers_url":"https://api.github.com/users/rust-lang/followers","following_url":"https://api.github.com/users/rust-lang/following{/other_user}","gists_url":"https://api.github.com/users/rust-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/rust-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rust-lang/subscriptions","organizations_url":"https://api.github.com/users/rust-lang/orgs","repos_url":"https://api.github.com/users/rust-lang/repos","events_url":"https://api.github.com/users/rust-lang/events{/privacy}","received_events_url":"https://api.github.com/users/rust-lang/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/rust-lang/book","description":"The Rust Programming Language","fork":false,"url":"https://api.github.com/repos/rust-lang/book","forks_url":"https://api.github.com/repos/rust-lang/book/forks","keys_url":"https://api.github.com/repos/rust-lang/book/keys{/key_id}","collaborators_url":"https://api.github.com/repos/rust-lang/book/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/rust-lang/book/teams","hooks_url":"https://api.github.com/repos/rust-lang/book/hooks","issue_events_url":"https://api.github.com/repos/rust-lang/book/issues/events{/number}","events_url":"https://api.github.com/repos/rust-lang/book/events","assignees_url":"https://api.github.com/repos/rust-lang/book/assignees{/user}","branches_url":"https://api.github.com/repos/rust-lang/book/branches{/branch}","tags_url":"https://api.github.com/repos/rust-lang/book/tags","blobs_url":"https://api.github.com/repos/rust-lang/book/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/rust-lang/book/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/rust-lang/book/git/refs{/sha}","trees_url":"https://api.github.com/repos/rust-lang/book/git/trees{/sha}","statuses_url":"https://api.github.com/repos/rust-lang/book/statuses/{sha}","languages_url":"https://api.github.com/repos/rust-lang/book/languages","stargazers_url":"https://api.github.com/repos/rust-lang/book/stargazers","contributors_url":"https://api.github.com/repos/rust-lang/book/contributors","subscribers_url":"https://api.github.com/repos/rust-lang/book/subscribers","subscription_url":"https://api.github.com/repos/rust-lang/book/subscription","commits_url":"https://api.github.com/repos/rust-lang/book/commits{/sha}","git_commits_url":"https://api.github.com/repos/rust-lang/book/git/commits{/sha}","comments_url":"https://api.github.com/repos/rust-lang/book/comments{/number}","issue_comment_url":"https://api.github.com/repos/rust-lang/book/issues/comments{/number}","contents_url":"https://api.github.com/repos/rust-lang/book/contents/{+path}","compare_url":"https://api.github.com/repos/rust-lang/book/compare/{base}...{head}","merges_url":"https://api.github.com/repos/rust-lang/book/merges","archive_url":"https://api.github.com/repos/rust-lang/book/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/rust-lang/book/downloads","issues_url":"https://api.github.com/repos/rust-lang/book/issues{/number}","pulls_url":"https://api.github.com/repos/rust-lang/book/pulls{/number}","milestones_url":"https://api.github.com/repos/rust-lang/book/milestones{/number}","notifications_url":"https://api.github.com/repos/rust-lang/book/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/rust-lang/book/labels{/name}","releases_url":"https://api.github.com/repos/rust-lang/book/releases{/id}","created_at":"2015-12-11T22:49:49Z","updated_at":"2016-01-14T00:42:18Z","pushed_at":"2016-01-14T06:02:14Z","git_url":"git://github.com/rust-lang/book.git","ssh_url":"git@github.com:rust-lang/book.git","clone_url":"https://github.com/rust-lang/book.git","svn_url":"https://github.com/rust-lang/book","homepage":"http://rust-lang.github.io/book/","size":1627,"stargazers_count":73,"watchers_count":73,"language":"HTML","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":16,"mirror_url":null,"open_issues_count":31,"forks":16,"open_issues":31,"watchers":73,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/rust-lang/book/pulls/58"},"html":{"href":"https://github.com/rust-lang/book/pull/58"},"issue":{"href":"https://api.github.com/repos/rust-lang/book/issues/58"},"comments":{"href":"https://api.github.com/repos/rust-lang/book/issues/58/comments"},"review_comments":{"href":"https://api.github.com/repos/rust-lang/book/pulls/58/comments"},"review_comment":{"href":"https://api.github.com/repos/rust-lang/book/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/rust-lang/book/pulls/58/commits"},"statuses":{"href":"https://api.github.com/repos/rust-lang/book/statuses/1045fa2c7b2420fb8abede6eab137c5b539f4ac5"}}}}