gtest-string.h 13.3 KB
Newer Older
shiqian's avatar
shiqian committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// Copyright 2005, Google Inc.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//     * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//     * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Authors: wan@google.com (Zhanyong Wan), eefacm@gmail.com (Sean Mcafee)
//
// The Google C++ Testing Framework (Google Test)
//
// This header file declares the String class and functions used internally by
// Google Test.  They are subject to change without notice. They should not used
// by code external to Google Test.
//
38
// This header file is #included by <gtest/internal/gtest-internal.h>.
shiqian's avatar
shiqian committed
39
40
41
42
43
// It should not be #included by other files.

#ifndef GTEST_INCLUDE_GTEST_INTERNAL_GTEST_STRING_H_
#define GTEST_INCLUDE_GTEST_INTERNAL_GTEST_STRING_H_

44
45
46
47
48
#ifdef __BORLANDC__
// string.h is not guaranteed to provide strcpy on C++ Builder.
#include <mem.h>
#endif

shiqian's avatar
shiqian committed
49
#include <string.h>
50
#include "gtest/internal/gtest-port.h"
shiqian's avatar
shiqian committed
51

52
53
#include <string>

shiqian's avatar
shiqian committed
54
55
56
57
58
namespace testing {
namespace internal {

// String - a UTF-8 string class.
//
59
// For historic reasons, we don't use std::string.
shiqian's avatar
shiqian committed
60
//
61
62
63
64
65
// TODO(wan@google.com): replace this class with std::string or
// implement it in terms of the latter.
//
// Note that String can represent both NULL and the empty string,
// while std::string cannot represent NULL.
shiqian's avatar
shiqian committed
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
//
// NULL and the empty string are considered different.  NULL is less
// than anything (including the empty string) except itself.
//
// This class only provides minimum functionality necessary for
// implementing Google Test.  We do not intend to implement a full-fledged
// string class here.
//
// Since the purpose of this class is to provide a substitute for
// std::string on platforms where it cannot be used, we define a copy
// constructor and assignment operators such that we don't need
// conditional compilation in a lot of places.
//
// In order to make the representation efficient, the d'tor of String
// is not virtual.  Therefore DO NOT INHERIT FROM String.
81
class GTEST_API_ String {
shiqian's avatar
shiqian committed
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 public:
  // Static utility methods

  // Returns the input enclosed in double quotes if it's not NULL;
  // otherwise returns "(null)".  For example, "\"Hello\"" is returned
  // for input "Hello".
  //
  // This is useful for printing a C string in the syntax of a literal.
  //
  // Known issue: escape sequences are not handled yet.
  static String ShowCStringQuoted(const char* c_str);

  // Clones a 0-terminated C string, allocating memory using new.  The
  // caller is responsible for deleting the return value using
  // delete[].  Returns the cloned string, or NULL if the input is
  // NULL.
  //
  // This is different from strdup() in string.h, which allocates
  // memory using malloc().
  static const char* CloneCString(const char* c_str);

103
#if GTEST_OS_WINDOWS_MOBILE
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
  // Windows CE does not have the 'ANSI' versions of Win32 APIs. To be
  // able to pass strings to Win32 APIs on CE we need to convert them
  // to 'Unicode', UTF-16.

  // Creates a UTF-16 wide string from the given ANSI string, allocating
  // memory using new. The caller is responsible for deleting the return
  // value using delete[]. Returns the wide string, or NULL if the
  // input is NULL.
  //
  // The wide string is created using the ANSI codepage (CP_ACP) to
  // match the behaviour of the ANSI versions of Win32 calls and the
  // C runtime.
  static LPCWSTR AnsiToUtf16(const char* c_str);

  // Creates an ANSI string from the given wide string, allocating
  // memory using new. The caller is responsible for deleting the return
  // value using delete[]. Returns the ANSI string, or NULL if the
  // input is NULL.
  //
  // The returned string is created using the ANSI codepage (CP_ACP) to
  // match the behaviour of the ANSI versions of Win32 calls and the
  // C runtime.
  static const char* Utf16ToAnsi(LPCWSTR utf16_str);
#endif

shiqian's avatar
shiqian committed
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
  // Compares two C strings.  Returns true iff they have the same content.
  //
  // Unlike strcmp(), this function can handle NULL argument(s).  A
  // NULL C string is considered different to any non-NULL C string,
  // including the empty string.
  static bool CStringEquals(const char* lhs, const char* rhs);

