Bug 1499212 - document that Literal parameters must have a null terminator r=dbaron
authorKarl Tomlinson <karlt+@karlt.net>
Fri, 19 Oct 2018 01:26:21 +0000
changeset 490420 3f6b347621b3ca43e9c54f36b9721fa4c070eda1
parent 490419 9cc9c8d06722b89670910b8d61ee41f884c43e48
child 490421 1728cf8a0da4da103076a9e1ce02c9f5b4eb3d85
push id247
push userfmarier@mozilla.com
push dateSat, 27 Oct 2018 01:06:44 +0000
reviewersdbaron
bugs1499212
milestone64.0a1
Bug 1499212 - document that Literal parameters must have a null terminator r=dbaron A character array initialized with a list of character literals will not necessarily have a trailing null-terminator required for AssignLiteral or trimmed in EqualsLiteral. Depends on D8775 Differential Revision: https://phabricator.services.mozilla.com/D8951
xpcom/string/nsTStringRepr.h
xpcom/string/nsTSubstring.h
--- a/xpcom/string/nsTStringRepr.h
+++ b/xpcom/string/nsTStringRepr.h
@@ -253,19 +253,19 @@ public:
   // length of 'data'.
   bool NS_FASTCALL EqualsASCII(const char* aData, size_type aLen) 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* aData) const;
 
   // EqualsLiteral must ONLY be called with an actual literal string, or
-  // a char array *constant* declared without an explicit size.
-  // Do not attempt to use it with a non-constant char array variable.
-  // Use EqualsASCII for that.
+  // a char array *constant* declared without an explicit size and with an
+  // initializer that is a string literal or is otherwise null-terminated.
+  // Use EqualsASCII for other char array variables.
   // (Although this method may happen to produce expected results for other
   // char arrays that have bound one greater than the sequence of interest,
   // such use is discouraged for reasons of readability and maintainability.)
   // The template trick to acquire the array bound at compile time without
   // using a macro is due to Corey Kosak, with much thanks.
   template<int N>
   inline bool EqualsLiteral(const char (&aStr)[N]) const
   {
@@ -277,20 +277,20 @@ public:
   // 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* aData,
                                         size_type aLen) const;
   bool NS_FASTCALL LowerCaseEqualsASCII(const char* aData) const;
 
-  // LowerCaseEqualsLiteral must ONLY be called with an actual
-  // literal string, or a char array *constant* declared without an
-  // explicit size.  Do not attempt to use it with a non-constant char array
-  // variable. Use LowerCaseEqualsASCII for that.
+  // LowerCaseEqualsLiteral must ONLY be called with an actual literal string,
+  // or a char array *constant* declared without an explicit size and with an
+  // initializer that is a string literal or is otherwise null-terminated.
+  // Use LowerCaseEqualsASCII for other char array variables.
   // (Although this method may happen to produce expected results for other
   // char arrays that have bound one greater than the sequence of interest,
   // such use is discouraged for reasons of readability and maintainability.)
   template<int N>
   bool LowerCaseEqualsLiteral(const char (&aStr)[N]) const
   {
     return LowerCaseEqualsASCII(aStr, N - 1);
   }
--- a/xpcom/string/nsTSubstring.h
+++ b/xpcom/string/nsTSubstring.h
@@ -469,36 +469,36 @@ public:
                                             const fallible_t& aFallible)
   {
     return AssignASCII(aData,
                        mozilla::AssertedCast<size_type, size_t>(strlen(aData)),
                        aFallible);
   }
 
   // AssignLiteral must ONLY be called with an actual literal string, or
-  // a character array *constant* declared without an explicit size.
-  // Do not attempt to use it with a character array variable that is not
-  // constant or does not have static storage duration. Use Assign or
-  // AssignASCII for those.
+  // a character array *constant* of static storage duration declared
+  // without an explicit size and with an initializer that is a string
+  // literal or is otherwise null-terminated.
+  // Use Assign or AssignASCII for other character array variables.
   //
   // This method does not need a fallible version, because it uses the
   // POD buffer of the literal as the string's buffer without allocating.
   // The literal does not need to be ASCII. If this a 16-bit string, this
   // method takes a u"" literal. (The overload on 16-bit strings that takes
   // a "" literal takes only ASCII.)
   template<int N>
   void AssignLiteral(const char_type (&aStr)[N])
   {
     AssignLiteral(aStr, N - 1);
   }
 
   // AssignLiteral must ONLY be called with an actual literal string, or
-  // a char array *constant* declared without an explicit size.
-  // Do not attempt to use it with a non-constant char array variable.
-  // Use AssignASCII for that.
+  // a char array *constant* declared without an explicit size and with an
+  // initializer that is a string literal or is otherwise null-terminated.
+  // Use AssignASCII for other char array variables.
   //
   // This method takes an 8-bit (ASCII-only!) string that is expanded
   // into a 16-bit string at run time causing a run-time allocation.
   // To avoid the run-time allocation (at the cost of the literal
   // taking twice the size in the binary), use the above overload that
   // takes a u"" string instead. Using the overload that takes a u""
   // literal is generally preferred when working with 16-bit strings.
   //