Home | History | Annotate | Download | only in internal
      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 (at) google.com (Zhanyong Wan), eefacm (at) 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>
     50 #include "gtest/internal/gtest-port.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 (at) 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.
     81 class GTEST_API_ 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.
    226   String(const ::std::string& str) {
    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_
    351