gtest-string.h revision 1be2c9def7187e4e643c00a31dd9986395795d7d
1// Copyright 2005, Google Inc. 2// 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// Authors: wan@google.com (Zhanyong Wan), eefacm@gmail.com (Sean Mcafee) 31// 32// The Google C++ Testing Framework (Google Test) 33// 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. 37// 38// This header file is #included by <gtest/internal/gtest-internal.h>. 39// It should not be #included by other files. 40 41#ifndef GTEST_INCLUDE_GTEST_INTERNAL_GTEST_STRING_H_ 42#define GTEST_INCLUDE_GTEST_INTERNAL_GTEST_STRING_H_ 43 44#include <string.h> 45#include <gtest/internal/gtest-port.h> 46 47#if GTEST_HAS_GLOBAL_STRING || GTEST_HAS_STD_STRING 48#include <string> 49#endif // GTEST_HAS_GLOBAL_STRING || GTEST_HAS_STD_STRING 50 51namespace testing { 52namespace internal { 53 54// String - a UTF-8 string class. 55// 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 59// to work. 60// 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 63// NULL. 64// 65// NULL and the empty string are considered different. NULL is less 66// than anything (including the empty string) except itself. 67// 68// This class only provides minimum functionality necessary for 69// implementing Google Test. We do not intend to implement a full-fledged 70// string class here. 71// 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. 76// 77// In order to make the representation efficient, the d'tor of String 78// is not virtual. Therefore DO NOT INHERIT FROM String. 79class String { 80 public: 81 // Static utility methods 82 83 // Returns the input if it's not NULL, otherwise returns "(null)". 84 // This function serves two purposes: 85 // 86 // 1. ShowCString(NULL) has type 'const char *', instead of the 87 // type of NULL (which is int). 88 // 89 // 2. In MSVC, streaming a null char pointer to StrStream generates 90 // an access violation, so we need to convert NULL to "(null)" 91 // before streaming it. 92 static inline const char* ShowCString(const char* c_str) { 93 return c_str ? c_str : "(null)"; 94 } 95 96 // Returns the input enclosed in double quotes if it's not NULL; 97 // otherwise returns "(null)". For example, "\"Hello\"" is returned 98 // for input "Hello". 99 // 100 // This is useful for printing a C string in the syntax of a literal. 101 // 102 // Known issue: escape sequences are not handled yet. 103 static String ShowCStringQuoted(const char* c_str); 104 105 // Clones a 0-terminated C string, allocating memory using new. The 106 // caller is responsible for deleting the return value using 107 // delete[]. Returns the cloned string, or NULL if the input is 108 // NULL. 109 // 110 // This is different from strdup() in string.h, which allocates 111 // memory using malloc(). 112 static const char* CloneCString(const char* c_str); 113 114#ifdef _WIN32_WCE 115 // Windows CE does not have the 'ANSI' versions of Win32 APIs. To be 116 // able to pass strings to Win32 APIs on CE we need to convert them 117 // to 'Unicode', UTF-16. 118 119 // Creates a UTF-16 wide string from the given ANSI string, allocating 120 // memory using new. The caller is responsible for deleting the return 121 // value using delete[]. Returns the wide string, or NULL if the 122 // input is NULL. 123 // 124 // The wide string is created using the ANSI codepage (CP_ACP) to 125 // match the behaviour of the ANSI versions of Win32 calls and the 126 // C runtime. 127 static LPCWSTR AnsiToUtf16(const char* c_str); 128 129 // Creates an ANSI string from the given wide string, allocating 130 // memory using new. The caller is responsible for deleting the return 131 // value using delete[]. Returns the ANSI string, or NULL if the 132 // input is NULL. 133 // 134 // The returned string is created using the ANSI codepage (CP_ACP) to 135 // match the behaviour of the ANSI versions of Win32 calls and the 136 // C runtime. 137 static const char* Utf16ToAnsi(LPCWSTR utf16_str); 138#endif 139 140 // Compares two C strings. Returns true iff they have the same content. 141 // 142 // Unlike strcmp(), this function can handle NULL argument(s). A 143 // NULL C string is considered different to any non-NULL C string, 144 // including the empty string. 145 static bool CStringEquals(const char* lhs, const char* rhs); 146 147 // Converts a wide C string to a String using the UTF-8 encoding. 148 // NULL will be converted to "(null)". If an error occurred during 149 // the conversion, "(failed to convert from wide string)" is 150 // returned. 151 static String ShowWideCString(const wchar_t* wide_c_str); 152 153 // Similar to ShowWideCString(), except that this function encloses 154 // the converted string in double quotes. 155 static String ShowWideCStringQuoted(const wchar_t* wide_c_str); 156 157 // Compares two wide C strings. Returns true iff they have the same 158 // content. 159 // 160 // Unlike wcscmp(), this function can handle NULL argument(s). A 161 // NULL C string is considered different to any non-NULL C string, 162 // including the empty string. 163 static bool WideCStringEquals(const wchar_t* lhs, const wchar_t* rhs); 164 165 // Compares two C strings, ignoring case. Returns true iff they 166 // have the same content. 167 // 168 // Unlike strcasecmp(), this function can handle NULL argument(s). 169 // A NULL C string is considered different to any non-NULL C string, 170 // including the empty string. 171 static bool CaseInsensitiveCStringEquals(const char* lhs, 172 const char* rhs); 173 174 // Compares two wide C strings, ignoring case. Returns true iff they 175 // have the same content. 176 // 177 // Unlike wcscasecmp(), this function can handle NULL argument(s). 178 // A NULL C string is considered different to any non-NULL wide C string, 179 // including the empty string. 180 // NB: The implementations on different platforms slightly differ. 181 // On windows, this method uses _wcsicmp which compares according to LC_CTYPE 182 // environment variable. On GNU platform this method uses wcscasecmp 183 // which compares according to LC_CTYPE category of the current locale. 184 // On MacOS X, it uses towlower, which also uses LC_CTYPE category of the 185 // current locale. 186 static bool CaseInsensitiveWideCStringEquals(const wchar_t* lhs, 187 const wchar_t* rhs); 188 189 // Formats a list of arguments to a String, using the same format 190 // spec string as for printf. 191 // 192 // We do not use the StringPrintf class as it is not universally 193 // available. 194 // 195 // The result is limited to 4096 characters (including the tailing 196 // 0). If 4096 characters are not enough to format the input, 197 // "<buffer exceeded>" is returned. 198 static String Format(const char* format, ...); 199 200 // C'tors 201 202 // The default c'tor constructs a NULL string. 203 String() : c_str_(NULL) {} 204 205 // Constructs a String by cloning a 0-terminated C string. 206 String(const char* c_str) : c_str_(NULL) { // NOLINT 207 *this = c_str; 208 } 209 210 // Constructs a String by copying a given number of chars from a 211 // buffer. E.g. String("hello", 3) will create the string "hel". 212 String(const char* buffer, size_t len); 213 214 // The copy c'tor creates a new copy of the string. The two 215 // String objects do not share content. 216 String(const String& str) : c_str_(NULL) { 217 *this = str; 218 } 219 220 // D'tor. String is intended to be a final class, so the d'tor 221 // doesn't need to be virtual. 222 ~String() { delete[] c_str_; } 223 224 // Allows a String to be implicitly converted to an ::std::string or 225 // ::string, and vice versa. Converting a String containing a NULL 226 // pointer to ::std::string or ::string is undefined behavior. 227 // Converting a ::std::string or ::string containing an embedded NUL 228 // character to a String will result in the prefix up to the first 229 // NUL character. 230#if GTEST_HAS_STD_STRING 231 String(const ::std::string& str) : c_str_(NULL) { *this = str.c_str(); } 232 233 operator ::std::string() const { return ::std::string(c_str_); } 234#endif // GTEST_HAS_STD_STRING 235 236#if GTEST_HAS_GLOBAL_STRING 237 String(const ::string& str) : c_str_(NULL) { *this = str.c_str(); } 238 239 operator ::string() const { return ::string(c_str_); } 240#endif // GTEST_HAS_GLOBAL_STRING 241 242 // Returns true iff this is an empty string (i.e. ""). 243 bool empty() const { 244 return (c_str_ != NULL) && (*c_str_ == '\0'); 245 } 246 247 // Compares this with another String. 248 // Returns < 0 if this is less than rhs, 0 if this is equal to rhs, or > 0 249 // if this is greater than rhs. 250 int Compare(const String& rhs) const; 251 252 // Returns true iff this String equals the given C string. A NULL 253 // string and a non-NULL string are considered not equal. 254 bool operator==(const char* c_str) const { 255 return CStringEquals(c_str_, c_str); 256 } 257 258 // Returns true iff this String is less than the given C string. A NULL 259 // string is considered less than "". 260 bool operator<(const String& rhs) const { return Compare(rhs) < 0; } 261 262 // Returns true iff this String doesn't equal the given C string. A NULL 263 // string and a non-NULL string are considered not equal. 264 bool operator!=(const char* c_str) const { 265 return !CStringEquals(c_str_, c_str); 266 } 267 268 // Returns true iff this String ends with the given suffix. *Any* 269 // String is considered to end with a NULL or empty suffix. 270 bool EndsWith(const char* suffix) const; 271 272 // Returns true iff this String ends with the given suffix, not considering 273 // case. Any String is considered to end with a NULL or empty suffix. 274 bool EndsWithCaseInsensitive(const char* suffix) const; 275 276 // Returns the length of the encapsulated string, or -1 if the 277 // string is NULL. 278 int GetLength() const { 279 return c_str_ ? static_cast<int>(strlen(c_str_)) : -1; 280 } 281 282 // Gets the 0-terminated C string this String object represents. 283 // The String object still owns the string. Therefore the caller 284 // should NOT delete the return value. 285 const char* c_str() const { return c_str_; } 286 287 // Sets the 0-terminated C string this String object represents. 288 // The old string in this object is deleted, and this object will 289 // own a clone of the input string. This function copies only up to 290 // length bytes (plus a terminating null byte), or until the first 291 // null byte, whichever comes first. 292 // 293 // This function works even when the c_str parameter has the same 294 // value as that of the c_str_ field. 295 void Set(const char* c_str, size_t length); 296 297 // Assigns a C string to this object. Self-assignment works. 298 const String& operator=(const char* c_str); 299 300 // Assigns a String object to this object. Self-assignment works. 301 const String& operator=(const String &rhs) { 302 *this = rhs.c_str_; 303 return *this; 304 } 305 306 private: 307 const char* c_str_; 308}; 309 310// Streams a String to an ostream. 311inline ::std::ostream& operator <<(::std::ostream& os, const String& str) { 312 // We call String::ShowCString() to convert NULL to "(null)". 313 // Otherwise we'll get an access violation on Windows. 314 return os << String::ShowCString(str.c_str()); 315} 316 317// Gets the content of the StrStream's buffer as a String. Each '\0' 318// character in the buffer is replaced with "\\0". 319String StrStreamToString(StrStream* stream); 320 321// Converts a streamable value to a String. A NULL pointer is 322// converted to "(null)". When the input value is a ::string, 323// ::std::string, ::wstring, or ::std::wstring object, each NUL 324// character in it is replaced with "\\0". 325 326// Declared here but defined in gtest.h, so that it has access 327// to the definition of the Message class, required by the ARM 328// compiler. 329template <typename T> 330String StreamableToString(const T& streamable); 331 332} // namespace internal 333} // namespace testing 334 335#endif // GTEST_INCLUDE_GTEST_INTERNAL_GTEST_STRING_H_ 336