From 213063730183648cd84767f30503eb1697c6344b Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Thu, 6 Oct 2016 10:47:55 +0200 Subject: [PATCH 1/5] Book: Be very explicit of lifetimes being descriptive ... no prescriptive. Pointed out in https://users.rust-lang.org/t/what-if-i-get-lifetimes-wrong/7535/4, which was a revelation to me and made me think this should be more clear in the book. --- src/doc/book/lifetimes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/doc/book/lifetimes.md b/src/doc/book/lifetimes.md index f7d9c94bc454f..9918c24e17586 100644 --- a/src/doc/book/lifetimes.md +++ b/src/doc/book/lifetimes.md @@ -56,6 +56,8 @@ To fix this, we have to make sure that step four never happens after step three. The ownership system in Rust does this through a concept called lifetimes, which describe the scope that a reference is valid for. +*Note* It's important to understand that lifetimes are _descriptive_ not _prescriptive_. This means that the lifetimes of references are determined by the code, not by the lifetime annotations. The annotations, however, point out the lifetimes to the compiler in case it can't figure them out by itself. + When we have a function that takes an argument by reference, we can be implicit or explicit about the lifetime of the reference: From 7f02eb387d490932d45fa82ae755bceced94a698 Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Thu, 6 Oct 2016 11:15:47 +0200 Subject: [PATCH 2/5] Distinguish lifetimes and their annotations Also, emphasize differently. --- src/doc/book/lifetimes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/lifetimes.md b/src/doc/book/lifetimes.md index 9918c24e17586..da73c0c9ea2b4 100644 --- a/src/doc/book/lifetimes.md +++ b/src/doc/book/lifetimes.md @@ -56,7 +56,7 @@ To fix this, we have to make sure that step four never happens after step three. The ownership system in Rust does this through a concept called lifetimes, which describe the scope that a reference is valid for. -*Note* It's important to understand that lifetimes are _descriptive_ not _prescriptive_. This means that the lifetimes of references are determined by the code, not by the lifetime annotations. The annotations, however, point out the lifetimes to the compiler in case it can't figure them out by itself. +**Note** It's important to understand that lifetime annotations are _descriptive_ not _prescriptive_. This means that the lifetimes of references are determined by the code, not by the annotations. The annotations, however, point out the lifetimes to the compiler in case it can't figure them out by itself. When we have a function that takes an argument by reference, we can be implicit or explicit about the lifetime of the reference: From a54230239310ab5a20b1c23fd4341b938d0fd2a4 Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Thu, 6 Oct 2016 11:52:30 +0200 Subject: [PATCH 3/5] Another shot at clarity --- src/doc/book/lifetimes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/lifetimes.md b/src/doc/book/lifetimes.md index da73c0c9ea2b4..9d30aa85f3f45 100644 --- a/src/doc/book/lifetimes.md +++ b/src/doc/book/lifetimes.md @@ -56,7 +56,7 @@ To fix this, we have to make sure that step four never happens after step three. The ownership system in Rust does this through a concept called lifetimes, which describe the scope that a reference is valid for. -**Note** It's important to understand that lifetime annotations are _descriptive_ not _prescriptive_. This means that the lifetimes of references are determined by the code, not by the annotations. The annotations, however, point out the lifetimes to the compiler in case it can't figure them out by itself. +**Note** It's important to understand that lifetime annotations are _descriptive_ not _prescriptive_. This means that who long a reference is valid is determined by the code, not by the annotations. The annotations, however, point out this fact to the compiler in case it can't figure it out by itself. When we have a function that takes an argument by reference, we can be implicit or explicit about the lifetime of the reference: From 2a0bd6db856929315876b2b875e5fcf22832ff58 Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Thu, 6 Oct 2016 11:53:53 +0200 Subject: [PATCH 4/5] Typos --- src/doc/book/lifetimes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/lifetimes.md b/src/doc/book/lifetimes.md index 9d30aa85f3f45..652ed9d2f7379 100644 --- a/src/doc/book/lifetimes.md +++ b/src/doc/book/lifetimes.md @@ -56,7 +56,7 @@ To fix this, we have to make sure that step four never happens after step three. The ownership system in Rust does this through a concept called lifetimes, which describe the scope that a reference is valid for. -**Note** It's important to understand that lifetime annotations are _descriptive_ not _prescriptive_. This means that who long a reference is valid is determined by the code, not by the annotations. The annotations, however, point out this fact to the compiler in case it can't figure it out by itself. +**Note** It's important to understand that lifetime annotations are _descriptive_, not _prescriptive_. This means that how long a reference is valid is determined by the code, not by the annotations. The annotations, however, point out this fact to the compiler in case it can't figure it out by itself. When we have a function that takes an argument by reference, we can be implicit or explicit about the lifetime of the reference: From 0d0cdb77dfe5efc9ded30e6ab8b175d602b07223 Mon Sep 17 00:00:00 2001 From: KillTheMule Date: Fri, 7 Oct 2016 08:48:19 +0200 Subject: [PATCH 5/5] Wrap & improve --- src/doc/book/lifetimes.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/doc/book/lifetimes.md b/src/doc/book/lifetimes.md index 652ed9d2f7379..e865609f217f0 100644 --- a/src/doc/book/lifetimes.md +++ b/src/doc/book/lifetimes.md @@ -56,10 +56,12 @@ To fix this, we have to make sure that step four never happens after step three. The ownership system in Rust does this through a concept called lifetimes, which describe the scope that a reference is valid for. -**Note** It's important to understand that lifetime annotations are _descriptive_, not _prescriptive_. This means that how long a reference is valid is determined by the code, not by the annotations. The annotations, however, point out this fact to the compiler in case it can't figure it out by itself. - -When we have a function that takes an argument by reference, we can be -implicit or explicit about the lifetime of the reference: +**Note** It's important to understand that lifetime annotations are +_descriptive_, not _prescriptive_. This means that how long a reference is valid +is determined by the code, not by the annotations. The annotations, however, +give information about lifetimes to the compiler that uses them to check the +validity of references. The compiler can do so without annotations in simple +cases, but needs the programmers support in complex scenarios. ```rust // implicit