Initial Commit.

skills/mql5/references/docs/09-strings/0639-strings-stringreserve.md

@@ -0,0 +1,64 @@
+# StringReserve
+
+Reserves the buffer of a specified size for a string in memory.
+
+```
+bool  StringReserve(
+   string&    string_var,       // string
+   uint       new_capacity      // buffer size for storing a string
+   );
+
+```
+
+Parameters
+
+string_var
+
+[in][out]  String the buffer size should change the size for.
+
+new_capacity
+
+[in]  Buffer size required for a string. If the new_capacity size is less than the string length, the size of the current buffer does not change.
+
+Return Value
+
+In case of successful execution, returns true, otherwise - false. To receive an [error](/en/docs/constants/errorswarnings/errorcodes) code, the [GetLastError()](/en/docs/check/getlasterror) function should be called.
+
+Note
+
+Generally, the string size is not equal to the size of the buffer meant for storing the string. When creating a string, the appropriate buffer is usually allocated with a margin. The StringReserve() function allows managing the buffer size and specify the optimal size for future operations.
+
+Unlike [StringInit()](/en/docs/strings/stringinit), the StringReserve() function does not change the string contents and does not fill it with characters.
+
+Example:
+
+```
+void OnStart()
+  {
+   string s;
+//--- check the operation speed without using StringReserve
+   ulong t0=GetMicrosecondCount();
+   for(int i=0; i< 1024; i++)
+      s+=" "+(string)i;
+   ulong msc_no_reserve=GetMicrosecondCount()-t0;
+   s=NULL;
+//--- now, let's do the same using StringReserve
+   StringReserve(s,1024 * 3);
+   t0=GetMicrosecondCount();
+   for(int i=0; i< 1024; i++)
+      s+=" "+(string)i;
+   ulong msc_reserve=GetMicrosecondCount()-t0;
+//--- check the time
+   Print("Test with StringReserve passed for "+(string)msc_reserve+" msc");   
+   Print("Test without StringReserve passed for "+(string)msc_no_reserve+" msc");         
+/* Result
+     Test with StringReserve passed for 50 msc
+     Test without StringReserve passed for 121 msc
+*/
+  }
+
+```
+
+See also
+
+[StringBufferLen](/en/docs/strings/stringbufferlen), [StringSetLength](/en/docs/strings/stringsetlength), [StringInit](/en/docs/strings/stringinit), [StringSetCharacter](/en/docs/strings/stringsetcharacter)