1 // Copyright 2005, Google Inc.
2 // All rights reserved.
4 // Redistribution and use in source and binary forms, with or without
5 // modification, are permitted provided that the following conditions are
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
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.
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.
30 // Authors: wan@google.com (Zhanyong Wan), eefacm@gmail.com (Sean Mcafee)
32 // The Google C++ Testing Framework (Google Test)
34 // This header file declares the String class and functions used internally by
35 // Google Test. They are subject to change without notice. They should not used
36 // by code external to Google Test.
38 // This header file is #included by <gtest/internal/gtest-internal.h>.
39 // It should not be #included by other files.
41 #ifndef GTEST_INCLUDE_GTEST_INTERNAL_GTEST_STRING_H_
42 #define GTEST_INCLUDE_GTEST_INTERNAL_GTEST_STRING_H_
45 #include <gtest/internal/gtest-port.h>
47 #if GTEST_HAS_GLOBAL_STRING || GTEST_HAS_STD_STRING
49 #endif // GTEST_HAS_GLOBAL_STRING || GTEST_HAS_STD_STRING
54 // String - a UTF-8 string class.
56 // We cannot use std::string as Microsoft's STL implementation in
57 // Visual C++ 7.1 has problems when exception is disabled. There is a
58 // hack to work around this, but we've seen cases where the hack fails
61 // Also, String is different from std::string in that it can represent
62 // both NULL and the empty string, while std::string cannot represent
65 // NULL and the empty string are considered different. NULL is less
66 // than anything (including the empty string) except itself.
68 // This class only provides minimum functionality necessary for
69 // implementing Google Test. We do not intend to implement a full-fledged
72 // Since the purpose of this class is to provide a substitute for
73 // std::string on platforms where it cannot be used, we define a copy
74 // constructor and assignment operators such that we don't need
75 // conditional compilation in a lot of places.
77 // In order to make the representation efficient, the d'tor of String
78 // is not virtual. Therefore DO NOT INHERIT FROM String.
81 // Static utility methods
83 // Returns the input enclosed in double quotes if it's not NULL;
84 // otherwise returns "(null)". For example, "\"Hello\"" is returned
87 // This is useful for printing a C string in the syntax of a literal.
89 // Known issue: escape sequences are not handled yet.
90 static String ShowCStringQuoted(const char* c_str);
92 // Clones a 0-terminated C string, allocating memory using new. The
93 // caller is responsible for deleting the return value using
94 // delete[]. Returns the cloned string, or NULL if the input is
97 // This is different from strdup() in string.h, which allocates
98 // memory using malloc().
99 static const char* CloneCString(const char* c_str);
101 #if GTEST_OS_WINDOWS_MOBILE
102 // Windows CE does not have the 'ANSI' versions of Win32 APIs. To be
103 // able to pass strings to Win32 APIs on CE we need to convert them
104 // to 'Unicode', UTF-16.
106 // Creates a UTF-16 wide string from the given ANSI string, allocating
107 // memory using new. The caller is responsible for deleting the return
108 // value using delete[]. Returns the wide string, or NULL if the
111 // The wide string is created using the ANSI codepage (CP_ACP) to
112 // match the behaviour of the ANSI versions of Win32 calls and the
114 static LPCWSTR AnsiToUtf16(const char* c_str);
116 // Creates an ANSI string from the given wide string, allocating
117 // memory using new. The caller is responsible for deleting the return
118 // value using delete[]. Returns the ANSI string, or NULL if the
121 // The returned string is created using the ANSI codepage (CP_ACP) to
122 // match the behaviour of the ANSI versions of Win32 calls and the
124 static const char* Utf16ToAnsi(LPCWSTR utf16_str);
127 // Compares two C strings. Returns true iff they have the same content.
129 // Unlike strcmp(), this function can handle NULL argument(s). A
130 // NULL C string is considered different to any non-NULL C string,
131 // including the empty string.
132 static bool CStringEquals(const char* lhs, const char* rhs);
134 // Converts a wide C string to a String using the UTF-8 encoding.
135 // NULL will be converted to "(null)". If an error occurred during
136 // the conversion, "(failed to convert from wide string)" is
138 static String ShowWideCString(const wchar_t* wide_c_str);
140 // Similar to ShowWideCString(), except that this function encloses
141 // the converted string in double quotes.
142 static String ShowWideCStringQuoted(const wchar_t* wide_c_str);
144 // Compares two wide C strings. Returns true iff they have the same
147 // Unlike wcscmp(), this function can handle NULL argument(s). A
148 // NULL C string is considered different to any non-NULL C string,
149 // including the empty string.
150 static bool WideCStringEquals(const wchar_t* lhs, const wchar_t* rhs);
152 // Compares two C strings, ignoring case. Returns true iff they
153 // have the same content.
155 // Unlike strcasecmp(), this function can handle NULL argument(s).
156 // A NULL C string is considered different to any non-NULL C string,
157 // including the empty string.
158 static bool CaseInsensitiveCStringEquals(const char* lhs,
161 // Compares two wide C strings, ignoring case. Returns true iff they
162 // have the same content.
164 // Unlike wcscasecmp(), this function can handle NULL argument(s).
165 // A NULL C string is considered different to any non-NULL wide C string,
166 // including the empty string.
167 // NB: The implementations on different platforms slightly differ.
168 // On windows, this method uses _wcsicmp which compares according to LC_CTYPE
169 // environment variable. On GNU platform this method uses wcscasecmp
170 // which compares according to LC_CTYPE category of the current locale.
171 // On MacOS X, it uses towlower, which also uses LC_CTYPE category of the
173 static bool CaseInsensitiveWideCStringEquals(const wchar_t* lhs,
176 // Formats a list of arguments to a String, using the same format
177 // spec string as for printf.
179 // We do not use the StringPrintf class as it is not universally
182 // The result is limited to 4096 characters (including the tailing
183 // 0). If 4096 characters are not enough to format the input,
184 // "<buffer exceeded>" is returned.
185 static String Format(const char* format, ...);
189 // The default c'tor constructs a NULL string.
190 String() : c_str_(NULL), length_(0) {}
192 // Constructs a String by cloning a 0-terminated C string.
193 String(const char* c_str) { // NOLINT
198 ConstructNonNull(c_str, strlen(c_str));
202 // Constructs a String by copying a given number of chars from a
203 // buffer. E.g. String("hello", 3) creates the string "hel",
204 // String("a\0bcd", 4) creates "a\0bc", String(NULL, 0) creates "",
205 // and String(NULL, 1) results in access violation.
206 String(const char* buffer, size_t length) {
207 ConstructNonNull(buffer, length);
210 // The copy c'tor creates a new copy of the string. The two
211 // String objects do not share content.
212 String(const String& str) : c_str_(NULL), length_(0) { *this = str; }
214 // D'tor. String is intended to be a final class, so the d'tor
215 // doesn't need to be virtual.
216 ~String() { delete[] c_str_; }
218 // Allows a String to be implicitly converted to an ::std::string or
219 // ::string, and vice versa. Converting a String containing a NULL
220 // pointer to ::std::string or ::string is undefined behavior.
221 // Converting a ::std::string or ::string containing an embedded NUL
222 // character to a String will result in the prefix up to the first
224 #if GTEST_HAS_STD_STRING
225 String(const ::std::string& str) {
226 ConstructNonNull(str.c_str(), str.length());
229 operator ::std::string() const { return ::std::string(c_str(), length()); }
230 #endif // GTEST_HAS_STD_STRING
232 #if GTEST_HAS_GLOBAL_STRING
233 String(const ::string& str) {
234 ConstructNonNull(str.c_str(), str.length());
237 operator ::string() const { return ::string(c_str(), length()); }
238 #endif // GTEST_HAS_GLOBAL_STRING
240 // Returns true iff this is an empty string (i.e. "").
241 bool empty() const { return (c_str() != NULL) && (length() == 0); }
243 // Compares this with another String.
244 // Returns < 0 if this is less than rhs, 0 if this is equal to rhs, or > 0
245 // if this is greater than rhs.
246 int Compare(const String& rhs) const;
248 // Returns true iff this String equals the given C string. A NULL
249 // string and a non-NULL string are considered not equal.
250 bool operator==(const char* c_str) const { return Compare(c_str) == 0; }
252 // Returns true iff this String is less than the given String. A
253 // NULL string is considered less than "".
254 bool operator<(const String& rhs) const { return Compare(rhs) < 0; }
256 // Returns true iff this String doesn't equal the given C string. A NULL
257 // string and a non-NULL string are considered not equal.
258 bool operator!=(const char* c_str) const { return !(*this == c_str); }
260 // Returns true iff this String ends with the given suffix. *Any*
261 // String is considered to end with a NULL or empty suffix.
262 bool EndsWith(const char* suffix) const;
264 // Returns true iff this String ends with the given suffix, not considering
265 // case. Any String is considered to end with a NULL or empty suffix.
266 bool EndsWithCaseInsensitive(const char* suffix) const;
268 // Returns the length of the encapsulated string, or 0 if the
270 size_t length() const { return length_; }
272 // Gets the 0-terminated C string this String object represents.
273 // The String object still owns the string. Therefore the caller
274 // should NOT delete the return value.
275 const char* c_str() const { return c_str_; }
277 // Assigns a C string to this object. Self-assignment works.
278 const String& operator=(const char* c_str) { return *this = String(c_str); }
280 // Assigns a String object to this object. Self-assignment works.
281 const String& operator=(const String& rhs) {
284 if (rhs.c_str() == NULL) {
288 ConstructNonNull(rhs.c_str(), rhs.length());
296 // Constructs a non-NULL String from the given content. This
297 // function can only be called when data_ has not been allocated.
298 // ConstructNonNull(NULL, 0) results in an empty string ("").
299 // ConstructNonNull(NULL, non_zero) is undefined behavior.
300 void ConstructNonNull(const char* buffer, size_t length) {
301 char* const str = new char[length + 1];
302 memcpy(str, buffer, length);
312 // Streams a String to an ostream. Each '\0' character in the String
313 // is replaced with "\\0".
314 inline ::std::ostream& operator<<(::std::ostream& os, const String& str) {
315 if (str.c_str() == NULL) {
318 const char* const c_str = str.c_str();
319 for (size_t i = 0; i != str.length(); i++) {
320 if (c_str[i] == '\0') {
330 // Gets the content of the StrStream's buffer as a String. Each '\0'
331 // character in the buffer is replaced with "\\0".
332 String StrStreamToString(StrStream* stream);
334 // Converts a streamable value to a String. A NULL pointer is
335 // converted to "(null)". When the input value is a ::string,
336 // ::std::string, ::wstring, or ::std::wstring object, each NUL
337 // character in it is replaced with "\\0".
339 // Declared here but defined in gtest.h, so that it has access
340 // to the definition of the Message class, required by the ARM
342 template <typename T>
343 String StreamableToString(const T& streamable);
345 } // namespace internal
346 } // namespace testing
348 #endif // GTEST_INCLUDE_GTEST_INTERNAL_GTEST_STRING_H_