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

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

 /*
  * (C) 1999 Lars Knoll (knoll@kde.org)
  * Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2012, 2013 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.
  *
@@ skipping 169 matching lines @@
 
   // Find substrings.
   size_t find(const StringView& value,
               unsigned start = 0,
               TextCaseSensitivity caseSensitivity = TextCaseSensitive) const {
     return m_impl
                ? DISPATCH_CASE_OP(caseSensitivity, m_impl->find, (value, start))
                : kNotFound;
   }
 
-  // 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_impl ? m_impl->findIgnoringCase(value, start) : kNotFound;
   }
 
   // ASCII case insensitive string matching.
   size_t findIgnoringASCIICase(const StringView& value,
                                unsigned start = 0) const {
     return m_impl ? m_impl->findIgnoringASCIICase(value, start) : kNotFound;
   }
 
@@ skipping 72 matching lines @@
 
   void ensure16Bit();
 
   void truncate(unsigned length);
   void remove(unsigned start, unsigned length = 1);
 
   String substring(unsigned pos, unsigned len = UINT_MAX) const;
   String left(unsigned len) const { return substring(0, len); }
   String right(unsigned len) const { return substring(length() - len, len); }
 
-  // Returns a lowercase/uppercase version of the string
+  // 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.
   String lower() const;
   String upper() const;
 
   String lower(const AtomicString& localeIdentifier) const;
   String upper(const AtomicString& localeIdentifier) const;
 
   String stripWhiteSpace() const;
   String stripWhiteSpace(IsWhiteSpaceFunctionPtr) const;
   String simplifyWhiteSpace(StripBehavior = StripExtraWhiteSpace) const;
   String simplifyWhiteSpace(IsWhiteSpaceFunctionPtr,
@@ skipping 353 matching lines @@
 using WTF::emptyString;
 using WTF::emptyString16Bit;
 using WTF::charactersAreAllASCII;
 using WTF::equal;
 using WTF::find;
 using WTF::isAllSpecialCharacters;
 using WTF::isSpaceOrNewline;
 
 #include "wtf/text/AtomicString.h"
 #endif  // WTFString_h