more code

mikeblome · mikeblome · commit 4d3200ccca5a · 2019-11-07T17:51:04.000-08:00
diff --git a/docs/cpp/pointers-cpp.md b/docs/cpp/pointers-cpp.md
@@ -6,25 +6,18 @@ ms.assetid: 595387c5-8e58-4670-848f-344c7caf985e
 ---
 # Pointers (C++)
 
-A pointer stores the address of a object in memory and is used to access that object. On 64-bit operating systems a pointer has a size of 64 bits; a system's pointer size determines how much addressable memory it can have. A pointer can point to a typed object or to **void**. A non-const pointer can be incremented or decremented, which causes it to point to a new location in memory. This is called *pointer arithmetic* and is used in C-style programming to iterate over elements in arrays or other data structures. A const pointer cannot be made to point to a different memory location, and in that sense is very similar to a [reference](references-cpp.md).
+A pointer stores the address of a object in memory and is used to access that object. On 64-bit operating systems a pointer has a size of 64 bits; a system's pointer size determines how much addressable memory it can have. A pointer can point to a typed object or to **void**. When a program allocates a new object on the [heap]() in memory, it receives the address of that object in the form of a pointer. Such pointers are called *owning pointers*; an owning pointer (or a copy of it) must be used to explicitly delete the heap-allocated object when it is no longer needed. Failure to delete the memory results in a *memory leak* and renders the memory unavailable to any other program on the machine.
 
-Pointers are used extensively in C++ to pass larger objects to and from functions because it is far more efficient to copy a 64-bit value than to copy an entire object. When a program allocates a new object on the [heap]() in memory, it receives the address of that object in the form of a pointer. Such pointers are called *owning pointers* because they must be used to explicitly delete the object when it is no longer needed. Pointers to functions enable functions to be passed to other functions and are used for "callbacks" in C-style programming.
+A pointer (if it is not declared as **const**) can be incremented or decremented so that it points to a new location in memory. This is called *pointer arithmetic* and is used in C-style programming to iterate over elements in arrays or other data structures. A **const** pointer cannot be made to point to a different memory location, and in that sense is very similar to a [reference](references-cpp.md).
 
-deferencing
+Pointers (along with references) are used extensively in C++ to pass larger objects to and from functions because it is usually far more efficient to copy a pointer than to copy an entire object. When defining a function, specify pointer parameters as **const** unless you intend for the function to modify the object. In general, **const** references are the preferred way to pass objects to functions unless the value of the object can possibly be **nullptr**.
 
-char* p ="Hello";
+Pointers to functions enable functions to be passed to other functions and are used for "callbacks" in C-style programming.
 
-print p vs. *p
+## Pointer errors
 
 In C and C++, pointer errors are by far the greatest cause of crashes, hangs, data corruption, security holes and general programmer misery. In modern C++, the use of *raw pointers* is strongly discouraged except in very specific scenarios. Modern C++ provides *smart pointers* for allocating objects, *iterators* for traversing data structures, and *lambda expressions* for passing callable functions. By using these language and library facilities instead of raw pointers, you will make your program safer, easier to debug, and simpler to understand and maintain.
 
-## Syntax
-
-```cpp
-MyClass* p;
-
-```
-
 ## Initialization and member access
 
 The following example shows how to declare a pointer and initialize it with an object allocated on the heap, and then how to use it. It also shows a few of the dangers associated with pointers.
@@ -69,36 +62,43 @@ int main()
 {
     // Use the * operator to declare a pointer type
     // Use new to allocate and initialize memory
-    MyClass* mc = new MyClass{ 108, "Mike" };
+    MyClass* pmc = new MyClass{ 108, "Mike" };
 
     // Prints the memory address. Usually not what you want.
-   // std:: cout << mc << std::endl;
+    std:: cout << pmc << std::endl;
+
+    // Copy the pointed-to object by dereferencing the pointer
+    // to access the contents of the memory location.
+    // mc is a separate object, allocated here on the stack
+    MyClass mc = *pmc;
+
+    // Declare a pointer that points to mc using the addressof operator
+    MyClass* pcopy = &mc;
 
     // Use the -> operator to access the object's public members
-    mc->print(); // "Mike, 108"
+    pmc->print(); // "Mike, 108"
 
-    // Copy the pointer. Now mc and mc2 point to same object!
-    MyClass* mc2 = mc;
+    // Copy the pointer. Now pmc and pmc2 point to same object!
+    MyClass* pmc2 = pmc;
 
     // Use copied pointer to modify the original object
-    mc2->name = "Lisa";
-    mc->print(); // "Lisa, 108"
-    mc2->print(); // "Lisa, 108"
+    pmc2->name = "Lisa";
+    pmc->print(); // "Lisa, 108"
+    pmc2->print(); // "Lisa, 108"
 
     // Pass the pointer to a function.
     func_A(mc);
-    mc->print(); // "Lisa, 3"
-    mc2->print(); // "Lisa, 3"
+    pmc->print(); // "Lisa, 3"
+    pmc2->print(); // "Lisa, 3"
 
     // Dereference the pointer and pass a copy
     // of the pointed-to object to a function
     func_B(*mc);
-    mc->print(); // "Lisa, 3" (original not modified by function)
+    pmc->print(); // "Lisa, 3" (original not modified by function)
 
-    delete(mc); // don't forget to give memory back to operating system!
-   // delete(mc2); //crash! memory location was already deleted
+    delete(pmc); // don't forget to give memory back to operating system!
+   // delete(pmc2); //crash! memory location was already deleted
 }
