Bug 1487614 - Make the docs of SetCapacity() even more explicit. r=froydnj
authorHenri Sivonen <hsivonen@hsivonen.fi>
Sat, 01 Sep 2018 07:50:11 +0000
changeset 492149 13777f26498ef48a9418838cde0ebc9128705708
parent 492148 bf6f5ec86920a3f58d16ca6ea2c406b09197e976
child 492150 5e01b236471ee1b3b8210d1fbc7f90e9bb11c767
push id1815
push userffxbld-merge
push dateMon, 15 Oct 2018 10:40:45 +0000
treeherdermozilla-release@18d4c09e9378 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersfroydnj
bugs1487614
milestone63.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1487614 - Make the docs of SetCapacity() even more explicit. r=froydnj MozReview-Commit-ID: KinrUtBG7Jd Differential Revision: https://phabricator.services.mozilla.com/D4744
xpcom/string/nsTSubstring.h
--- a/xpcom/string/nsTSubstring.h
+++ b/xpcom/string/nsTSubstring.h
@@ -857,33 +857,56 @@ public:
   nsTSubstringSplitter<T> Split(const char_type aChar) const;
 
   /**
    * buffer sizing
    */
 
   /**
    * Attempts to set the capacity to the given size in number of
-   * code units without affecting the length of the string, in
-   * order to avoid reallocation during subsequent calls to Append()
-   * or subsequent converting appends where the conversion is between
-   * UTF-16 and Latin1 (in either direction).
+   * code units without affecting the length of the string in
+   * order to avoid reallocation during a subsequent sequence of
+   * appends.
+   *
+   * This method is appropriate to use before a sequence of multiple
+   * operations from the following list (without operations that are
+   * not on the list between the SetCapacity() call and operations
+   * from the list):
    *
-   * Calling SetCapacity() is a pessimization ahead of a converting
-   * append where the conversion is between UTF-16 and UTF-8 (in
-   * either direction), so please don't call SetCapacity() ahead
-   * of that kind of converting append.
+   * Append()
+   * AppendASCII()
+   * AppendLiteral() (except if the string is empty: bug 1487606)
+   * AppendPrintf()
+   * AppendInt()
+   * AppendFloat()
+   * LossyAppendUTF16toASCII()
+   * AppendASCIItoUTF16()
+   *
+   * DO NOT call SetCapacity() if the subsequent operations on the
+   * string do not meet the criteria above. Operations that undo
+   * the benefits of SetCapacity() include but are not limited to:
+   *
+   * SetLength()
+   * Truncate()
+   * Assign()
+   * AssignLiteral()
+   * Adopt()
+   * CopyASCIItoUTF16()
+   * LossyCopyUTF16toASCII()
+   * AppendUTF16toUTF8()
+   * AppendUTF8toUTF16()
+   * CopyUTF16toUTF8()
+   * CopyUTF8toUTF16()
    *
    * If your string is an nsAuto[C]String and you are calling
    * SetCapacity() with a constant N, please instead declare the
    * string as nsAuto[C]StringN<N+1> without calling SetCapacity().
    *
    * There is no need to include room for the null terminator: it is
    * the job of the string class.
-   * Also ensures that the buffer is mutable.
    *
    * Note: Calling SetCapacity() does not give you permission to
    * use the pointer obtained from BeginWriting() to write
    * past the current length (as returned by Length()) of the
    * string. Please use either BulkWrite() or SetLength()
    * instead.
    */
   void NS_FASTCALL SetCapacity(size_type aNewCapacity);