  // Converts a wide C string to a String using the UTF-8 encoding.
  // NULL will be converted to "(null)".  If an error occurred during
  // the conversion, "(failed to convert from wide string)" is
  // returned.
  static String ShowWideCString(const wchar_t* wide_c_str);

  // Similar to ShowWideCString(), except that this function encloses
  // the converted string in double quotes.
  static String ShowWideCStringQuoted(const wchar_t* wide_c_str);

  // Compares two wide C strings.  Returns true iff they have the same
  // content.
  //
  // Unlike wcscmp(), this function can handle NULL argument(s).  A
  // NULL C string is considered different to any non-NULL C string,
  // including the empty string.
  static bool WideCStringEquals(const wchar_t* lhs, const wchar_t* rhs);

  // Compares two C strings, ignoring case.  Returns true iff they
  // have the same content.
  //
  // Unlike strcasecmp(), this function can handle NULL argument(s).
  // A NULL C string is considered different to any non-NULL C string,
  // including the empty string.
  static bool CaseInsensitiveCStringEquals(const char* lhs,
                                           const char* rhs);

163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
  // Compares two wide C strings, ignoring case.  Returns true iff they
  // have the same content.
  //
  // Unlike wcscasecmp(), this function can handle NULL argument(s).
  // A NULL C string is considered different to any non-NULL wide C string,
  // including the empty string.
  // NB: The implementations on different platforms slightly differ.
  // On windows, this method uses _wcsicmp which compares according to LC_CTYPE
  // environment variable. On GNU platform this method uses wcscasecmp
  // which compares according to LC_CTYPE category of the current locale.
  // On MacOS X, it uses towlower, which also uses LC_CTYPE category of the
  // current locale.
  static bool CaseInsensitiveWideCStringEquals(const wchar_t* lhs,
                                               const wchar_t* rhs);

shiqian's avatar
shiqian committed
178
179
180
181
182
183
184
185
186
187
188
189
190
  // Formats a list of arguments to a String, using the same format
  // spec string as for printf.
  //
  // We do not use the StringPrintf class as it is not universally
  // available.
  //
  // The result is limited to 4096 characters (including the tailing
  // 0).  If 4096 characters are not enough to format the input,
  // "<buffer exceeded>" is returned.
  static String Format(const char* format, ...);

  // C'tors

191
192
  // The default c'tor constructs a NULL string.
  String() : c_str_(NULL), length_(0) {}
shiqian's avatar
shiqian committed
193
194

  // Constructs a String by cloning a 0-terminated C string.
195
196
  String(const char* a_c_str) {  // NOLINT
    if (a_c_str == NULL) {
197
198
      c_str_ = NULL;
      length_ = 0;
199
    } else {
200
      ConstructNonNull(a_c_str, strlen(a_c_str));
201
    }
shiqian's avatar
shiqian committed
202
203
204
  }

  // Constructs a String by copying a given number of chars from a
205
206
207
  // buffer.  E.g. String("hello", 3) creates the string "hel",
  // String("a\0bcd", 4) creates "a\0bc", String(NULL, 0) creates "",
  // and String(NULL, 1) results in access violation.
208
209
  String(const char* buffer, size_t a_length) {
    ConstructNonNull(buffer, a_length);
210
  }
shiqian's avatar
shiqian committed
211
212
213

  // The copy c'tor creates a new copy of the string.  The two
  // String objects do not share content.
214
  String(const String& str) : c_str_(NULL), length_(0) { *this = str; }
shiqian's avatar
shiqian committed
215
216
217

  // D'tor.  String is intended to be a final class, so the d'tor
  // doesn't need to be virtual.
218
  ~String() { delete[] c_str_; }
shiqian's avatar
shiqian committed
219

220
221
222
223
224
225
  // Allows a String to be implicitly converted to an ::std::string or
  // ::string, and vice versa.  Converting a String containing a NULL
  // pointer to ::std::string or ::string is undefined behavior.
  // Converting a ::std::string or ::string containing an embedded NUL
  // character to a String will result in the prefix up to the first
  // NUL character.
226
227
228
  String(const ::std::string& str) {
    ConstructNonNull(str.c_str(), str.length());
  }
229

230
  operator ::std::string() const { return ::std::string(c_str(), length()); }
231
232

#if GTEST_HAS_GLOBAL_STRING
233
234
235
  String(const ::string& str) {
    ConstructNonNull(str.c_str(), str.length());
  }
236

237
  operator ::string() const { return ::string(c_str(), length()); }
238
239
#endif  // GTEST_HAS_GLOBAL_STRING

shiqian's avatar
shiqian committed
240
  // Returns true iff this is an empty string (i.e. "").
241
  bool empty() const { return (c_str() != NULL) && (length() == 0); }
shiqian's avatar
shiqian committed
242
243
244
245
246
247
248
249

