1 /*
2  * Copyright (C) 2009 Google Inc. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *
8  *     * Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *     * Redistributions in binary form must reproduce the above
11  * copyright notice, this list of conditions and the following disclaimer
12  * in the documentation and/or other materials provided with the
13  * distribution.
14  *     * Neither the name of Google Inc. nor the names of its
15  * contributors may be used to endorse or promote products derived from
16  * this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 
31 #ifndef THIRD_PARTY_BLINK_PUBLIC_PLATFORM_WEB_STRING_H_
32 #define THIRD_PARTY_BLINK_PUBLIC_PLATFORM_WEB_STRING_H_
33 
34 #include <string>
35 #include "base/memory/scoped_refptr.h"
36 #include "base/optional.h"
37 #include "base/strings/latin1_string_conversions.h"
38 #include "base/strings/nullable_string16.h"
39 #include "base/strings/string16.h"
40 #include "third_party/blink/public/platform/web_common.h"
41 
42 #if INSIDE_BLINK
43 #include "third_party/blink/renderer/platform/wtf/forward.h"  // nogncheck
44 #endif
45 
46 namespace WTF {
47 class StringImpl;
48 }
49 
50 namespace blink {
51 
52 // Use either one of static methods to convert ASCII, Latin1, UTF-8 or
53 // UTF-16 string into WebString:
54 //
55 // * WebString::FromASCII(const std::string& ascii)
56 // * WebString::FromLatin1(const std::string& latin1)
57 // * WebString::FromUTF8(const std::string& utf8)
58 // * WebString::FromUTF16(const base::string16& utf16)
59 // * WebString::FromUTF16(const base::NullableString16& utf16)
60 // * WebString::FromUTF16(const base::Optional<base::string16>& utf16)
61 //
62 // Similarly, use either of following methods to convert WebString to
63 // ASCII, Latin1, UTF-8 or UTF-16:
64 //
65 // * webstring.Ascii()
66 // * webstring.Latin1()
67 // * webstring.Utf8()
68 // * webstring.Utf16()
69 // * WebString::ToNullableString16(webstring)
70 // * WebString::ToOptionalString16(webstring)
71 //
72 // Note that if you need to convert the UTF8 string converted from WebString
73 // back to WebString with FromUTF8() you may want to specify Strict
74 // UTF8ConversionMode when you call Utf8(), as FromUTF8 rejects strings
75 // with invalid UTF8 characters.
76 //
77 // Some types like GURL and base::FilePath can directly take either utf-8 or
78 // utf-16 strings. Use following methods to convert WebString to/from GURL or
79 // FilePath rather than going through intermediate string types:
80 //
81 // * GURL WebStringToGURL(const WebString&)
82 // * base::FilePath WebStringToFilePath(const WebString&)
83 // * WebString FilePathToWebString(const base::FilePath&);
84 //
85 // It is inexpensive to copy a WebString object.
86 // WARNING: It is not safe to pass a WebString across threads!!!
87 //
88 class WebString {
89  public:
90   enum class UTF8ConversionMode {
91     // Ignores errors for invalid characters.
92     kLenient,
93     // Errors out on invalid characters, returns null string.
94     kStrict,
95     // Replace invalid characters with 0xFFFD.
96     // (This is the same conversion mode as base::UTF16ToUTF8)
97     kStrictReplacingErrorsWithFFFD,
98   };
99 
100   BLINK_PLATFORM_EXPORT ~WebString();
101   BLINK_PLATFORM_EXPORT WebString();
102   BLINK_PLATFORM_EXPORT WebString(const WebUChar* data, size_t len);
103 
104   BLINK_PLATFORM_EXPORT WebString(const WebString&);
105   BLINK_PLATFORM_EXPORT WebString(WebString&&);
106 
107   BLINK_PLATFORM_EXPORT WebString& operator=(const WebString&);
108   BLINK_PLATFORM_EXPORT WebString& operator=(WebString&&);
109 
110   BLINK_PLATFORM_EXPORT void Reset();
111 
112   BLINK_PLATFORM_EXPORT bool Equals(const WebString&) const;
113   BLINK_PLATFORM_EXPORT bool Equals(const char* characters, size_t len) const;
Equals(const char * characters)114   bool Equals(const char* characters) const {
115     return Equals(characters, characters ? strlen(characters) : 0);
116   }
117 
118   BLINK_PLATFORM_EXPORT size_t length() const;
119 
IsEmpty()120   bool IsEmpty() const { return !length(); }
IsNull()121   bool IsNull() const { return !impl_; }
122 
123   BLINK_PLATFORM_EXPORT std::string Utf8(
124       UTF8ConversionMode = UTF8ConversionMode::kLenient) const;
125 
126   BLINK_PLATFORM_EXPORT static WebString FromUTF8(const char* data,
127                                                   size_t length);
FromUTF8(const std::string & s)128   static WebString FromUTF8(const std::string& s) {
129     return FromUTF8(s.data(), s.length());
130   }
131 
Utf16()132   base::string16 Utf16() const {
133     return base::Latin1OrUTF16ToUTF16(length(), Data8(), Data16());
134   }
135 
136   BLINK_PLATFORM_EXPORT static WebString FromUTF16(const base::string16&);
137   BLINK_PLATFORM_EXPORT static WebString FromUTF16(
138       const base::NullableString16&);
139   BLINK_PLATFORM_EXPORT static WebString FromUTF16(
140       const base::Optional<base::string16>&);
141 
ToNullableString16(const WebString & s)142   static base::NullableString16 ToNullableString16(const WebString& s) {
143     return base::NullableString16(ToOptionalString16(s));
144   }
145 
ToOptionalString16(const WebString & s)146   static base::Optional<base::string16> ToOptionalString16(const WebString& s) {
147     return s.IsNull() ? base::nullopt : base::make_optional(s.Utf16());
148   }
149 
150   BLINK_PLATFORM_EXPORT std::string Latin1() const;
151 
152   BLINK_PLATFORM_EXPORT static WebString FromLatin1(const WebLChar* data,
153                                                     size_t length);
154 
FromLatin1(const std::string & s)155   static WebString FromLatin1(const std::string& s) {
156     return FromLatin1(reinterpret_cast<const WebLChar*>(s.data()), s.length());
157   }
158 
159   // This asserts if the string contains non-ascii characters.
160   // Use this rather than calling base::UTF16ToASCII() which always incurs
161   // (likely unnecessary) string16 conversion.
162   BLINK_PLATFORM_EXPORT std::string Ascii() const;
163 
164   // Use this rather than calling base::IsStringASCII().
165   BLINK_PLATFORM_EXPORT bool ContainsOnlyASCII() const;
166 
167   // Does same as FromLatin1 but asserts if the given string has non-ascii char.
168   BLINK_PLATFORM_EXPORT static WebString FromASCII(const std::string&);
169 
170   template <int N>
WebString(const char (& data)[N])171   WebString(const char (&data)[N]) : WebString(FromUTF8(data, N - 1)) {}
172 
173   template <int N>
174   WebString& operator=(const char (&data)[N]) {
175     *this = FromUTF8(data, N - 1);
176     return *this;
177   }
178 
179 #if INSIDE_BLINK
180   BLINK_PLATFORM_EXPORT WebString(const WTF::String&);
181   BLINK_PLATFORM_EXPORT WebString& operator=(const WTF::String&);
182   BLINK_PLATFORM_EXPORT operator WTF::String() const;
183 
184   BLINK_PLATFORM_EXPORT operator WTF::StringView() const;
185 
186   BLINK_PLATFORM_EXPORT WebString(const WTF::AtomicString&);
187   BLINK_PLATFORM_EXPORT WebString& operator=(const WTF::AtomicString&);
188   BLINK_PLATFORM_EXPORT operator WTF::AtomicString() const;
189 #endif
190 
191  private:
192   BLINK_PLATFORM_EXPORT bool Is8Bit() const;
193   BLINK_PLATFORM_EXPORT const WebLChar* Data8() const;
194   BLINK_PLATFORM_EXPORT const WebUChar* Data16() const;
195 
196   scoped_refptr<WTF::StringImpl> impl_;
197 };
198 
199 inline bool operator==(const WebString& a, const char* b) {
200   return a.Equals(b);
201 }
202 
203 inline bool operator!=(const WebString& a, const char* b) {
204   return !(a == b);
205 }
206 
207 inline bool operator==(const char* a, const WebString& b) {
208   return b == a;
209 }
210 
211 inline bool operator!=(const char* a, const WebString& b) {
212   return !(b == a);
213 }
214 
215 inline bool operator==(const WebString& a, const WebString& b) {
216   return a.Equals(b);
217 }
218 
219 inline bool operator!=(const WebString& a, const WebString& b) {
220   return !(a == b);
221 }
222 
223 }  // namespace blink
224 
225 #endif
226