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 testing/base/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 47namespace testing { 48namespace internal { 49 50// String - a UTF-8 string class. 51// 52// We cannot use std::string as Microsoft's STL implementation in 53// Visual C++ 7.1 has problems when exception is disabled. There is a 54// hack to work around this, but we've seen cases where the hack fails 55// to work. 56// 57// Also, String is different from std::string in that it can represent 58// both NULL and the empty string, while std::string cannot represent 59// NULL. 60// 61// NULL and the empty string are considered different. NULL is less 62// than anything (including the empty string) except itself. 63// 64// This class only provides minimum functionality necessary for 65// implementing Google Test. We do not intend to implement a full-fledged 66// string class here. 67// 68// Since the purpose of this class is to provide a substitute for 69// std::string on platforms where it cannot be used, we define a copy 70// constructor and assignment operators such that we don't need 71// conditional compilation in a lot of places. 72// 73// In order to make the representation efficient, the d'tor of String 74// is not virtual. Therefore DO NOT INHERIT FROM String. 75class String { 76 public: 77 // Static utility methods 78 79 // Returns the input if it's not NULL, otherwise returns "(null)". 80 // This function serves two purposes: 81 // 82 // 1. ShowCString(NULL) has type 'const char *', instead of the 83 // type of NULL (which is int). 84 // 85 // 2. In MSVC, streaming a null char pointer to StrStream generates 86 // an access violation, so we need to convert NULL to "(null)" 87 // before streaming it. 88 static inline const char* ShowCString(const char* c_str) { 89 return c_str ? c_str : "(null)"; 90 } 91 92 // Returns the input enclosed in double quotes if it's not NULL; 93 // otherwise returns "(null)". For example, "\"Hello\"" is returned 94 // for input "Hello". 95 // 96 // This is useful for printing a C string in the syntax of a literal. 97 // 98 // Known issue: escape sequences are not handled yet. 99 static String ShowCStringQuoted(const char* c_str); 100 101 // Clones a 0-terminated C string, allocating memory using new. The 102 // caller is responsible for deleting the return value using 103 // delete[]. Returns the cloned string, or NULL if the input is 104 // NULL. 105 // 106 // This is different from strdup() in string.h, which allocates 107 // memory using malloc(). 108 static const char* CloneCString(const char* c_str); 109 110 // Compares two C strings. Returns true iff they have the same content. 111 // 112 // Unlike strcmp(), this function can handle NULL argument(s). A 113 // NULL C string is considered different to any non-NULL C string, 114 // including the empty string. 115 static bool CStringEquals(const char* lhs, const char* rhs); 116 117 // Converts a wide C string to a String using the UTF-8 encoding. 118 // NULL will be converted to "(null)". If an error occurred during 119 // the conversion, "(failed to convert from wide string)" is 120 // returned. 121 static String ShowWideCString(const wchar_t* wide_c_str); 122 123 // Similar to ShowWideCString(), except that this function encloses 124 // the converted string in double quotes. 125 static String ShowWideCStringQuoted(const wchar_t* wide_c_str); 126 127 // Compares two wide C strings. Returns true iff they have the same 128 // content. 129 // 130 // Unlike wcscmp(), this function can handle NULL argument(s). A 131 // NULL C string is considered different to any non-NULL C string, 132 // including the empty string. 133 static bool WideCStringEquals(const wchar_t* lhs, const wchar_t* rhs); 134 135 // Compares two C strings, ignoring case. Returns true iff they 136 // have the same content. 137 // 138 // Unlike strcasecmp(), this function can handle NULL argument(s). 139 // A NULL C string is considered different to any non-NULL C string, 140 // including the empty string. 141 static bool CaseInsensitiveCStringEquals(const char* lhs, 142 const char* rhs); 143 144 // Formats a list of arguments to a String, using the same format 145 // spec string as for printf. 146 // 147 // We do not use the StringPrintf class as it is not universally 148 // available. 149 // 150 // The result is limited to 4096 characters (including the tailing 151 // 0). If 4096 characters are not enough to format the input, 152 // "<buffer exceeded>" is returned. 153 static String Format(const char* format, ...); 154 155 // C'tors 156 157 // The default c'tor constructs a NULL string. 158 String() : c_str_(NULL) {} 159 160 // Constructs a String by cloning a 0-terminated C string. 161 String(const char* c_str) : c_str_(NULL) { // NOLINT 162 *this = c_str; 163 } 164 165 // Constructs a String by copying a given number of chars from a 166 // buffer. E.g. String("hello", 3) will create the string "hel". 167 String(const char* buffer, size_t len); 168 169 // The copy c'tor creates a new copy of the string. The two 170 // String objects do not share content. 171 String(const String& str) : c_str_(NULL) { 172 *this = str; 173 } 174 175 // D'tor. String is intended to be a final class, so the d'tor 176 // doesn't need to be virtual. 177 ~String() { delete[] c_str_; } 178 179 // Returns true iff this is an empty string (i.e. ""). 180 bool empty() const { 181 return (c_str_ != NULL) && (*c_str_ == '\0'); 182 } 183 184 // Compares this with another String. 185 // Returns < 0 if this is less than rhs, 0 if this is equal to rhs, or > 0 186 // if this is greater than rhs. 187 int Compare(const String& rhs) const; 188 189 // Returns true iff this String equals the given C string. A NULL 190 // string and a non-NULL string are considered not equal. 191 bool operator==(const char* c_str) const { 192 return CStringEquals(c_str_, c_str); 193 } 194 195 // Returns true iff this String doesn't equal the given C string. A NULL 196 // string and a non-NULL string are considered not equal. 197 bool operator!=(const char* c_str) const { 198 return !CStringEquals(c_str_, c_str); 199 } 200 201 // Returns true iff this String ends with the given suffix. *Any* 202 // String is considered to end with a NULL or empty suffix. 203 bool EndsWith(const char* suffix) const; 204 205 // Returns true iff this String ends with the given suffix, not considering 206 // case. Any String is considered to end with a NULL or empty suffix. 207 bool EndsWithCaseInsensitive(const char* suffix) const; 208 209 // Returns the length of the encapsulated string, or -1 if the 210 // string is NULL. 211 int GetLength() const { 212 return c_str_ ? static_cast<int>(strlen(c_str_)) : -1; 213 } 214 215 // Gets the 0-terminated C string this String object represents. 216 // The String object still owns the string. Therefore the caller 217 // should NOT delete the return value. 218 const char* c_str() const { return c_str_; } 219 220 // Sets the 0-terminated C string this String object represents. 221 // The old string in this object is deleted, and this object will 222 // own a clone of the input string. This function copies only up to 223 // length bytes (plus a terminating null byte), or until the first 224 // null byte, whichever comes first. 225 // 226 // This function works even when the c_str parameter has the same 227 // value as that of the c_str_ field. 228 void Set(const char* c_str, size_t length); 229 230 // Assigns a C string to this object. Self-assignment works. 231 const String& operator=(const char* c_str); 232 233 // Assigns a String object to this object. Self-assignment works. 234 const String& operator=(const String &rhs) { 235 *this = rhs.c_str_; 236 return *this; 237 } 238 239 private: 240 const char* c_str_; 241}; 242 243// Streams a String to an ostream. 244inline ::std::ostream& operator <<(::std::ostream& os, const String& str) { 245 // We call String::ShowCString() to convert NULL to "(null)". 246 // Otherwise we'll get an access violation on Windows. 247 return os << String::ShowCString(str.c_str()); 248} 249 250// Gets the content of the StrStream's buffer as a String. Each '\0' 251// character in the buffer is replaced with "\\0". 252String StrStreamToString(StrStream* stream); 253 254// Converts a streamable value to a String. A NULL pointer is 255// converted to "(null)". When the input value is a ::string, 256// ::std::string, ::wstring, or ::std::wstring object, each NUL 257// character in it is replaced with "\\0". 258 259// Declared here but defined in gtest.h, so that it has access 260// to the definition of the Message class, required by the ARM 261// compiler. 262template <typename T> 263String StreamableToString(const T& streamable); 264 265} // namespace internal 266} // namespace testing 267 268#endif // GTEST_INCLUDE_GTEST_INTERNAL_GTEST_STRING_H_ 269