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 482060 8fd8a747cd87423a2b6938c243393157e2b0e6e4
parent 482059 a3273afbe89161e13c92a2915f0e824bcc375794
child 482061 9216e8942ed6d31b68411623420e45f3ca964adf
push id232
push userfmarier@mozilla.com
push dateWed, 05 Sep 2018 20:45:54 +0000
reviewersfroydnj
bugs1484668
milestone63.0a1
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&);