Minor consistency cleanup

- Fixed an inconsistent title (section ToC and actual guideline title
differed)
- Can't reseat a reference, so changed it to pointer
- Removed what I think is a stray/outdated rule against passing
move-only types (unique_ptr) by &&
- Reordered a three-line example for logical flow
This commit is contained in:
hsutter 2017-03-16 08:54:26 -07:00
parent 55780020c1
commit dfb2a5b1fe

View File

@ -8008,7 +8008,7 @@ Here, we ignore such cases.
* [R.2: In interfaces, use raw pointers to denote individual objects (only)](#Rr-use-ptr)
* [R.3: A raw pointer (a `T*`) is non-owning](#Rr-ptr)
* [R.4: A raw reference (a `T&`) is non-owning](#Rr-ref)
* [R.5: Prefer scoped objects](#Rr-scoped)
* [R.5: Prefer scoped objects, don't heap-allocate unnecessarily](#Rr-scoped)
* [R.6: Avoid non-`const` global variables](#Rr-global)
* Allocation and deallocation rule summary:
@ -8267,7 +8267,7 @@ We want owners identified so that we can reliably and efficiently delete the obj
See [the raw pointer rule](#Rr-ptr)
### <a name="Rr-scoped"></a>R.5: Don't heap-allocate unnecessarily
### <a name="Rr-scoped"></a>R.5: Prefer scoped objects, don't heap-allocate unnecessarily
##### Reason
@ -8700,7 +8700,7 @@ Using `unique_ptr` in this way both documents and enforces the function call's o
void sink(unique_ptr<widget>); // consumes the widget
void sink(widget*); // just uses the widget
void uses(widget*); // just uses the widget
##### Example, bad
@ -8710,7 +8710,6 @@ Using `unique_ptr` in this way both documents and enforces the function call's o
* (Simple) Warn if a function takes a `Unique_ptr<T>` parameter by lvalue reference and does not either assign to it or call `reset()` on it on at least one code path. Suggest taking a `T*` or `T&` instead.
* (Simple) ((Foundation)) Warn if a function takes a `Unique_ptr<T>` parameter by reference to `const`. Suggest taking a `const T*` or `const T&` instead.
* (Simple) ((Foundation)) Warn if a function takes a `Unique_ptr<T>` parameter by rvalue reference. Suggest using pass by value instead.
### <a name="Rr-reseat"></a>R.33: Take a `unique_ptr<widget>&` parameter to express that a function reseats the`widget`
@ -8720,7 +8719,7 @@ Using `unique_ptr` in this way both documents and enforces the function call's r
##### Note
"reseat" means "making a reference or a smart pointer refer to a different object."
"reseat" means "making a pointer or a smart pointer refer to a different object."
##### Example
@ -8734,7 +8733,6 @@ Using `unique_ptr` in this way both documents and enforces the function call's r
* (Simple) Warn if a function takes a `Unique_ptr<T>` parameter by lvalue reference and does not either assign to it or call `reset()` on it on at least one code path. Suggest taking a `T*` or `T&` instead.
* (Simple) ((Foundation)) Warn if a function takes a `Unique_ptr<T>` parameter by reference to `const`. Suggest taking a `const T*` or `const T&` instead.
* (Simple) ((Foundation)) Warn if a function takes a `Unique_ptr<T>` parameter by rvalue reference. Suggest using pass by value instead.
### <a name="Rr-sharedptrparam-owner"></a>R.34: Take a `shared_ptr<widget>` parameter to express that a function is part owner
@ -8746,10 +8744,10 @@ This makes the function's ownership sharing explicit.
void share(shared_ptr<widget>); // share -- "will" retain refcount
void reseat(shared_ptr<widget>&); // "might" reseat ptr
void may_share(const shared_ptr<widget>&); // "might" retain refcount
void reseat(shared_ptr<widget>&); // "might" reseat ptr
##### Enforcement
* (Simple) Warn if a function takes a `Shared_ptr<T>` parameter by lvalue reference and does not either assign to it or call `reset()` on it on at least one code path. Suggest taking a `T*` or `T&` instead.