Merge pull request #6161 from oldnewthing/oldnewthing-clistbox-initstorage

Clarify CListBox::InitStorage parameters

Author: JamesJBarnett

docs/mfc/codesnippet/CPP/clistbox-class_23.cpp

@@ -1,6 +1,6 @@
-// Initialize the storage of the list box to be 256 strings with
-// about 10 characters per string, performance improvement.
-int n = m_myListBox.InitStorage(256, 16 * sizeof(TCHAR));
+// Reserve space in the list box for 256 additional strings with
+// about 15 characters per string.
+int n = m_myListBox.InitStorage(256, 256 * (15 + 1) * sizeof(TCHAR));
 ASSERT(n != LB_ERRSPACE);
 
 // Add 256 items to the list box.

docs/mfc/reference/clistbox-class.md

@@ -873,20 +873,22 @@ int InitStorage(
 ### Parameters
 
 *`nItems`*<br/>
-Specifies the number of items to add.
+Specifies the number of items to for which to reserve space.
 
 *`nBytes`*<br/>
-Specifies the amount of memory, in bytes, to allocate for item strings.
+Specifies the amount of additional memory, in bytes, to allocate for item strings.
 
 ### Return Value
 
 If successful, the maximum number of items that the list box can store before a memory reallocation is needed, otherwise `LB_ERRSPACE`, meaning not enough memory is available.
 
 ### Remarks
 
-Call this function before adding a large number of items to a `CListBox`.
+You can call this function before adding a large number of items to a `CListBox`.
 
-This function helps speed up the initialization of list boxes that have a large number of items (more than 100). It preallocates the specified amount of memory so that subsequent [`AddString`](#addstring), [`InsertString`](#insertstring), and [`Dir`](#dir) functions take the shortest possible time. You can use estimates for the parameters. If you overestimate, some extra memory is allocated; if you underestimate, the normal allocation is used for items that exceed the preallocated amount.
+This function helps speed up the initialization of list boxes that have a large number of items (more than 100). It preallocates the specified amount of memory so that subsequent [`AddString`](#addstring), [`InsertString`](#insertstring), and [`Dir`](#dir) functions are more efficient. You can use estimates for the parameters. If you overestimate, the extra memory remains allocated; if you underestimate, the list box will allocate additional memory as necessary.
+
+The memory required to store a string includes the null terminator. Therefore, if you plan to add 100 strings, each with a length of 10 characters, you would pass a *wParam* of 100 and an *lParam* of 100 &times; (10 + 1) &times; sizeof(TCHAR).
 
 Windows 95/98 only: The *`nItems`* parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size of the items in a list box is limited only by available memory.