Bug 326317 - Fix issues with comments in nsTSubstring.h. r=dbaron
authorCykesiopka <cykesiopka@hotmail.com>
Mon, 25 Feb 2013 09:07:15 -0500
changeset 133288 f7b1ac19bface7e9a141ad9690e10ffe5b6776da
parent 133285 ca0d05c997588eea4a74fcc574ffffb2d23f6a51
child 133289 0470103ac4a807a1f09506ff0e258bcf06656147
push id2452
push userlsblakk@mozilla.com
push dateMon, 13 May 2013 16:59:38 +0000
treeherdermozilla-beta@d4b152d29d8d [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersdbaron
bugs326317
milestone22.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 326317 - Fix issues with comments in nsTSubstring.h. r=dbaron
xpcom/string/public/nsTSubstring.h
--- a/xpcom/string/public/nsTSubstring.h
+++ b/xpcom/string/public/nsTSubstring.h
@@ -270,19 +270,20 @@ class nsTSubstring_CharT
       bool NS_FASTCALL EqualsASCII( const char* data, size_type len ) const;
         /**
          * An efficient comparison with ASCII that can be used even
          * for wide strings. Call this version when 'data' is
          * null-terminated.
          */
       bool NS_FASTCALL EqualsASCII( const char* data ) const;
 
-    // EqualsLiteral must ONLY be applied to an actual literal string.
-    // Do not attempt to use it with a regular char* pointer, or with a char
-    // array variable.
+    // EqualsLiteral must ONLY be applied to an actual literal string, or
+    // a char array *constant* declared without an explicit size.
+    // Do not attempt to use it with a regular char* pointer, or with a
+    // non-constant char array variable. Use EqualsASCII for them.
     // The template trick to acquire the array length at compile time without
     // using a macro is due to Corey Kosak, with much thanks.
 #ifdef NS_DISABLE_LITERAL_TEMPLATE
       inline bool EqualsLiteral( const char* str ) const
         {
           return EqualsASCII(str);
         }
 #else
@@ -304,18 +305,19 @@ class nsTSubstring_CharT
     // ASCII/Literal string. The ASCII string is *not* lowercased for
     // you. If you compare to an ASCII or literal string that contains an
     // uppercase character, it is guaranteed to return false. We will
     // throw assertions too.
       bool NS_FASTCALL LowerCaseEqualsASCII( const char* data, size_type len ) const;
       bool NS_FASTCALL LowerCaseEqualsASCII( const char* data ) const;
 
     // LowerCaseEqualsLiteral must ONLY be applied to an actual
-    // literal string.  Do not attempt to use it with a regular char*
-    // pointer, or with a char array variable. Use
+    // literal string, or a char array *constant* declared without an 
+    // explicit size.  Do not attempt to use it with a regular char*
+    // pointer, or with a non-constant char array variable. Use
     // LowerCaseEqualsASCII for them.
 #ifdef NS_DISABLE_LITERAL_TEMPLATE
       inline bool LowerCaseEqualsLiteral( const char* str ) const
         {
           return LowerCaseEqualsASCII(str);
         }
 #else
       template<int N>
@@ -355,19 +357,20 @@ class nsTSubstring_CharT
         {
           AssignASCII(data, strlen(data));
         }
       bool NS_FASTCALL AssignASCII( const char* data, const fallible_t& ) NS_WARN_UNUSED_RESULT
         {
           return AssignASCII(data, strlen(data), fallible_t());
         }
 
-    // AssignLiteral must ONLY be applied to an actual literal string.
-    // Do not attempt to use it with a regular char* pointer, or with a char
-    // array variable. Use AssignASCII for those.
+    // AssignLiteral must ONLY be applied to an actual literal string, or
+    // a char array *constant* declared without an explicit size.
+    // Do not attempt to use it with a regular char* pointer, or with a 
+    // non-constant char array variable. Use AssignASCII for those.
     // There are not fallible version of these methods because they only really
     // apply to small allocations that we wouldn't want to check anyway.
 #ifdef NS_DISABLE_LITERAL_TEMPLATE
       void AssignLiteral( const char* str )
                   { AssignASCII(str); }
 #else
       template<int N>
       void AssignLiteral( const char (&str)[N] )
@@ -477,18 +480,21 @@ class nsTSubstring_CharT
       void Cut( index_type cutStart, size_type cutLength )                                       { Replace(cutStart, cutLength, char_traits::sEmptyBuffer, 0); }
 
 
         /**
          * buffer sizing
          */
 
         /**
-         * Attempts to set the capacity to the given size, without affecting
-         * the length of the string. Also ensures that the buffer is mutable.
+         * Attempts to set the capacity to the given size in number of 
+         * characters, without affecting the length of the string.
+         * 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.
          */
       void NS_FASTCALL SetCapacity( size_type newCapacity );
       bool NS_FASTCALL SetCapacity( size_type newCapacity, const fallible_t& ) NS_WARN_UNUSED_RESULT;
 
       void NS_FASTCALL SetLength( size_type newLength );
       bool NS_FASTCALL SetLength( size_type newLength, const fallible_t& ) NS_WARN_UNUSED_RESULT;
 
       void Truncate( size_type newLength = 0 )