Merge remote-tracking branch 'refs/remotes/origin/master' into cr-build-error

Author: Colin Robertson

docs/TOC.md

@@ -1,6 +1,6 @@
-# [Visual C++ in Visual Studio 2017 RC](top/visual-cpp-in-visual-studio.md)
-# [What's New for Visual C++ in Visual Studio 2017 RC](top/what-s-new-for-visual-cpp-in-visual-studio.md)
-# [Supported Platforms (Visual C++)](top/supported-platforms-visual-cpp.md)
+# [Visual C++ in Visual Studio 2017 RC](visual-cpp-in-visual-studio.md)
+# [What's New for Visual C++ in Visual Studio 2017 RC](what-s-new-for-visual-cpp-in-visual-studio.md)
+# [Supported Platforms (Visual C++)](supported-platforms-visual-cpp.md)
 # [C Language](c-language/c-language-reference.md)
 # [C++ Language](cpp/cpp-language-reference.md)
 # [C/C++ Preprocessor](preprocessor/c-cpp-preprocessor-reference.md)
@@ -9,17 +9,17 @@
 # [Windows Development](windows/overview-of-windows-programming-in-cpp.md)
 # [Linux Development](linux/download-install-and-setup-the-linux-development-workload.md)
 # [.NET Development with C++/CLI](dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md)
-# [Cloud and Web Programming in Visual C++](top/cloud-and-web-programming-in-visual-cpp.md)
-## [C++ REST SDK (Codename "Casablanca")](top/cpp-rest-sdk-codename-casablanca.md)
+# [Cloud and Web Programming in Visual C++](cloud/cloud-and-web-programming-in-visual-cpp.md)
+## [C++ REST SDK (Codename "Casablanca")](cloud/cpp-rest-sdk-codename-casablanca.md)
 # [Parallel Programming](parallel/parallel-programming-in-visual-cpp.md)
 # [Data Access](data/data-access-programming-mfc-atl.md)
 # [Text and Strings](text/text-and-strings-in-visual-cpp.md)
 # [Using the Visual Studio IDE for C++](ide/ide-and-tools-for-visual-cpp-development.md)
 # [Compilers and Build Tools](build/building-c-cpp-programs.md)
 # [Porting and Upgrading Visual C++ Code](porting/visual-cpp-porting-and-upgrading-guide.md)
-# [Security Best Practices for C++](top/security-best-practices-for-cpp.md)
-## [Running as a Member of the Users Group](top/running-as-a-member-of-the-users-group.md)
-## [How User Account Control (UAC) Affects Your Application](top/how-user-account-control-uac-affects-your-application.md)
-# [Visual C++ Samples](top/visual-cpp-samples.md)
-# [Visual C++ Help and Community](top/visual-cpp-help-and-community.md)
-# [How to Report a Problem with the Visual C++ Toolset](top/how-to-report-a-problem-with-the-visual-cpp-toolset.md)
+# [Security Best Practices for C++](security/security-best-practices-for-cpp.md)
+## [Running as a Member of the Users Group](security/running-as-a-member-of-the-users-group.md)
+## [How User Account Control (UAC) Affects Your Application](security/how-user-account-control-uac-affects-your-application.md)
+# [Visual C++ Samples](visual-cpp-samples.md)
+# [Visual C++ Help and Community](visual-cpp-help-and-community.md)
+# [How to Report a Problem with the Visual C++ Toolset](how-to-report-a-problem-with-the-visual-cpp-toolset.md)

docs/_breadcrumb/toc.yml

@@ -117,4 +117,10 @@
         topicHref: /cpp/porting/porting-and-upgrading-guide
       - name: Text and Strings
         tocHref: /cpp/text/
-        topicHref: /cpp/text/text-and-strings
+        topicHref: /cpp/text/text-and-strings
+      - name: Security
+        tocHref: /cpp/security
+        topicHref: /cpp/security/security-best-practices-for-cpp
+      - name: Cloud and Web
+        tocHref: /cpp/cloud
+        topicHref: /cpp/cloud/cloud-and-web-programming-in-visual-cpp

docs/atl-mfc-shared/memory-management-with-cstringt.md

@@ -54,5 +54,5 @@ Class [CStringT](../atl-mfc-shared/reference/cstringt-class.md) is a template cl
 -   [CFixedStringT: An Example of a Custom String Manager](../atl-mfc-shared/cfixedstringt-example-of-a-custom-string-manager.md)  
 
 ## See Also  