-
 ```
 
 ## Const pointers and pointers to const objects
@@ -110,19 +110,48 @@ A const pointer can point to either a const or non-const object, but can't be mo
 Certain arithmetic operations can be performed on non-const pointers to make them point to a new memory location. A pointer can be incremented and decremented using the **++**, **+=**, **-=** and **--** operators. This technique can be used in arrays and is especially useful in buffers of untyped data. A **void\*** increments by the size of a **char** (1 byte). A typed pointer increments by size of the type it points to. 
 
 ```cpp
-// pointers.cpp : This file contains the 'main' function. Program execution begins and ends there.
-//
+#include <iostream>
+#include <string>
+
+using namespace std;
 
+
+class MyClass
+{
+public:
+    int num;
+    std::string name;
+    void print() { std::cout << name << ":" << num << std::endl; }
+};
+
+
+int main()
+{
    // Pointer arithmetic may be done with an array declared
    // on the stack or allocated on the heap with new.
    // The increment operator takes into account the size
-   // of the objects pointed to.
-   p = new int[5];
-   for (i = 0; i < 5; i++, p++) {
-      *p = i * 10;
-      printf_s("0x%p %d\n", p, *p);
+   // of the objects pointed to. In this example p increments by sizeof(int)
+   int* p = new int[5];
+   for (i = 0; i < 5; i++, p++)
+   {
+      *p = i * 10; // set the value of the pointed-to int
+      printf_s("0x%p %d\n", p, *p); //print the pointer address, and the value of the pointed-to int
    }
 
+   MyClass arr[3];
+   arr[0] = {108, "Mike"};
+   arr[1] = {109, "Lisa"};
+   arr[2] = {110, "Tabby"};
+
+    // pmc increments by sizeof(MyClass):
+
+    MyClass* pmc = &arr[0];
+    cout << pmc->name; // Mike
+    pmc++;
+    cout << pmc->name; // Lisa
+    pmc++;
+    cout << pmc->name; //Tabby
+
    // A common expression seen is dereferencing in combination
    // with increment or decrement operators, as shown here.
    // The indirection operator * takes precedence over the
@@ -138,35 +167,7 @@ Certain arithmetic operations can be performed on non-const pointers to make the
 
    // s2 was copied into s1, so now they are both equal to "dog"
    printf_s("%s %s", s1, s2);
-
-#include <iostream>
-#include <string>
-
-using namespace std;
-
-class MyClass
-{
-public:
-    int num;
-    std::string name;
-    void print() { std::cout << name << ":" << num << std::endl; }
-};
-
-int main()
-{
-    MyClass arr[3];
-    arr[0] = {108, "Mike"};
-    arr[1] = {109, "Lisa"};
-    arr[2] = {110, "Tabby"};
-
-    MyClass* pmc = &arr[0];
-    cout << pmc->name;
-    pmc++;
-    cout << pmc->name;
-    pmc++;
-    cout << pmc->name;
 }
-
 ```
 
 ## void* pointers
@@ -176,33 +177,6 @@ A pointer to **void** simply points to a raw memory location. Sometimes it is un
 ## Pointers to functions
 
 TBD 
-
-> \[*storage-class-specifiers*] \[*cv-qualifiers*] *type-specifiers* \[*ms-modifier*] *declarator* **;**
-
-where any valid pointer declarator may be used for *declarator*. The syntax for a simple pointer declarator is as follows:
-
-> __\*__ \[*cv-qualifiers*] *identifier* \[**=** *expression*]
-
-1. The declaration specifiers:
-
-   - An optional storage class specifier. For more information, see [Specifiers](../cpp/specifiers.md).
-
-   - An optional **const** or **volatile** keyword applying to the type of the object to be pointed to.
-
-   - The type specifier: the name of a type representing the type of the object to be pointed to.
-
-1. The declarator:
-
-   - An optional Microsoft-specific modifier. For more information, see [Microsoft-Specific Modifiers](../cpp/microsoft-specific-modifiers.md).
-
-   - The __\*__ operator.
-
-   - An optional **const** or **volatile** keyword applying to the pointer itself.
-
-   - The identifier.
-
-   - An optional initializer.
-
 The declarator for a pointer to function looks like this:
 
 > __(\*__ \[*cv-qualifiers*] *identifier* **)(** *argument-list* **)** \[*cv-qualifers*] \[*exception-specification*] \[**=** *expression*] **;**
@@ -211,97 +185,6 @@ For an array of pointers, the syntax looks like this:
 
 > __\*__ *identifier* **\[** \[*constant-expression*] **]**
 
-Multiple declarators and their initializers may appear together in a single declaration in a comma separated list following the declaration specifier.
-
-A simple example of a pointer declaration is:
-
-```cpp
-char *pch;
-```
-
-The preceding declaration specifies that `pch` points to an object of type **char**.
-
-A more complex example is
-
-```cpp
-static unsigned int * const ptr;
-```
-
-The preceding declaration specifies that `ptr` is a constant pointer to an object of type **unsigned** **int** with static storage duration.
-
-The next example shows how multiple pointers are declared and initialized:
-
-```cpp
-static int *p = &i, *q = &j;
-```
-
-In the preceding example, pointers p and q both point to objects of type **int** and are initialized to the addresses of i and j respectively.  The storage class specifier **static** applies to both pointers.
-
-## Example
-
-```cpp
-// pointer.cpp
-// compile with: /EHsc
-#include <iostream>
-int main() {
-   int i = 1, j = 2; // local variables on the stack
-   int *p;
-
-   // a pointer may be assigned to "point to" the value of
-   // another variable using the & (address of) operator
-   p = &j;
-
-   // since j was on the stack, this address will be somewhere
-   // on the stack.  Pointers are printed in hex format using
-   // %p and conventionally marked with 0x.
-   printf_s("0x%p\n",  p);
-
-   // The * (indirection operator) can be read as "the value
-   // pointed to by".
-   // Since p is pointing to j, this should print "2"
-   printf_s("0x%p %d\n",  p, *p);
-
-   // changing j will change the result of the indirection
-   // operator on p.
-   j = 7;
-   printf_s("0x%p %d\n",  p, *p );
-
-   // The value of j can also be changed through the pointer
-   // by making an assignment to the dereferenced pointer
-   *p = 10;
-   printf_s("j is %d\n", j); // j is now 10
-
-   // allocate memory on the heap for an integer,
-   // initialize to 5
-   p = new int(5);
-
-   // print the pointer and the object pointed to
-   // the address will be somewhere on the heap
-   printf_s("0x%p %d\n",  p, *p);
-
-   // free the memory pointed to by p
-   delete p;
-
-   // At this point, dereferencing p with *p would trigger
-   // a runtime access violation.
-
-
-}
-```
-
-```Output
-0x0012FEC8
-0x0012FEC8 2
-0x0012FEC8 7
-j is 10
-0x00320850 5
-0x00320850 0
-0x00320854 10
-0x00320858 20
-0x0032085C 30
-0x00320860 40
-dog dog
-```
 
 ## Example
 
@@ -386,9 +269,9 @@ a (add node)  d (display list)  q (quit)
 
 ## Example
 
+The following example demonstrates how pointer arithmetic can be used to access individual pixels in a bitmap. Note the use of **new** and **delete**, and the dereference operator.
+
 ```cpp
-// pointer_arithmetic.cpp : This file contains the 'main' function. Program execution begins and ends there.
-//
 
 #include <iostream>
 #include <string>
@@ -419,15 +302,13 @@ int main()
     bf.bfReserved2 = 0;
     bf.bfOffBits = sizeof(BITMAPFILEHEADER) + sizeof(BITMAPINFOHEADER); //54
 
-    
     // Create a gray square with a 2-pixel wide outline
     unsigned char* begin = &buffer[0];
     unsigned char* end = &buffer[0] + bufferSize;
     unsigned char* p = begin;
     constexpr int pixelWidth = 3;
     constexpr int borderWidth = 2;
 
-    int  c = 0;
     while (p < end)
     {
             // is top or bottom row:
@@ -444,10 +325,8 @@ int main()
             *p = 0xC3;
         }
         p++; //increment one byte (char)
-        c++;
     }
 
-    cout << "c = " << c;
     ofstream wf(R"(box.bmp)", ios::out | ios::binary);
 
     wf.write(reinterpret_cast<char*>(&bf), sizeof(bf));
