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

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

 /*
  * Copyright (C) 1999 Lars Knoll (knoll@kde.org)
  * Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2013 Apple Inc. All rights
  * reserved.
  * Copyright (C) 2009 Google 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 33 matching lines @@
 
 namespace WTF {
 
 struct AlreadyHashed;
 template <typename>
 class RetainPtr;
 
 enum TextCaseSensitivity {
   TextCaseSensitive,
   TextCaseASCIIInsensitive,
+
+  // Unicode aware case insensitive matching. Non-ASCII characters might match
+  // to ASCII characters. This flag is rarely used to implement web platform
+  // features.
   TextCaseInsensitive
 };
 
 enum StripBehavior { StripExtraWhiteSpace, DoNotStripWhiteSpace };
 
 typedef bool (*CharacterMatchFunctionPtr)(UChar);
 typedef bool (*IsWhiteSpaceFunctionPtr)(UChar);
 typedef HashMap<unsigned, StringImpl*, AlreadyHashed> StaticStringsTable;
 
 // Define STRING_STATS to turn on run time statistics of string sizes and memory
@@ skipping 313 matching lines @@
   PassRefPtr<StringImpl> remove(unsigned start, unsigned lengthToRemove = 1);
 
   // Find characters.
   size_t find(LChar character, unsigned start = 0);
   size_t find(char character, unsigned start = 0);
   size_t find(UChar character, unsigned start = 0);
   size_t find(CharacterMatchFunctionPtr, unsigned index = 0);
 
   // Find substrings.
   size_t find(const StringView&, unsigned index = 0);
+  // 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&, unsigned index = 0);
   size_t findIgnoringASCIICase(const StringView&, unsigned index = 0);
 
   size_t reverseFind(UChar, unsigned index = UINT_MAX);
   size_t reverseFind(const StringView&, unsigned index = UINT_MAX);
 
   bool startsWith(UChar) const;
   bool startsWith(const StringView&) const;
   bool startsWithIgnoringCase(const StringView&) const;
   bool startsWithIgnoringASCIICase(const StringView&) const;
@@ skipping 139 matching lines @@
     if (a[i] != b[i])
       return false;
   }
   return true;
 }
 
 ALWAYS_INLINE bool equal(const UChar* a, const LChar* b, unsigned length) {
   return equal(b, a, length);
 }
 
+// Unicode aware case insensitive string matching. Non-ASCII characters might
+// match to ASCII characters. These functions are rarely used to implement web
+// platform features.
 WTF_EXPORT bool equalIgnoringCase(const LChar*, const LChar*, unsigned length);
 WTF_EXPORT bool equalIgnoringCase(const UChar*, const LChar*, unsigned length);
 inline bool equalIgnoringCase(const LChar* a, const UChar* b, unsigned length) {
   return equalIgnoringCase(b, a, length);
 }
-
 WTF_EXPORT bool equalIgnoringCase(const UChar*, const UChar*, unsigned length);
 
 WTF_EXPORT bool equalIgnoringNullity(StringImpl*, StringImpl*);
 
 template <typename CharacterTypeA, typename CharacterTypeB>
 inline bool equalIgnoringASCIICase(const CharacterTypeA* a,
                                    const CharacterTypeB* b,
                                    unsigned length) {
   for (unsigned i = 0; i < length; ++i) {
     if (toASCIILower(a[i]) != toASCIILower(b[i]))
@@ skipping 271 matching lines @@
 using WTF::TextCaseASCIIInsensitive;
 using WTF::TextCaseInsensitive;
 using WTF::TextCaseSensitive;
 using WTF::TextCaseSensitivity;
 using WTF::equal;
 using WTF::equalNonNull;
 using WTF::lengthOfNullTerminatedString;
 using WTF::reverseFind;
 
 #endif