WebString: makes string16 conversions explicit (part 1: blink, content)

third_party/WebKit/public/platform/WebString.h

 /*
  * Copyright (C) 2009 Google Inc. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
  * met:
  *
  *     * Redistributions of source code must retain the above copyright
  * notice, this list of conditions and the following disclaimer.
  *     * Redistributions in binary form must reproduce the above
@@ skipping 15 matching lines @@
  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
 #ifndef WebString_h
 #define WebString_h
 
 #include "WebCommon.h"
 #include "WebPrivatePtr.h"
+#include "base/strings/latin1_string_conversions.h"
+#include "base/strings/nullable_string16.h"
+#include "base/strings/string16.h"
 #include <string>
 
 #if INSIDE_BLINK
 #include "wtf/Forward.h"
-#else
-#include <base/strings/latin1_string_conversions.h>
-#include <base/strings/nullable_string16.h>
-#include <base/strings/string16.h>
 #endif
 
 namespace WTF {
 class StringImpl;
 }
 
 namespace blink {
 
-// A UTF-16 string container.  It is inexpensive to copy a WebString
-// object.
+// Use either one of static methods to convert ASCII, Latin1, UTF-8 or
+// UTF-16 string into WebString:
 //
+// * WebString::fromASCII(const std::string& ascii)
+// * WebString::fromLatin1(const std::string& latin1)
+// * WebString::fromUTF8(const std::string& utf8)
+// * WebString::fromUTF16(const base::string16& utf16)
+// * WebString::fromUTF16(const base::NullableString16& utf16)
+//
+// Similarly, use either of following methods to convert WebString to
+// ASCII, Latin1, UTF-8 or UTF-16:
+//
+// * webstring.ascii()
+// * webstring.latin1()
+// * webstring.utf8()
+// * webstring.utf16()
+// * WebString::toNullableString16(webstring)
+//
+// Some types like GURL and base::FilePath can directly take either utf-8 or
+// utf-16 strings. Use following methods to convert WebString to/from GURL or
+// FilePath rather than going through intermediate string types:
+//
+// * GURL WebStringToGURL(const WebString&)
+// * base::FilePath WebStringToFilePath(const WebString&)
+// * WebString FilePathToWebString(const base::FilePath&)
+//
+// Also see helper templates defined in StringVectorCopier.h for
+// string vector conversions (like std::vector<base::string16> to
+// WebVector<WebString).
+//
+// It is inexpensive to copy a WebString object.
 // WARNING: It is not safe to pass a WebString across threads!!!
 //
 class WebString {
  public:
   ~WebString() { reset(); }
 
   WebString() {}
 
   WebString(const WebUChar* data, size_t len) { assign(data, len); }
 
@@ skipping 19 matching lines @@
   BLINK_COMMON_EXPORT std::string utf8() const;
 
   BLINK_COMMON_EXPORT static WebString fromUTF8(const char* data,
                                                 size_t length);
   BLINK_COMMON_EXPORT static WebString fromUTF8(const char* data);
 
   static WebString fromUTF8(const std::string& s) {
     return fromUTF8(s.data(), s.length());
   }
 
+  base::string16 utf16() const {
+    return base::Latin1OrUTF16ToUTF16(length(), data8(), data16());
+  }
+
+  BLINK_COMMON_EXPORT static WebString fromUTF16(const base::string16&);
+
+  BLINK_COMMON_EXPORT static WebString fromUTF16(const base::NullableString16&);
+
+  static base::NullableString16 toNullableString16(const WebString& s) {
+    return base::NullableString16(s.utf16(), s.isNull());
+  }
+
   BLINK_COMMON_EXPORT std::string latin1() const;
 
   BLINK_COMMON_EXPORT static WebString fromLatin1(const WebLChar* data,
                                                   size_t length);
 
   static WebString fromLatin1(const std::string& s) {
     return fromLatin1(reinterpret_cast<const WebLChar*>(s.data()), s.length());
   }
 
   // This asserts if the string contains non-ascii characters.
@@ skipping 22 matching lines @@
   BLINK_COMMON_EXPORT WebString(const WTF::String&);
   BLINK_COMMON_EXPORT WebString& operator=(const WTF::String&);
   BLINK_COMMON_EXPORT operator WTF::String() const;
 
   BLINK_COMMON_EXPORT operator WTF::StringView() const;
 
   BLINK_COMMON_EXPORT WebString(const WTF::AtomicString&);
   BLINK_COMMON_EXPORT WebString& operator=(const WTF::AtomicString&);
   BLINK_COMMON_EXPORT operator WTF::AtomicString() const;
 #else
+  // WARNING: implicit conversions to/from string16 are being deprecated,
+  // use fromUTF16() or utf16() instead in new changes.
   WebString(const base::string16& s) { assign(s.data(), s.length()); }
 
   WebString& operator=(const base::string16& s) {
     assign(s.data(), s.length());
     return *this;
   }
 
   operator base::string16() const {
     return base::Latin1OrUTF16ToUTF16(length(), data8(), data16());
   }
@@ skipping 49 matching lines @@
   return a.equals(b);
 }
 
 inline bool operator!=(const WebString& a, const WebString& b) {
   return !(a == b);
 }
 
 }  // namespace blink
 
 #endif