WTF: Add comments and tests for Unicode aware case-insensitive string operations.

third_party/WebKit/Source/wtf/text/AtomicString.h

 /*
  * Copyright (C) 2004, 2005, 2006, 2008 Apple Inc. All rights reserved.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
  * License as published by the Free Software Foundation; either
  * version 2 of the License, or (at your option) any later version.
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ skipping 86 matching lines @@
     return m_string.find(matchFunction, start);
   }
 
   // Find substrings.
   size_t find(const StringView& value,
               unsigned start = 0,
               TextCaseSensitivity caseSensitivity = TextCaseSensitive) const {
     return m_string.find(value, start, caseSensitivity);
   }
 
-  // Unicode aware case insensitive string matching.
+  // Unicode aware case insensitive string matching. Non-ASCII characters might
+  // match to ASCII characters. This function is rarely used to implement web
+  // platform features.
   size_t findIgnoringCase(const StringView& value, unsigned start = 0) const {
     return m_string.findIgnoringCase(value, start);
   }
 
   // ASCII case insensitive string matching.
   size_t findIgnoringASCIICase(const StringView& value,
                                unsigned start = 0) const {
     return m_string.findIgnoringASCIICase(value, start);
   }
 
@@ skipping 19 matching lines @@
   bool startsWith(UChar character) const {
     return m_string.startsWith(character);
   }
 
   bool endsWith(const StringView& suffix,
                 TextCaseSensitivity caseSensitivity = TextCaseSensitive) const {
     return m_string.endsWith(suffix, caseSensitivity);
   }
   bool endsWith(UChar character) const { return m_string.endsWith(character); }
 
+  // Returns a lowercase/uppercase version of the string. These functions might
+  // convert non-ASCII characters to ASCII characters. For example, lower() for
+  // U+212A is 'k', upper() for U+017F is 'S'.
+  // These functions are rarely used to implement web platform features.
   AtomicString lower() const;
+  AtomicString upper() const { return AtomicString(impl()->upper()); }
+
+  // Returns a lowercase version of the string. This function converts only
+  // upper-case ASCII characters.
   AtomicString lowerASCII() const;
-  AtomicString upper() const { return AtomicString(impl()->upper()); }
 
   int toInt(bool* ok = 0) const { return m_string.toInt(ok); }
   double toDouble(bool* ok = 0) const { return m_string.toDouble(ok); }
   float toFloat(bool* ok = 0) const { return m_string.toFloat(ok); }
 
   static AtomicString number(int);
   static AtomicString number(unsigned);
   static AtomicString number(long);
   static AtomicString number(unsigned long);
   static AtomicString number(long long);
@@ skipping 137 matching lines @@
 using WTF::AtomicString;
 using WTF::nullAtom;
 using WTF::emptyAtom;
 using WTF::starAtom;
 using WTF::xmlAtom;
 using WTF::xmlnsAtom;
 using WTF::xlinkAtom;
 
 #include "wtf/text/StringConcatenate.h"
 #endif  // AtomicString_h