  // Compares this with another String.
  // Returns < 0 if this is less than rhs, 0 if this is equal to rhs, or > 0
  // if this is greater than rhs.
  int Compare(const String& rhs) const;

  // Returns true iff this String equals the given C string.  A NULL
  // 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; }
shiqian's avatar
shiqian committed
251

252
253
  // Returns true iff this String is less than the given String.  A
  // NULL string is considered less than "".
254
255
  bool operator<(const String& rhs) const { return Compare(rhs) < 0; }

shiqian's avatar
shiqian committed
256
257
  // Returns true iff this String doesn't equal the given C string.  A NULL
  // string and a non-NULL string are considered not equal.
258
  bool operator!=(const char* a_c_str) const { return !(*this == a_c_str); }
shiqian's avatar
shiqian committed
259
260
261
262
263
264
265
266
267

  // Returns true iff this String ends with the given suffix.  *Any*
  // String is considered to end with a NULL or empty suffix.
  bool EndsWith(const char* suffix) const;

  // Returns true iff this String ends with the given suffix, not considering
  // case. Any String is considered to end with a NULL or empty suffix.
  bool EndsWithCaseInsensitive(const char* suffix) const;

268
  // Returns the length of the encapsulated string, or 0 if the
shiqian's avatar
shiqian committed
269
  // string is NULL.
270
  size_t length() const { return length_; }
shiqian's avatar
shiqian committed
271
272
273
274

  // Gets the 0-terminated C string this String object represents.
  // The String object still owns the string.  Therefore the caller
  // should NOT delete the return value.
275
  const char* c_str() const { return c_str_; }
shiqian's avatar
shiqian committed
276
277

  // Assigns a C string to this object.  Self-assignment works.
278
279
280
  const String& operator=(const char* a_c_str) {
    return *this = String(a_c_str);
  }
shiqian's avatar
shiqian committed
281
282

  // Assigns a String object to this object.  Self-assignment works.
283
284
  const String& operator=(const String& rhs) {
    if (this != &rhs) {
285
286
287
288
289
290
      delete[] c_str_;
      if (rhs.c_str() == NULL) {
        c_str_ = NULL;
        length_ = 0;
      } else {
        ConstructNonNull(rhs.c_str(), rhs.length());
291
292
293
      }
    }

shiqian's avatar
shiqian committed
294
295
296
297
    return *this;
  }

 private:
298
299
300
301
  // Constructs a non-NULL String from the given content.  This
  // function can only be called when data_ has not been allocated.
  // ConstructNonNull(NULL, 0) results in an empty string ("").
  // ConstructNonNull(NULL, non_zero) is undefined behavior.
302
303
304
305
  void ConstructNonNull(const char* buffer, size_t a_length) {
    char* const str = new char[a_length + 1];
    memcpy(str, buffer, a_length);
    str[a_length] = '\0';
306
    c_str_ = str;
307
    length_ = a_length;
308
  }
shiqian's avatar
shiqian committed
309

310
311
  const char* c_str_;
  size_t length_;
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
};  // class String

// Streams a String to an ostream.  Each '\0' character in the String
// is replaced with "\\0".
inline ::std::ostream& operator<<(::std::ostream& os, const String& str) {
  if (str.c_str() == NULL) {
    os << "(null)";
  } else {
    const char* const c_str = str.c_str();
    for (size_t i = 0; i != str.length(); i++) {
      if (c_str[i] == '\0') {
        os << "\\0";
      } else {
        os << c_str[i];
      }
    }
  }
  return os;
shiqian's avatar
shiqian committed
330
331
}

332
// Gets the content of the stringstream's buffer as a String.  Each '\0'
shiqian's avatar
shiqian committed
333
// character in the buffer is replaced with "\\0".
334
GTEST_API_ String StringStreamToString(::std::stringstream* stream);
shiqian's avatar
shiqian committed
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350

// Converts a streamable value to a String.  A NULL pointer is
// converted to "(null)".  When the input value is a ::string,
// ::std::string, ::wstring, or ::std::wstring object, each NUL
// character in it is replaced with "\\0".

// Declared here but defined in gtest.h, so that it has access
// to the definition of the Message class, required by the ARM
// compiler.
template <typename T>
String StreamableToString(const T& streamable);

}  // namespace internal
}  // namespace testing

#endif  // GTEST_INCLUDE_GTEST_INTERNAL_GTEST_STRING_H_