Merge pull request #2477 from mikeblome/mb-pointers

Update and improve pointers topic

Author: v-shils

docs/cpp/const-and-volatile-pointers.md

@@ -1,12 +1,12 @@
 ---
-title: "const and volatile Pointers"
-ms.date: "11/04/2016"
+title: "const and volatile pointers"
+ms.date: "11/19/2019"
 helpviewer_keywords: ["volatile keyword [C++], and pointers", "pointers, and const", "pointers, and volatile", "const keyword [C++], volatile pointers"]
 ms.assetid: 0c92dc6c-400e-4342-b345-63ddfe649d7e
 ---
-# const and volatile Pointers
+# const and volatile pointers
 
-The [const](../cpp/const-cpp.md) and [volatile](../cpp/volatile-cpp.md) keywords change how pointers are treated. The **const** keyword specifies that the pointer cannot be modified after initialization; the pointer is protected from modification thereafter.
+The [const](const-cpp.md) and [volatile](volatile-cpp.md) keywords change how pointers are treated. The **const** keyword specifies that the pointer cannot be modified after initialization; the pointer is protected from modification thereafter.
 
 The **volatile** keyword specifies that the value associated with the name that follows can be modified by actions other than those in the user application. Therefore, the **volatile** keyword is useful for declaring objects in shared memory that can be accessed by multiple processes or global data areas used for communication with interrupt service routines.
 
