Bug 1384834 (part 4) - Improve comments for Adopt() and getter_Copies(). r=erahm.
authorNicholas Nethercote <nnethercote@mozilla.com>
Tue, 01 Aug 2017 06:06:36 +1000
changeset 420870 d6e8c5e46a872611ddbe8703980212d5daf2984f
parent 420869 f3b45d52b78e2757f26559033bdb476e22c35159
child 420871 566c5e68903a11fb7ddfb297368f98f7ce4dc102
push id7566
push usermtabara@mozilla.com
push dateWed, 02 Aug 2017 08:25:16 +0000
treeherdermozilla-beta@86913f512c3c [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerserahm
bugs1384834
milestone56.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 1384834 (part 4) - Improve comments for Adopt() and getter_Copies(). r=erahm.
xpcom/string/nsTString.h
xpcom/string/nsTSubstring.h
--- a/xpcom/string/nsTString.h
+++ b/xpcom/string/nsTString.h
@@ -770,24 +770,40 @@ public:
   {
     Assign(aTuple);
     return *this;
   }
 };
 
 
 /**
- * getter_Copies support for use with raw string out params:
+ * getter_Copies support for adopting raw string out params that are
+ * heap-allocated, e.g.:
  *
- *    NS_IMETHOD GetBlah(char**);
+ *    char* gStr;
+ *    void GetBlah(char** aStr)
+ *    {
+ *      *aStr = strdup(gStr);
+ *    }
  *
- *    void some_function()
+ *    // This works, but is clumsy.
+ *    void Inelegant()
  *    {
- *      nsXPIDLCString blah;
- *      GetBlah(getter_Copies(blah));
+ *      char* buf;
+ *      GetBlah(&buf);
+ *      nsCString str;
+ *      str.Adopt(buf);
+ *      // ...
+ *    }
+ *
+ *    // This is nicer.
+ *    void Elegant()
+ *    {
+ *      nsCString str;
+ *      GetBlah(getter_Copies(str));
  *      // ...
  *    }
  */
 class MOZ_STACK_CLASS nsTGetterCopies_CharT
 {
 public:
   typedef CharT char_type;
 
@@ -807,14 +823,15 @@ public:
     return &mData;
   }
 
 private:
   nsTSubstring_CharT& mString;
   char_type* mData;
 };
 
+// See the comment above nsTGetterCopies_CharT for how to use this.
 inline nsTGetterCopies_CharT
 getter_Copies(nsTSubstring_CharT& aString)
 {
   return nsTGetterCopies_CharT(aString);
 }
 
--- a/xpcom/string/nsTSubstring.h
+++ b/xpcom/string/nsTSubstring.h
@@ -521,16 +521,19 @@ public:
     return *this;
   }
   self_type& operator=(const substring_tuple_type& aTuple)
   {
     Assign(aTuple);
     return *this;
   }
 
+  // Adopt a heap-allocated char sequence for this string; is Voided if aData
+  // is null. Useful for e.g. converting an strdup'd C string into an
+  // nsCString. See also getter_Copies(), which is a useful wrapper.
   void NS_FASTCALL Adopt(char_type* aData, size_type aLength = size_type(-1));
 
 
   /**
    * buffer manipulation
    */
 
   void NS_FASTCALL Replace(index_type aCutStart, size_type aCutLength,