Orxonox  0.0.5 Codename: Arcturus
gtest-string.h
Go to the documentation of this file.
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 #ifdef __BORLANDC__
45 // string.h is not guaranteed to provide strcpy on C++ Builder.
46 # include <mem.h>
47 #endif
48 
49 #include <string.h>
51 
52 #include <string>
53 
54 namespace testing {
55 namespace internal {
56 
57 // String - a UTF-8 string class.
58 //
59 // For historic reasons, we don't use std::string.
60 //
61 // TODO(wan@google.com): replace this class with std::string or
62 // implement it in terms of the latter.
63 //
64 // Note that String can represent both NULL and the empty string,
65 // while std::string cannot represent NULL.
66 //
67 // NULL and the empty string are considered different. NULL is less
68 // than anything (including the empty string) except itself.
69 //
70 // This class only provides minimum functionality necessary for
71 // implementing Google Test. We do not intend to implement a full-fledged
72 // string class here.
73 //
74 // Since the purpose of this class is to provide a substitute for
75 // std::string on platforms where it cannot be used, we define a copy
76 // constructor and assignment operators such that we don't need
77 // conditional compilation in a lot of places.
78 //
79 // In order to make the representation efficient, the d'tor of String
80 // is not virtual. Therefore DO NOT INHERIT FROM String.
82  public:
83  // Static utility methods
84 
85  // Returns the input enclosed in double quotes if it's not NULL;
86  // otherwise returns "(null)". For example, "\"Hello\"" is returned
87  // for input "Hello".
88  //
89  // This is useful for printing a C string in the syntax of a literal.
90  //
91  // Known issue: escape sequences are not handled yet.
92  static String ShowCStringQuoted(const char* c_str);
93 
94  // Clones a 0-terminated C string, allocating memory using new. The
95  // caller is responsible for deleting the return value using
96  // delete[]. Returns the cloned string, or NULL if the input is
97  // NULL.
98  //
99  // This is different from strdup() in string.h, which allocates
100  // memory using malloc().
101  static const char* CloneCString(const char* c_str);
102 
103 #if GTEST_OS_WINDOWS_MOBILE
104  // Windows CE does not have the 'ANSI' versions of Win32 APIs. To be
105  // able to pass strings to Win32 APIs on CE we need to convert them
106  // to 'Unicode', UTF-16.
107 
108  // Creates a UTF-16 wide string from the given ANSI string, allocating
109  // memory using new. The caller is responsible for deleting the return
110  // value using delete[]. Returns the wide string, or NULL if the
111  // input is NULL.
112  //
113  // The wide string is created using the ANSI codepage (CP_ACP) to
114  // match the behaviour of the ANSI versions of Win32 calls and the
115  // C runtime.
116  static LPCWSTR AnsiToUtf16(const char* c_str);
117 
118  // Creates an ANSI string from the given wide string, allocating
119  // memory using new. The caller is responsible for deleting the return
120  // value using delete[]. Returns the ANSI string, or NULL if the
121  // input is NULL.
122  //
123  // The returned string is created using the ANSI codepage (CP_ACP) to
124  // match the behaviour of the ANSI versions of Win32 calls and the
125  // C runtime.
126  static const char* Utf16ToAnsi(LPCWSTR utf16_str);
127 #endif
128 
129  // Compares two C strings. Returns true iff they have the same content.
130  //
131  // Unlike strcmp(), this function can handle NULL argument(s). A
132  // NULL C string is considered different to any non-NULL C string,
133  // including the empty string.
134  static bool CStringEquals(const char* lhs, const char* rhs);
135 
136  // Converts a wide C string to a String using the UTF-8 encoding.
137  // NULL will be converted to "(null)". If an error occurred during
138  // the conversion, "(failed to convert from wide string)" is
139  // returned.
140  static String ShowWideCString(const wchar_t* wide_c_str);
141 
142  // Similar to ShowWideCString(), except that this function encloses
143  // the converted string in double quotes.
144  static String ShowWideCStringQuoted(const wchar_t* wide_c_str);
145 
146  // Compares two wide C strings. Returns true iff they have the same
147  // content.
148  //
149  // Unlike wcscmp(), this function can handle NULL argument(s). A
150  // NULL C string is considered different to any non-NULL C string,
151  // including the empty string.
152  static bool WideCStringEquals(const wchar_t* lhs, const wchar_t* rhs);
153 
154  // Compares two C strings, ignoring case. Returns true iff they
155  // have the same content.
156  //
157  // Unlike strcasecmp(), this function can handle NULL argument(s).
158  // A NULL C string is considered different to any non-NULL C string,
159  // including the empty string.
160  static bool CaseInsensitiveCStringEquals(const char* lhs,
161  const char* rhs);
162 
163  // Compares two wide C strings, ignoring case. Returns true iff they
164  // have the same content.
165  //
166  // Unlike wcscasecmp(), this function can handle NULL argument(s).
167  // A NULL C string is considered different to any non-NULL wide C string,
168  // including the empty string.
169  // NB: The implementations on different platforms slightly differ.
170  // On windows, this method uses _wcsicmp which compares according to LC_CTYPE
171  // environment variable. On GNU platform this method uses wcscasecmp
172  // which compares according to LC_CTYPE category of the current locale.
173  // On MacOS X, it uses towlower, which also uses LC_CTYPE category of the
174  // current locale.
175  static bool CaseInsensitiveWideCStringEquals(const wchar_t* lhs,
176  const wchar_t* rhs);
177 
178  // Formats a list of arguments to a String, using the same format
179  // spec string as for printf.
180  //
181  // We do not use the StringPrintf class as it is not universally
182  // available.
183  //
184  // The result is limited to 4096 characters (including the tailing
185  // 0). If 4096 characters are not enough to format the input,
186  // "<buffer exceeded>" is returned.
187  static String Format(const char* format, ...);
188 
189  // C'tors
190 
191  // The default c'tor constructs a NULL string.
192  String() : c_str_(NULL), length_(0) {}
193 
194  // Constructs a String by cloning a 0-terminated C string.
195  String(const char* a_c_str) { // NOLINT
196  if (a_c_str == NULL) {
197  c_str_ = NULL;
198  length_ = 0;
199  } else {
200  ConstructNonNull(a_c_str, strlen(a_c_str));
201  }
202  }
203 
204  // Constructs a String by copying a given number of chars from a
205  // buffer. E.g. String("hello", 3) creates the string "hel",
206  // String("a\0bcd", 4) creates "a\0bc", String(NULL, 0) creates "",
207  // and String(NULL, 1) results in access violation.
208  String(const char* buffer, size_t a_length) {
209  ConstructNonNull(buffer, a_length);
210  }
211 
212  // The copy c'tor creates a new copy of the string. The two
213  // String objects do not share content.
214  String(const String& str) : c_str_(NULL), length_(0) { *this = str; }
215 
216  // D'tor. String is intended to be a final class, so the d'tor
217  // doesn't need to be virtual.
218  ~String() { delete[] c_str_; }
219 
220  // Allows a String to be implicitly converted to an ::std::string or
221  // ::string, and vice versa. Converting a String containing a NULL
222  // pointer to ::std::string or ::string is undefined behavior.
223  // Converting a ::std::string or ::string containing an embedded NUL
224  // character to a String will result in the prefix up to the first
225  // NUL character.
227  ConstructNonNull(str.c_str(), str.length());
228  }
229 
230  operator ::std::string() const { return ::std::string(c_str(), length()); }
231 
232 #if GTEST_HAS_GLOBAL_STRING
233  String(const ::string& str) {
234  ConstructNonNull(str.c_str(), str.length());
235  }
236 
237  operator ::string() const { return ::string(c_str(), length()); }
238 #endif // GTEST_HAS_GLOBAL_STRING
239 
240  // Returns true iff this is an empty string (i.e. "").
241  bool empty() const { return (c_str() != NULL) && (length() == 0); }
242 
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;
247 
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* a_c_str) const { return Compare(a_c_str) == 0; }
251 
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; }
255 
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* a_c_str) const { return !(*this == a_c_str); }
259 
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;
263 
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;
267 
268  // Returns the length of the encapsulated string, or 0 if the
269  // string is NULL.
270  size_t length() const { return length_; }
271 
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_; }
276 
277  // Assigns a C string to this object. Self-assignment works.
278  const String& operator=(const char* a_c_str) {
279  return *this = String(a_c_str);
280  }
281 
282  // Assigns a String object to this object. Self-assignment works.
283  const String& operator=(const String& rhs) {
284  if (this != &rhs) {
285  delete[] c_str_;
286  if (rhs.c_str() == NULL) {
287  c_str_ = NULL;
288  length_ = 0;
289  } else {
290  ConstructNonNull(rhs.c_str(), rhs.length());
291  }
292  }
293 
294  return *this;
295  }
296 
297  private:
298  // Constructs a non-NULL String from the given content. This
299  // function can only be called when c_str_ has not been allocated.
300  // ConstructNonNull(NULL, 0) results in an empty string ("").
301  // ConstructNonNull(NULL, non_zero) is undefined behavior.
302  void ConstructNonNull(const char* buffer, size_t a_length) {
303  char* const str = new char[a_length + 1];
304  memcpy(str, buffer, a_length);
305  str[a_length] = '\0';
306  c_str_ = str;
307  length_ = a_length;
308  }
309 
310  const char* c_str_;
311  size_t length_;
312 }; // class String
313 
314 // Streams a String to an ostream. Each '\0' character in the String
315 // is replaced with "\\0".
316 inline ::std::ostream& operator<<(::std::ostream& os, const String& str) {
317  if (str.c_str() == NULL) {
318  os << "(null)";
319  } else {
320  const char* const c_str = str.c_str();
321  for (size_t i = 0; i != str.length(); i++) {
322  if (c_str[i] == '\0') {
323  os << "\\0";
324  } else {
325  os << c_str[i];
326  }
327  }
328  }
329  return os;
330 }
331 
332 // Gets the content of the stringstream's buffer as a String. Each '\0'
333 // character in the buffer is replaced with "\\0".
334 GTEST_API_ String StringStreamToString(::std::stringstream* stream);
335 
336 // Converts a streamable value to a String. A NULL pointer is
337 // converted to "(null)". When the input value is a ::string,
338 // ::std::string, ::wstring, or ::std::wstring object, each NUL
339 // character in it is replaced with "\\0".
340 
341 // Declared here but defined in gtest.h, so that it has access
342 // to the definition of the Message class, required by the ARM
343 // compiler.
344 template <typename T>
345 String StreamableToString(const T& streamable);
346 
347 } // namespace internal
348 } // namespace testing
349 
350 #endif // GTEST_INCLUDE_GTEST_INTERNAL_GTEST_STRING_H_
PolymorphicMatcher< internal::EndsWithMatcher< internal::string > > EndsWith(const internal::string &suffix)
Definition: gmock-matchers.h:2795
Definition: gmock-actions.h:49
size_t length() const
Definition: gtest-string.h:270
inline::std::ostream & operator<<(::std::ostream &os, const String &str)
Definition: gtest-string.h:316
bool operator==(const char *a_c_str) const
Definition: gtest-string.h:250
::std::string string
Definition: gtest-port.h:756
GTEST_API_ String StringStreamToString(::std::stringstream *stream)
Definition: gtest.cc:1735
const char * c_str_
Definition: gtest-string.h:310
#define GTEST_API_
Definition: gtest-port.h:662
bool operator<(const String &rhs) const
Definition: gtest-string.h:254
size_t length_
Definition: gtest-string.h:311
const char * c_str() const
Definition: gtest-string.h:275
String(const ::std::string &str)
Definition: gtest-string.h:226
const String & operator=(const char *a_c_str)
Definition: gtest-string.h:278
~String()
Definition: gtest-string.h:218
bool operator!=(const char *a_c_str) const
Definition: gtest-string.h:258
void ConstructNonNull(const char *buffer, size_t a_length)
Definition: gtest-string.h:302
const String & operator=(const String &rhs)
Definition: gtest-string.h:283
bool CaseInsensitiveCStringEquals(const char *lhs, const char *rhs)
Definition: gmock-matchers.h:854
Definition: gtest-string.h:81
bool empty() const
Definition: gtest-string.h:241
Definition: InputPrereqs.h:78
String(const char *a_c_str)
Definition: gtest-string.h:195
String()
Definition: gtest-string.h:192
String(const String &str)
Definition: gtest-string.h:214
String(const char *buffer, size_t a_length)
Definition: gtest-string.h:208
String StreamableToString(const T &streamable)
Definition: gtest.h:172