@@ -116,4 +116,5 @@ int main() {
 
 ## See also
 
-[Pointers](../cpp/pointers-cpp.md)
+[Pointers](pointers-cpp.md)
+[Raw pointers](raw-pointers.md)

docs/cpp/how-to-create-and-use-ccomptr-and-ccomqiptr-instances.md

@@ -1,11 +1,11 @@
 ---
-title: "How to: Create and Use CComPtr and CComQIPtr Instances"
+title: "How to: Create and use CComPtr and CComQIPtr instances"
 ms.custom: "how-to"
-ms.date: "11/04/2016"
+ms.date: "11/19/2019"
 ms.topic: "conceptual"
 ms.assetid: b0356cfb-12cc-4ee8-b988-8311ed1ab5e0
 ---
-# How to: Create and Use CComPtr and CComQIPtr Instances
+# How to: Create and use CComPtr and CComQIPtr instances
 
 In classic Windows programming, libraries are often implemented as COM objects (or more precisely, as COM servers). Many Windows operating system components are implemented as COM servers, and many contributors provide libraries in this form. For information about the basics of COM, see [Component Object Model (COM)](/windows/win32/com/component-object-model--com--portal).
 

docs/cpp/how-to-create-and-use-shared-ptr-instances.md

@@ -1,17 +1,17 @@
 ---
-title: "How to: Create and Use shared_ptr Instances"
+title: "How to: Create and use shared_ptr instances"
 ms.custom: "how-to"
-ms.date: "05/22/2019"
+ms.date: "11/19/2019"
 ms.topic: "conceptual"
 ms.assetid: 7d6ebb73-fa0d-4b0b-a528-bf05de96518e
 ---
-# How to: Create and Use shared_ptr Instances
+# How to: Create and Use shared_ptr instances
 
 The `shared_ptr` type is a smart pointer in the C++ standard library that is designed for scenarios in which more than one owner might have to manage the lifetime of the object in memory. After you initialize a `shared_ptr` you can copy it, pass it by value in function arguments, and assign it to other `shared_ptr` instances. All the instances point to the same object, and share access to one "control block" that increments and decrements the reference count whenever a new `shared_ptr` is added, goes out of scope, or is reset. When the reference count reaches zero, the control block deletes the memory resource and itself.
 
 The following illustration shows several `shared_ptr` instances that point to one memory location.
 
-![Shared pointer diagram](../cpp/media/shared_ptr.png "Shared pointer diagram")
+![Shared pointer diagram](media/shared_ptr.png "Shared pointer diagram")
 
 ## Example setup
 
@@ -68,25 +68,25 @@ int main()
 
 Whenever possible, use the [make_shared](../standard-library/memory-functions.md#make_shared) function to create a `shared_ptr` when the memory resource is created for the first time. `make_shared` is exception-safe. It uses the same call to allocate the memory for the control block and the resource, which reduces the construction overhead. If you don't use `make_shared`, then you have to use an explicit `new` expression to create the object before you pass it to the `shared_ptr` constructor. The following example shows various ways to declare and initialize a `shared_ptr` together with a new object.
 
-[!code-cpp[stl_smart_pointers#1](../cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_1.cpp)]
+[!code-cpp[stl_smart_pointers#1](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_1.cpp)]
 
 ## Example 2
 
 The following example shows how to declare and initialize `shared_ptr` instances that take on shared ownership of an object that has already been allocated by another `shared_ptr`. Assume that `sp2` is an initialized `shared_ptr`.
 
-[!code-cpp[stl_smart_pointers#2](../cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_2.cpp)]
+[!code-cpp[stl_smart_pointers#2](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_2.cpp)]
 
 ## Example 3
 
 `shared_ptr` is also helpful in C++ Standard Library containers when you're using algorithms that copy elements. You can wrap elements in a `shared_ptr`, and then copy it into other containers with the understanding that the underlying memory is valid as long as you need it, and no longer. The following example shows how to use the `remove_copy_if` algorithm on `shared_ptr` instances in a vector.
 
-[!code-cpp[stl_smart_pointers#4](../cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_3.cpp)]
+[!code-cpp[stl_smart_pointers#4](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_3.cpp)]
 
 ## Example 4
 
 You can use `dynamic_pointer_cast`, `static_pointer_cast`, and `const_pointer_cast` to cast a `shared_ptr`. These functions resemble the `dynamic_cast`, `static_cast`, and `const_cast` operators. The following example shows how to test the derived type of each element in a vector of `shared_ptr` of base classes, and then copy the elements and display information about them.
 
-[!code-cpp[stl_smart_pointers#5](../cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_4.cpp)]
+[!code-cpp[stl_smart_pointers#5](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_4.cpp)]
 
 ## Example 5
 
@@ -108,8 +108,8 @@ You can pass a `shared_ptr` to another function in the following ways:
 
 The following example shows how `shared_ptr` overloads various comparison operators to enable pointer comparisons on the memory that is owned by the `shared_ptr` instances.
 
-[!code-cpp[stl_smart_pointers#3](../cpp/codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_6.cpp)]
+[!code-cpp[stl_smart_pointers#3](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_6.cpp)]
 
 ## See also
 
-[Smart Pointers (Modern C++)](../cpp/smart-pointers-modern-cpp.md)
+[Smart Pointers (Modern C++)](smart-pointers-modern-cpp.md)

docs/cpp/how-to-create-and-use-unique-ptr-instances.md

@@ -1,51 +1,51 @@
 ---
-title: "How to: Create and Use unique_ptr Instances"
+title: "How to: Create and use unique_ptr instances"
 ms.custom: "how-to"
 ms.date: "11/19/2018"
 ms.topic: "conceptual"
 ms.assetid: 9a373030-e587-452f-b9a5-c5f9d58b7673
 ---
-# How to: Create and Use unique_ptr Instances
+# How to: Create and use unique_ptr instances
 
 A [unique_ptr](../standard-library/unique-ptr-class.md) does not share its pointer. It cannot be copied to another `unique_ptr`, passed by value to a function, or used in any C++ Standard Library algorithm that requires copies to be made. A `unique_ptr` can only be moved. This means that the ownership of the memory resource is transferred to another `unique_ptr` and the original `unique_ptr` no longer owns it. We recommend that you restrict an object to one owner, because multiple ownership adds complexity to the program logic. Therefore, when you need a smart pointer for a plain C++ object, use `unique_ptr`, and when you construct a `unique_ptr`, use the [make_unique](../standard-library/memory-functions.md#make_unique) helper function.
 
 The following diagram illustrates the transfer of ownership between two `unique_ptr` instances.
 
-![Moving the ownership of a unique_ptr](../cpp/media/unique_ptr.png "Moving the ownership of a unique_ptr")
+![Moving the ownership of a unique_ptr](media/unique_ptr.png "Moving the ownership of a unique_ptr")
 
 `unique_ptr` is defined in the `<memory>` header in the C++ Standard Library. It is exactly as efficient as a raw pointer and can be used in C++ Standard Library containers. The addition of `unique_ptr` instances to C++ Standard Library containers is efficient because the move constructor of the `unique_ptr` eliminates the need for a copy operation.
 
-## Example
+## Example 1
 
 The following example shows how to create `unique_ptr` instances and pass them between functions.
 
-[!code-cpp[stl_smart_pointers#210](../cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_1.cpp)]
+[!code-cpp[stl_smart_pointers#210](codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_1.cpp)]
 
 These examples demonstrate this basic characteristic of `unique_ptr`: it can be moved, but not copied. "Moving" transfers ownership to a new `unique_ptr` and resets the old `unique_ptr`.
 
-## Example
+## Example 2
 
 The following example shows how to create `unique_ptr` instances and use them in a vector.
 
-[!code-cpp[stl_smart_pointers#211](../cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_2.cpp)]
+[!code-cpp[stl_smart_pointers#211](codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_2.cpp)]
 
 In the range for  loop, notice that the `unique_ptr` is passed by reference. If you try to pass by value here, the compiler will throw an error because the `unique_ptr` copy constructor is deleted.
 
-## Example
+## Example 3
 
 The following example shows how to initialize a `unique_ptr` that is a class member.
 
-[!code-cpp[stl_smart_pointers#212](../cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_3.cpp)]
+[!code-cpp[stl_smart_pointers#212](codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_3.cpp)]
 
-## Example
+## Example 4
 
 You can use [make_unique](../standard-library/memory-functions.md#make_unique) to create a `unique_ptr` to an array, but you cannot use `make_unique` to initialize the array elements.
 
-[!code-cpp[stl_smart_pointers#213](../cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_4.cpp)]
+[!code-cpp[stl_smart_pointers#213](codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_4.cpp)]
 
 For more examples, see [make_unique](../standard-library/memory-functions.md#make_unique).
 
 ## See also
 
-[Smart Pointers (Modern C++)](../cpp/smart-pointers-modern-cpp.md)<br/>
+[Smart Pointers (Modern C++)](smart-pointers-modern-cpp.md)<br/>
 [make_unique](../standard-library/memory-functions.md#make_unique)

docs/cpp/how-to-create-and-use-weak-ptr-instances.md

@@ -1,15 +1,15 @@
 ---
-title: "How to: Create and Use weak_ptr Instances"
+title: "How to: Create and use weak_ptr instances"
 ms.custom: "how-to"
-ms.date: "09/18/2019"
+ms.date: "11/19/2019"
 ms.topic: "conceptual"
 ms.assetid: 8dd6909b-b070-4afa-9696-f2fc94579c65
 ---
-# How to: Create and Use weak_ptr Instances
+# How to: Create and use weak_ptr instances
 
-Sometimes an object must store a way to access the underlying object of a `shared_ptr` without causing the reference count to be incremented. Typically, this situation occurs when you have cyclic references between `shared_ptr` instances.
+Sometimes an object must store a way to access the underlying object of a [shared_ptr](../standard-library/shared-ptr-class.md) without causing the reference count to be incremented. Typically, this situation occurs when you have cyclic references between `shared_ptr` instances.
 
-The best design is to avoid shared ownership of pointers whenever you can. However, if you must have shared ownership of `shared_ptr` instances, avoid cyclic references between them. When cyclic references are unavoidable, or even preferable for some reason, use `weak_ptr` to give one or more of the owners a weak reference to another `shared_ptr`. By using a `weak_ptr`, you can create a `shared_ptr` that joins to an existing set of related instances, but only if the underlying memory resource is still valid. A `weak_ptr` itself does not participate in the reference counting, and therefore, it cannot prevent the reference count from going to zero. However, you can use a `weak_ptr` to try to obtain a new copy of the `shared_ptr` with which it was initialized. If the memory has already been deleted, the `weak_ptr`'s bool operator returns `false`. If the memory is still valid, the new shared pointer increments the reference count and guarantees that the memory will be valid as long as the `shared_ptr` variable stays in scope.
+The best design is to avoid shared ownership of pointers whenever you can. However, if you must have shared ownership of `shared_ptr` instances, avoid cyclic references between them. When cyclic references are unavoidable, or even preferable for some reason, use [weak_ptr](../standard-library/weak-ptr-class.md) to give one or more of the owners a weak reference to another `shared_ptr`. By using a `weak_ptr`, you can create a `shared_ptr` that joins to an existing set of related instances, but only if the underlying memory resource is still valid. A `weak_ptr` itself does not participate in the reference counting, and therefore, it cannot prevent the reference count from going to zero. However, you can use a `weak_ptr` to try to obtain a new copy of the `shared_ptr` with which it was initialized. If the memory has already been deleted, the `weak_ptr`'s bool operator returns `false`. If the memory is still valid, the new shared pointer increments the reference count and guarantees that the memory will be valid as long as the `shared_ptr` variable stays in scope.
 
 ## Example
 

docs/cpp/new-and-delete-operators.md

@@ -1,13 +1,13 @@
 ---
 title: "new and delete Operators"
-ms.date: "05/07/2019"
+ms.date: "11/19/2019"
 f1_keywords: ["delete_cpp", "new"]
 helpviewer_keywords: ["new keyword [C++]", "delete keyword [C++]"]
 ms.assetid: fa721b9e-0374-4f04-bb87-032ea775bcc8
 ---
-# new and delete Operators
+# new and delete operators
 
-C++ supports dynamic allocation and deallocation of objects using the [new](../cpp/new-operator-cpp.md) and [delete](../cpp/delete-operator-cpp.md) operators. These operators allocate memory for objects from a pool called the free store. The **new** operator calls the special function [operator new](../cpp/new-operator-cpp.md), and the **delete** operator calls the special function [operator delete](../cpp/delete-operator-cpp.md).
+C++ supports dynamic allocation and deallocation of objects using the [new](new-operator-cpp.md) and [delete](delete-operator-cpp.md) operators. These operators allocate memory for objects from a pool called the free store. The **new** operator calls the special function [operator new](new-operator-cpp.md), and the **delete** operator calls the special function [operator delete](delete-operator-cpp.md).
 
 The **new** function in the C++ Standard Library supports the behavior specified in the C++ standard, which is to throw a std::bad_alloc exception if the memory allocation fails. If you still want the non-throwing version of **new**, link your program with nothrownew.obj. However, when you link with nothrownew.obj, the default **operator new** in the C++ Standard Library no longer functions.
 
@@ -21,13 +21,13 @@ When a statement such as the following is encountered in a program, it translate
 char *pch = new char[BUFFER_SIZE];
 ```
 
-If the request is for zero bytes of storage, **operator new** returns a pointer to a distinct object (that is, repeated calls to **operator new** return different pointers). If there is insufficient memory for the allocation request, **operator new** throws a std::bad_alloc exception, or returns **nullptr** if you have linked in non-throwing **operator new** support.
+If the request is for zero bytes of storage, **operator new** returns a pointer to a distinct object (that is, repeated calls to **operator new** return different pointers). If there is insufficient memory for the allocation request, **operator new** throws a `std::bad_alloc` exception, or returns **nullptr** if you have linked in non-throwing **operator new** support.
 
 You can write a routine that attempts to free memory and retry the allocation; see [_set_new_handler](../c-runtime-library/reference/set-new-handler.md) for more information. For more details on the recovery scheme, see the Handling insufficient memory section of this topic.
 
 The two scopes for **operator new** functions are described in the following table.
 
-### Scope for operator new Functions
+### Scope for operator new functions
 
 |Operator|Scope|
 |--------------|-----------|
@@ -41,7 +41,6 @@ The global **operator new** function is called when the **new** operator is used
 An **operator new** function defined for a class is a static member function (which cannot, therefore, be virtual) that hides the global **operator new** function for objects of that class type. Consider the case where **new** is used to allocate and set memory to a given value:
 
 ```cpp
-// spec1_the_operator_new_function1.cpp
 #include <malloc.h>
 #include <memory.h>
 
@@ -77,7 +76,6 @@ Blanks *SomeBlanks = new Blanks;
 The compiler supports member array **new** and **delete** operators in a class declaration. For example:
 
 ```cpp
-// spec1_the_operator_new_function2.cpp
 class MyClass
 {
 public:
@@ -99,11 +97,9 @@ int main()
 
 ### Handling insufficient memory
 
-Testing for failed memory allocation can be done with code such as the following:
+Testing for failed memory allocation can be done as shown here:
 
 ```cpp
-// insufficient_memory_conditions.cpp
-// compile with: /EHsc
 #include <iostream>
 using namespace std;
 #define BIG_NUMBER 100000000
@@ -116,7 +112,7 @@ int main() {
 }
 ```
 
-There is another ways to handle failed memory allocation requests: write a custom recovery routine to handle such a failure, then register your function by calling the [_set_new_handler](../c-runtime-library/reference/set-new-handler.md) run-time function.
+There is another way to handle failed memory allocation requests. Write a custom recovery routine to handle such a failure, then register your function by calling the [_set_new_handler](../c-runtime-library/reference/set-new-handler.md) run-time function.
 
 ##  <a id="delete_operator"> </a> The delete operator
 
@@ -133,16 +129,13 @@ void operator delete( void *, size_t );
 
 Only one of the preceding two forms can be present for a given class. The first form takes a single argument of type `void *`, which contains a pointer to the object to deallocate. The second form—sized deallocation—takes two arguments, the first of which is a pointer to the memory block to deallocate and the second of which is the number of bytes to deallocate. The return type of both forms is **void** (**operator delete** cannot return a value).
 
-The intent of the second form is to speed up searching for the correct size category of the object to be deleted, which is often not stored near the allocation itself and likely uncached; the second form is particularly useful when an **operator delete** function from a base class is used to delete an object of a derived class.
+The intent of the second form is to speed up searching for the correct size category of the object to be deleted, which is often not stored near the allocation itself and likely uncached. The second form is useful when an **operator delete** function from a base class is used to delete an object of a derived class.
 
-The **operator delete** function is static; therefore, it cannot be virtual. The **operator delete** function obeys access control, as described in [Member-Access Control](../cpp/member-access-control-cpp.md).
+The **operator delete** function is static; therefore, it cannot be virtual. The **operator delete** function obeys access control, as described in [Member-Access Control](member-access-control-cpp.md).
 
 The following example shows user-defined **operator new** and **operator delete** functions designed to log allocations and deallocations of memory:
 
 ```cpp
-// spec1_the_operator_delete_function1.cpp
-// compile with: /EHsc
-// arguments: 3
 #include <iostream>
 using namespace std;
 
@@ -207,4 +200,4 @@ void f() {
    X *pX = new X[5];
    delete [] pX;
 }
-```
+```