Bug 1484668 - Document that writing past mLength code units via BeginWriting() is not OK. r=froydnj
authorHenri Sivonen <hsivonen@hsivonen.fi>
Fri, 24 Aug 2018 12:50:06 +0000
changeset 491425 8fd8a747cd87423a2b6938c243393157e2b0e6e4
parent 491424 a3273afbe89161e13c92a2915f0e824bcc375794
child 491426 9216e8942ed6d31b68411623420e45f3ca964adf
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
bugs1484668
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 1484668 - Document that writing past mLength code units via BeginWriting() is not OK. r=froydnj MozReview-Commit-ID: FdZN8PGLO9M Differential Revision: https://phabricator.services.mozilla.com/D3860
xpcom/string/nsTSubstring.h
--- a/xpcom/string/nsTSubstring.h
+++ b/xpcom/string/nsTSubstring.h
@@ -335,18 +335,34 @@ public:
   ~nsTSubstring()
   {
     Finalize();
   }
 
   /**
    * writing iterators
    *
+   * BeginWriting() makes the string mutable (if it isn't
+   * already) and returns (or writes into an outparam) a
+   * pointer that provides write access to the string's buffer.
+   *
    * Note: Consider if BulkWrite() suits your use case better
    * than BeginWriting() combined with SetLength().
+   *
+   * Note: Strings autoconvert into writable mozilla::Span,
+   * which may suit your use case better than calling
+   * BeginWriting() directly.
+   *
+   * When writing via the pointer obtained from BeginWriting(),
+   * you are allowed to write at most the number of code units
+   * indicated by Length() or, alternatively, write up to, but
+   * not including, the position indicated by EndWriting().
+   *
+   * In particular, calling SetCapacity() does not affect what
+   * the above paragraph says.
    */
 
   char_iterator BeginWriting()
   {
     if (!EnsureMutable()) {
       AllocFailed(base_string_type::mLength);
     }
 
@@ -815,20 +831,39 @@ public:
   nsTSubstringSplitter<T> Split(const char_type aChar) const;
 
   /**
    * buffer sizing
    */
 
   /**
    * Attempts to set the capacity to the given size in number of
-   * characters, without affecting the length of the string.
+   * 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).
+   *
+   * 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.
+   *
+   * 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);
   MOZ_MUST_USE bool NS_FASTCALL SetCapacity(size_type aNewCapacity,
                                             const fallible_t&);
 
   void NS_FASTCALL SetLength(size_type aNewLength);
   MOZ_MUST_USE bool NS_FASTCALL SetLength(size_type aNewLength,
                                           const fallible_t&);