- [CustomString sample](../top/visual-cpp-samples.md)
+ [CustomString sample](../visual-cpp-samples.md)
 

docs/atl-mfc-shared/reference/cimage-class.md

@@ -1504,8 +1504,8 @@ BOOL TransparentBlt(CImage* pSrcImage, CImage* pDstImage, int xDest, int yDest,
 
 
 ## See Also  
- [MMXSwarm Sample](../../top/visual-cpp-samples.md)   
- [SimpleImage Sample](../../top/visual-cpp-samples.md)   
+ [MMXSwarm Sample](../../visual-cpp-samples.md)   
+ [SimpleImage Sample](../../visual-cpp-samples.md)   
  [Device-Independent Bitmaps](http://msdn.microsoft.com/library/windows/desktop/dd183562)   
  [CreateDIBSection](http://msdn.microsoft.com/library/windows/desktop/dd183494)   
  [ATL COM Desktop Components](../../atl/atl-com-desktop-components.md)

docs/atl-mfc-shared/reference/cpoint-class.md

@@ -366,7 +366,7 @@ CSize operator-(POINT point) const throw();
  [!code-cpp[NVC_ATLMFC_Utilities#34](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_7.cpp)]  
 
 ## See Also  
- [MFC Sample MDI](../../top/visual-cpp-samples.md)   
+ [MFC Sample MDI](../../visual-cpp-samples.md)   
  [Hierarchy Chart](../../mfc/hierarchy-chart.md)   
  [POINT Structure](../../mfc/reference/point-structure1.md)   
  [CRect Class](../../atl-mfc-shared/reference/crect-class.md)   

docs/atl-mfc-shared/reference/csimplestringt-class.md

@@ -268,7 +268,7 @@ static void CopyCharsOverlapped(XCHAR* pchDest, const XCHAR* pchSrc, int nChars
  Call this method to copy characters from `pchSrc` to the `pchDest` string. Unlike `CopyChars`, `CopyCharsOverlapped` provides a safe method for copying from character buffers that might be overlapped.  
 
 ## Example  
- See the example for [CSimpleStringT::CopyChars](#csimplestringt__CopyChars), or the source code for `CSimpleStringT::SetString` (located in atlsimpstr.h).  
+ See the example for [CSimpleStringT::CopyChars](#csimplestringt__copychars), or the source code for `CSimpleStringT::SetString` (located in atlsimpstr.h).  
 
 ### Requirements  
  **Header:** atlsimpstr.h  
@@ -356,7 +356,7 @@ Frees any extra memory previously allocated by the string but no longer needed.
 void FreeExtra();  
 ```  
 ### Remarks  
- This should reduce the memory overhead consumed by the string object. The method reallocates the buffer to the exact length returned by [GetLength](#csimplestringt__GetLength).  
+ This should reduce the memory overhead consumed by the string object. The method reallocates the buffer to the exact length returned by [GetLength](#csimplestringt__getlength).  
 
 ## Example  
 ```cpp  
@@ -409,7 +409,7 @@ int GetAllocLength() const throw();
  The number of characters allocated for this object.  
   
 ### Remarks  
- Call this method to determine the number of characters allocated for this `CSimpleStringT` object. See [FreeExtra](#csimplestringt__FreeExtra) for an example of calling this function.  
+ Call this method to determine the number of characters allocated for this `CSimpleStringT` object. See [FreeExtra](#csimplestringt__freeextra) for an example of calling this function.  
   
 ### Requirements  
  **Header:** atlsimpstr.h  
@@ -426,7 +426,7 @@ XCHAR GetAt(int iChar
 ```  
 #### Parameters  
  `iChar`  
- Zero-based index of the character in the `CSimpleStringT` object. The `iChar` parameter must be greater than or equal to 0 and less than the value returned by [GetLength](#csimplestringt__GetLength). Otherwise, `GetAt` will generate an exception.  
+ Zero-based index of the character in the `CSimpleStringT` object. The `iChar` parameter must be greater than or equal to 0 and less than the value returned by [GetLength](#csimplestringt__getlength). Otherwise, `GetAt` will generate an exception.  
 
 ### Return Value  
  An `XCHAR` that contains the character at the specified position in the string.  
@@ -458,15 +458,15 @@ PXSTR GetBuffer();
  `nMinBufferLength`  
  The minimum number of characters that the character buffer can hold. This value does not include space for a null terminator.  
   
- If `nMinBufferLength` is larger than the length of the current buffer, `GetBuffer` destroys the current buffer, replaces it with a buffer of the requested size, and resets the object reference count to zero. If you have previously called [LockBuffer](#csimplestringt__LockBuffer) on this buffer, you lose the buffer lock.  
+ If `nMinBufferLength` is larger than the length of the current buffer, `GetBuffer` destroys the current buffer, replaces it with a buffer of the requested size, and resets the object reference count to zero. If you have previously called [LockBuffer](#csimplestringt__lockbuffer) on this buffer, you lose the buffer lock.  
   
 ### Return Value  
  An `PXSTR` pointer to the object's (null-terminated) character buffer.  
   
 ### Remarks  
  Call this method to return the buffer contents of the `CSimpleStringT` object. The returned `PXSTR` is not a constant and therefore allows direct modification of `CSimpleStringT` contents.  
   
- If you use the pointer returned by `GetBuffer` to change the string contents, you must call [ReleaseBuffer](#csimplestringt__ReleaseBuffer) before you use any other `CSimpleStringT` member methods.  
+ If you use the pointer returned by `GetBuffer` to change the string contents, you must call [ReleaseBuffer](#csimplestringt__releasebuffer) before you use any other `CSimpleStringT` member methods.  
   
  The address returned by `GetBuffer` may not be valid after the call to `ReleaseBuffer` because additional `CSimpleStringT` operations can cause the `CSimpleStringT` buffer to be reallocated. The buffer is not reallocated if you do not change the length of the `CSimpleStringT`.  
   
@@ -511,7 +511,7 @@ PXSTR GetBufferSetLength(int nLength);
 ### Remarks  
  Call this method to retrieve a specified length of the internal buffer of the `CSimpleStringT` object. The returned `PXSTR` pointer is not `const` and thus allows direct modification of `CSimpleStringT` contents.  
 
- If you use the pointer returned by [GetBufferSetLength](#vclrfcsimplestringtgetbuffersetlength) to change the string contents, call `ReleaseBuffer` to update the internal state of `CsimpleStringT` before you use any other `CSimpleStringT` methods.  
+ If you use the pointer returned by [GetBufferSetLength](#csimplestringt__getbuffersetlength) to change the string contents, call `ReleaseBuffer` to update the internal state of `CsimpleStringT` before you use any other `CSimpleStringT` methods.  
 
  The address returned by `GetBufferSetLength` may not be valid after the call to `ReleaseBuffer` because additional `CSimpleStringT` operations can cause the `CSimpleStringT` buffer to be reallocated. The buffer is not reassigned if you do not change the length of the `CSimpleStringT`.  
 
@@ -563,7 +563,7 @@ int GetLength() const throw();
 ### Remarks  
  Call this method to return the number of characters in the object. The count does not include a null terminator.  
   
- For multibyte character sets (MBCS), `GetLength` counts each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two bytes. See [FreeExtra](#csimplestringt__FreeExtra) for an example of calling this function.  
+ For multibyte character sets (MBCS), `GetLength` counts each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two bytes. See [FreeExtra](#csimplestringt__freeextra) for an example of calling this function.  
   
 ### Requirements  
  **Header:** atlsimpstr.h  
@@ -665,10 +665,10 @@ PXSTR LockBuffer();
   
  By locking the string in the buffer, you ensure that the string's exclusive hold on the buffer will remain intact.  
   
- After you have finished with `LockBuffer`, call [UnlockBuffer](#csimplestringt__UnlockBuffer) to reset the reference count to 1.  
+ After you have finished with `LockBuffer`, call [UnlockBuffer](#csimplestringt__unlockbuffer) to reset the reference count to 1.  
   
 > [!NOTE]
->  If you call [GetBuffer](#csimplestringt__GetBuffer) on a locked buffer and you set the `GetBuffer` parameter `nMinBufferLength` to greater than the length of the current buffer, you will lose the buffer lock. Such a call to `GetBuffer` destroys the current buffer, replaces it with a buffer of the requested size, and resets the reference count to zero.  
+>  If you call [GetBuffer](#csimplestringt__getbuffer) on a locked buffer and you set the `GetBuffer` parameter `nMinBufferLength` to greater than the length of the current buffer, you will lose the buffer lock. Such a call to `GetBuffer` destroys the current buffer, replaces it with a buffer of the requested size, and resets the reference count to zero.  
   
  For more information about reference counting, see the following articles:  
   
@@ -708,7 +708,7 @@ XCHAR operator[](int iChar
  Zero-based index of a character in the string.  
 
 ### Remarks  
- The overloaded subscript (`[]`) operator returns a single character specified by the zero-based index in `iChar`. This operator is a convenient substitute for the [GetAt](#csimplestringt__GetAt) member function.  
+ The overloaded subscript (`[]`) operator returns a single character specified by the zero-based index in `iChar`. This operator is a convenient substitute for the [GetAt](#csimplestringt__getat) member function.  
 
 > [!NOTE]
 >  You can use the subscript (`[]`) operator to get the value of a character in a `CSimpleStringT`, but you cannot use it to change the value of a character in a `CSimpleStringT`.  
@@ -723,6 +723,27 @@ ASSERT(s[1] == _T('b'));
   
 ### Requirements  
  **Header:** atlsimpstr.h  
+
+## <a name="csimplestringt__operator_at"></a>  CSimpleStringT::operator \[\]
+Call this function to access a single character of the character array.  
+  
+### Syntax  
+  
+```  
+  
+XCHAR operator[]( int iChar ) const;  
+```  
+  
+### Parameters  
+ `iChar`  
+ Zero-based index of a character in the string.  
+  
+### Remarks  
+ The overloaded subscript (`[]`) operator returns a single character specified by the zero-based index in `iChar`. This operator is a convenient substitute for the [GetAt](#csimplestringt__getat) member function.  
+  
+> [!NOTE]
+>  You can use the subscript (`[]`) operator to get the value of a character in a `CSimpleStringT`, but you cannot use it to change the value of a character in a `CSimpleStringT`.  
+  
   
 ##  <a name="csimplestringt__operator_add_eq"></a>  CSimpleStringT::operator +=  
 Joins a new string or character to the end of an existing string.  
@@ -916,7 +937,7 @@ typedef ChTraitsBase< BaseType >::PXSTR PXSTR;
 
 
 ##  <a name="csimplestringt__releasebuffer"></a>  CSimpleStringT::ReleaseBuffer  
-Releases control of the buffer allocated by [GetBuffer](#csimplestringt__GetBuffer).  
+Releases control of the buffer allocated by [GetBuffer](#csimplestringt__getbuffer).  
   
 ### Syntax  
   
@@ -928,7 +949,7 @@ void ReleaseBuffer(int nNewLength = -1);
  The new length of the string in characters, not counting a null terminator. If the string is null terminated, the -1 default value sets the `CSimpleStringT` size to the current length of the string.  
   
 ### Remarks  
- Call this method to reallocate or free up the buffer of the string object. If you know that the string in the buffer is null terminated, you can omit the `nNewLength` argument. If your string is not null terminated, use `nNewLength` to specify its length. The address returned by [GetBuffer](#csimplestringt__GetBuffer) is invalid after the call to `ReleaseBuffer` or any other `CSimpleStringT` operation.  
+ Call this method to reallocate or free up the buffer of the string object. If you know that the string in the buffer is null terminated, you can omit the `nNewLength` argument. If your string is not null terminated, use `nNewLength` to specify its length. The address returned by [GetBuffer](#csimplestringt__getbuffer) is invalid after the call to `ReleaseBuffer` or any other `CSimpleStringT` operation.  
   
 ## Example  
  The following example demonstrates the use of `CSimpleStringT::ReleaseBuffer`.  
@@ -950,7 +971,7 @@ ASSERT(s.GetLength() == 3); // Length still 3
 
 ##  <a name="csimplestringt__releasebuffersetlength"></a>  CSimpleStringT::ReleaseBufferSetLength
 
-Releases control of the buffer allocated by [GetBuffer](#csimplestringt__GetBuffer).  
+Releases control of the buffer allocated by [GetBuffer](#csimplestringt__getbuffer).  
 
 ### Syntax  
 
@@ -962,7 +983,7 @@ void ReleaseBufferSetLength(int nNewLength);
  The length of the string being released  
 
 ### Remarks  
- This function is functionally similar to [ReleaseBuffer](#csimplestringt__ReleaseBuffer) except that a valid length for the string object must be passed.  
+ This function is functionally similar to [ReleaseBuffer](#csimplestringt__releasebuffer) except that a valid length for the string object must be passed.  
 
 ### Requirements  
  **Header:** atlsimpstr.h  
@@ -979,7 +1000,7 @@ void SetAt(int iChar, XCHAR ch);
 ```  
 #### Parameters  
  `iChar`  
- Zero-based index of the character in the `CSimpleStringT` object. The `iChar` parameter must be greater than or equal to 0 and less than the value returned by [GetLength](#csimplestringt__GetLength).  
+ Zero-based index of the character in the `CSimpleStringT` object. The `iChar` parameter must be greater than or equal to 0 and less than the value returned by [GetLength](#csimplestringt__getlength).  
 
  *ch*  
  The new character.  
@@ -1116,7 +1137,7 @@ void Truncate(int nNewLength);
  Call this method to truncate the contents of the string to the new length.  
 
 > [!NOTE]
->  This does not affect the allocated length of the buffer. To decrease or increase the current buffer, see [FreeExtra](#csimplestringt__FreeExtra) and [Preallocate](#csimplestringt__Preallocate).  
+>  This does not affect the allocated length of the buffer. To decrease or increase the current buffer, see [FreeExtra](#csimplestringt__freeextra) and [Preallocate](#csimplestringt__preallocate).  
   
 ## Example  
  The following example demonstrates the use of `CSimpleStringT::Truncate`.  
@@ -1146,7 +1167,7 @@ void UnlockBuffer() throw();
 ### Remarks  
  Call this method to reset the reference count of the string to 1.  
   
- The `CSimpleStringT` destructor automatically calls `UnlockBuffer` to ensure that the buffer is not locked when the destructor is called. For an example of this method, see [LockBuffer](#csimplestringt__LockBuffer).  
+ The `CSimpleStringT` destructor automatically calls `UnlockBuffer` to ensure that the buffer is not locked when the destructor is called. For an example of this method, see [LockBuffer](#csimplestringt__lockbuffer).  
   
 ### Requirements  
  **Header:** atlsimpstr.h  

docs/atl-mfc-shared/reference/csize-class.md

@@ -262,7 +262,7 @@ CSize operator-() const throw();
  [!code-cpp[NVC_ATLMFC_Utilities#103](../../atl-mfc-shared/codesnippet/cpp/csize-class_7.cpp)]  
 
 ## See Also  
- [MFC Sample MDI](../../top/visual-cpp-samples.md)   
+ [MFC Sample MDI](../../visual-cpp-samples.md)   
  [Hierarchy Chart](../../mfc/hierarchy-chart.md)   
  [CRect Class](../../atl-mfc-shared/reference/crect-class.md)   
  [CPoint Class](../../atl-mfc-shared/reference/cpoint-class.md)

docs/atl/active-template-library-atl-concepts.md

@@ -105,7 +105,7 @@ The Active Template Library (ATL) is a set of template-based C++ classes that le
  Provides code for manipulating paths and URLs in the form of [CPathT](../atl/reference/cpatht-class.md) and [CUrl](../atl/reference/curl-class.md). A thread pool, [CThreadPool](../atl/reference/cthreadpool-class.md), can be used in your own applications. This code can be found in atlpath.h and atlutil.h.  
 
 ## Related Sections  
- [ATL Samples](../top/visual-cpp-samples.md)  
+ [ATL Samples](../visual-cpp-samples.md)  
  Provides descriptions of and links to the ATL sample programs.  
 
  [Creating an ATL Project](../atl/reference/creating-an-atl-project.md)  

docs/atl/adding-connection-points-to-an-object.md

@@ -56,7 +56,7 @@ The [ATL Tutorial](../atl/active-template-library-atl-tutorial.md) demonstrates
 
      [!code-cpp[NVC_ATL_Windowing#82](../atl/codesnippet/cpp/adding-connection-points-to-an-object_2.idl)]  
 
-     See the .idl file in the [Circ](../top/visual-cpp-samples.md) ATL sample for an example.  
+     See the .idl file in the [Circ](../visual-cpp-samples.md) ATL sample for an example.  
 
 3.  Use Class View to add methods and properties to the event interface. Right-click the class in Class View, point to **Add** on the shortcut menu, and click **Add Connection Point**.