Changeset 26587 in vbox for trunk/include

Timestamp:

Feb 16, 2010 4:57:09 PM (15 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

57775

Message:

Main: Bstr makeover (second attempt) -- make Bstr(NULL) and Bstr() behave the same; resulting cleanup; make some more internal methods use Utf8Str instead of Bstr; fix a lot of CheckComArgNotNull?() usage

Location:

trunk/include

Files:

• VBox/com/Guid.h (modified) (2 diffs)
• VBox/com/string.h (modified) (18 diffs)
• iprt/cdefs.h (modified) (1 diff)
• iprt/cpp/ministring.h (modified) (13 diffs)

trunk/include/VBox/com/Guid.h

@@ -97 +97 @@
     {
         ::RTUuidClear (&uuid);
-        if (!that.isNull())
+        if (!that.isEmpty())
            ::RTUuidFromUtf16(&uuid, that.raw());
         refresh();
@@ -145 +145 @@
     }
 
-    Bstr toUtf16 () const
+    Bstr toUtf16() const
     {
         if (isEmpty())

trunk/include/VBox/com/string.h

@@ -3 +3 @@
 /** @file
  * MS COM / XPCOM Abstraction Layer:
- * Smart string classes declaration
+ * UTF-8 and UTF-16 string classes
  */
 
@@ -59 +59 @@
 
 /**
- *  Helper class that represents the |BSTR| type and hides platform-specific
- *  implementation details.
- *
- *  This class uses COM/XPCOM-provided memory management routines to allocate
- *  and free string buffers. This makes it possible to:
- *  - use it as a type of member variables of COM/XPCOM components and pass
- *    their values to callers through component methods' output parameters
- *    using the #cloneTo() operation;
- *  - adopt (take ownership of) string buffers returned in output parameters
- *    of COM methods using the #asOutParam() operation and correctly free them
- *    afterwards.
+ *  String class used universally in Main for COM-style Utf-16 strings.
+ *  Unfortunately COM on Windows uses UTF-16 everywhere, requiring conversions
+ *  back and forth since most of VirtualBox and our libraries use UTF-8.
+ *  The Bstr class makes such conversions easier.
+ *
+ *  Whereas the BSTR identifier is a typedef for a pointer to a wide character
+ *  array (const char *uint_16 effectively, depending on the platform),
+ *  the Bstr class is a fully featured string class with memory management
+ *  for such strings.
+ *
+ *  Bstr uses COM/XPCOM-provided memory management routines (SysAlloc* etc.)
+ *  to allocate and free string buffers. This makes it possible to use it as
+ *  a type of member variables of COM/XPCOM components and pass their values
+ *  to callers through component methods' output parameters using the #cloneTo()
+ *  operation. Also, the class can adopt (take ownership of) string buffers
+ *  returned in output parameters of COM methods using the #asOutParam()
+ *  operation and correctly free them afterwards.
+ *
+ *  As opposed to the Ut8Str class, which is very efficient, Bstr does not
+ *  cache the length of its member string. As a result, copying Bstr's is
+ *  more expensive, and Bstr really should only be used to capture arguments
+ *  from and return data to public COM methods.
+ *
+ *  Starting with VirtualBox 3.2, like Utf8Str, Bstr no longer differentiates
+ *  between NULL strings and empty strings. In other words, Bstr("") and
+ *  Bstr(NULL) behave the same. In both cases, Bstr allocates no memory,
+ *  reports a zero length and zero allocated bytes for both, and returns an
+ *  empty C wide string from raw().
  */
 class Bstr
@@ -75 +92 @@
 public:
 
-    typedef BSTR String;
-    typedef CBSTR ConstString;
-
-    Bstr() : bstr(NULL) {}
-
-    Bstr(const Bstr &that) : bstr(NULL) { raw_copy(bstr, that.bstr); }
-    Bstr(CBSTR that) : bstr(NULL) { raw_copy(bstr, that); }
+    /**
+     * Creates an empty string that has no memory allocated.
+     */
+    Bstr()
+        : m_bstr(NULL)
+    {
+    }
+
+    /**
+     * Creates a copy of another Bstr.
+     *
+     * This allocates s.length() + 1 wide characters for the new instance, unless s is empty.
+     *
+     * @param   s               The source string.
+     *
+     * @throws  std::bad_alloc
+     */
+    Bstr(const Bstr &s)
+    {
+        copyFrom(s);
+    }
+
+    /**
+     * Creates a copy of a wide char string buffer.
+     *
+     * This allocates SysStringLen(pw) + 1 wide characters for the new instance, unless s is empty.
+     *
+     * @param   pcsz            The source string.
+     *
+     * @throws  std::bad_alloc
+     */
+    Bstr(CBSTR pw)
+    {
+        copyFrom(pw);
+    }
 
 #if defined (VBOX_WITH_XPCOM)
-    Bstr(const wchar_t *that) : bstr(NULL)
+    Bstr(const wchar_t *pw)
     {
         AssertCompile(sizeof(wchar_t) == sizeof(OLECHAR));
-        raw_copy(bstr, (CBSTR)that);
+        copyFrom((CBSTR)pw);
     }
 #endif
 
-    Bstr(const iprt::MiniString &that);
-    Bstr(const char *that);
-
-    /** Shortcut that calls #alloc(aSize) right after object creation. */
-    Bstr(size_t aSize) : bstr(NULL) { alloc(aSize); }
-
-    ~Bstr() { setNull(); }
-
-    Bstr &operator=(const Bstr &that) { safe_assign(that.bstr); return *this; }
-    Bstr &operator=(CBSTR that) { safe_assign(that); return *this; }
-
-    Bstr &operator=(const Utf8Str &that);
-    Bstr &operator=(const char *that);
-
-    Bstr &setNull()
-    {
-        if (bstr)
-        {
-            ::SysFreeString(bstr);
-            bstr = NULL;
-        }
-        return *this;
-    }
-
-    Bstr &setNullIfEmpty()
-    {
-        if (bstr && *bstr == 0)
-        {
-            ::SysFreeString(bstr);
-            bstr = NULL;
-        }
-        return *this;
-    }
-
-    /**
-     *  Allocates memory for a string capable to store \a aSize - 1 characters;
-     *  in other words, aSize includes the terminating zero character. If \a aSize
-     *  is zero, or if a memory allocation error occurs, this object will become null.
-     */
-    Bstr &alloc(size_t aSize)
-    {
-        setNull();
-        if (aSize)
-        {
-            unsigned int size = (unsigned int) aSize; Assert(size == aSize);
-            bstr = ::SysAllocStringLen(NULL, size - 1);
-            if (bstr)
-                bstr[0] = 0;
-        }
-        return *this;
-    }
-
-    int compare(CBSTR str) const
-    {
-        return ::RTUtf16Cmp((PRTUTF16) bstr, (PRTUTF16) str);
-    }
-
-    int compare(BSTR str) const
-    {
-        return ::RTUtf16Cmp((PRTUTF16) bstr, (PRTUTF16) str);
-    }
-
-    bool operator==(const Bstr &that) const { return !compare(that.bstr); }
-    bool operator!=(const Bstr &that) const { return !!compare(that.bstr); }
+
+    /**
+     * Creates a copy of an IPRT MiniString (which includes Utf8Str).
+     *
+     * This allocates s.length() + 1 wide characters for the new instance, unless s is empty.
+     *
+     * @param   pcsz            The source string.
+     *
+     * @throws  std::bad_alloc
+     */
+    Bstr(const iprt::MiniString &s)
+    {
+        copyFrom(s.c_str());        // @todo the source string length is know, we can probably speed this up
+    }
+
+    /**
+     * Creates a copy of a C string.
+     *
+     * This allocates strlen(pcsz) + 1 bytes for the new instance, unless s is empty.
+     *
+     * @param   pcsz            The source string.
+     *
+     * @throws  std::bad_alloc
+     */
+    Bstr(const char *pcsz)
+    {
+        copyFrom(pcsz);
+    }
+
+    /**
+     * String length in wide characters.
+     *
+     * Returns the length of the member string, which is equal to SysStringLen(raw()).
+     * In other words, this returns neither bytes nor the number of unicode codepoints.
+     *
+     * As opposed to Utf8Str::length(), this is _not_ cached and expensive.
+     */
+    size_t length() const
+    {
+        return ::SysStringLen(m_bstr);
+    }
+
+    /**
+     * Deallocates all memory.
+     */
+    inline void setNull()
+    {
+        cleanup();
+    }
+
+    /**
+     * Returns a const pointer to the member string. If the member string is empty,
+     * returns a pointer to a static null character.
+     * @return
+     */
+    CBSTR raw() const
+    {
+        return (m_bstr) ? m_bstr : (CBSTR)L"";
+    }
+
+    /**
+     * Empty string or not?
+     *
+     * Returns true if the member string has no length.
+     *
+     * @returns true if empty, false if not.
+     */
+    bool isEmpty() const
+    {
+        return (m_bstr == NULL);
+    }
+
+    operator bool() const
+    {
+        return !isEmpty();
+    }
+
+    bool operator!() const
+    {
+        return isEmpty();
+    }
+
+    /** Case sensitivity selector. */
+    enum CaseSensitivity
+    {
+        CaseSensitive,
+        CaseInsensitive
+    };
+
+    int compare(CBSTR str, CaseSensitivity cs = CaseSensitive) const
+    {
+        if (m_bstr == str)
+            return 0;
+        if (m_bstr == NULL)
+            return -1;
+        if (str == NULL)
+            return 1;
+
+        if (cs == CaseSensitive)
+            return ::RTUtf16Cmp((PRTUTF16)m_bstr, (PRTUTF16)str);
+        else
+            return ::RTUtf16ICmp((PRTUTF16)m_bstr, (PRTUTF16)str);
+    }
+
+    int compare(const Bstr &bstr, CaseSensitivity cs = CaseSensitive) const
+    {
+        return compare(bstr.raw(), cs);
+    }
+
+    /** @name Comparison operators.
+     * @{  */
+    bool operator==(const Bstr &that) const { return !compare(that.raw()); }
+    bool operator!=(const Bstr &that) const { return !!compare(that.raw()); }
+    bool operator<( const Bstr &that) const { return compare(that.raw()) < 0; }
+    bool operator>( const Bstr &that) const { return compare(that.raw()) > 0; }
+
     bool operator==(CBSTR that) const { return !compare(that); }
-    bool operator==(BSTR that) const { return !compare(that); }
-
-#if defined (VBOX_WITH_XPCOM)
-    bool operator!=(const wchar_t *that) const
-    {
-        AssertCompile(sizeof(wchar_t) == sizeof(OLECHAR));
-        return !!compare((CBSTR) that);
-    }
-    bool operator==(const wchar_t *that) const
-    {
-        AssertCompile(sizeof(wchar_t) == sizeof(OLECHAR));
-        return !compare((CBSTR) that);
-    }
-#endif
-
     bool operator!=(CBSTR that) const { return !!compare(that); }
-    bool operator!=(BSTR that) const { return !!compare(that); }
-    bool operator<(const Bstr &that) const { return compare(that.bstr) < 0; }
-    bool operator<(CBSTR that) const { return compare(that) < 0; }
-    bool operator<(BSTR that) const { return compare(that) < 0; }
-#if defined (VBOX_WITH_XPCOM)
-    bool operator<(const wchar_t *that) const
-    {
-        AssertCompile(sizeof(wchar_t) == sizeof(OLECHAR));
-        return compare((CBSTR) that) < 0;
-    }
-#endif
-
-    int compareIgnoreCase(CBSTR str) const
-    {
-        return ::RTUtf16LocaleICmp(bstr, str);
-    }
-
-    bool isNull() const { return bstr == NULL; }
-    operator bool() const { return !isNull(); }
-
-    bool isEmpty() const { return isNull() || *bstr == 0; }
-
-    size_t length() const { return isNull() ? 0 : ::RTUtf16Len((PRTUTF16) bstr); }
+    bool operator<( CBSTR that) const { return compare(that) < 0; }
+    bool operator>( CBSTR that) const { return compare(that) > 0; }
+
+    // the following two are necessary or stupid MSVC will complain with "ambiguous operator=="
+    bool operator==( BSTR that) const { return !compare(that); }
+    bool operator!=( BSTR that) const { return !!compare(that); }
+
+    /** @} */
 
     /** Intended to to pass instances as |CBSTR| input parameters to methods. */
-    operator CBSTR() const { return bstr; }
+    operator CBSTR() const { return raw(); }
 
     /**
@@ -204 +271 @@
      * input BSTR parameters of interface methods are not const.
      */
-    operator BSTR() { return bstr; }
-
-    /**
-     *  The same as operator CBSTR(), but for situations where the compiler
-     *  cannot typecast implicitly (for example, in printf() argument list).
-     */
-    CBSTR raw() const { return bstr; }
-
-    /**
-     *  Returns a non-const raw pointer that allows to modify the string directly.
-     *  @warning
-     *      Be sure not to modify data beyond the allocated memory! The
-     *      guaranteed size of the allocated memory is at least #length()
-     *      bytes after creation and after every assignment operation.
-     */
-    BSTR mutableRaw() { return bstr; }
+    operator BSTR() { return (BSTR)raw(); }
 
     /**
@@ -225 +277 @@
      *  within the interface method. Transfers the ownership of the duplicated
      *  string to the caller.
-     */
-    const Bstr &cloneTo(BSTR *pstr) const
+     *
+     *  This allocates a single 0 byte in the target if the member string is empty.
+     */
+    const Bstr& cloneTo(BSTR *pstr) const
     {
         if (pstr)
-        {
-            *pstr = NULL;
-            raw_copy(*pstr, bstr);
-        }
+            *pstr = ::SysAllocString((const OLECHAR*)raw());
+                    // raw() never returns NULL, so we always allocate something here
         return *this;
     }
@@ -243 +295 @@
      *  As opposed to cloneTo(), this method doesn't create a copy of the
      *  string.
-     */
-    Bstr &detachTo(BSTR *pstr)
-    {
-        *pstr = bstr;
-        bstr = NULL;
+     *
+     *  This allocates a single 0 byte in the target if the member string is empty.
+     */
+    Bstr& detachTo(BSTR *pstr)
+    {
+        *pstr = (m_bstr) ? m_bstr : ::SysAllocString((const OLECHAR*)"");
+        m_bstr = NULL;
         return *this;
     }
-
-    /**
-     *  Intended to assign copies of instances to |char *| out parameters from
-     *  within the interface method. Transfers the ownership of the duplicated
-     *  string to the caller.
-     */
-    const Bstr &cloneTo(char **pstr) const;
 
     /**
@@ -262 +309 @@
      *  Takes the ownership of the returned data.
      */
-    BSTR *asOutParam() { setNull(); return &bstr; }
+    BSTR* asOutParam()
+    {
+        cleanup();
+        return &m_bstr;
+    }
 
     /**
@@ -271 +322 @@
 protected:
 
-    void safe_assign(CBSTR str)
-    {
-        if (bstr != str)
+    /**
+     * Destructor implementation, also used to clean up in operator=() before
+     * assigning a new string.
+     */
+    void cleanup()
+    {
+        if (m_bstr)
         {
-            setNull();
-            raw_copy(bstr, str);
+            ::SysFreeString(m_bstr);
+            m_bstr = NULL;
         }
     }
 
-    inline static void raw_copy(BSTR &ls, CBSTR rs)
-    {
-        if (rs)
-            ls = ::SysAllocString((const OLECHAR *) rs);
-    }
-
-    inline static void raw_copy(BSTR &ls, const char *rs)
-    {
-        if (rs)
+    /**
+     *  Protected internal helper which allocates memory for a string capable of
+     *  storing \a aSize - 1 characters (not bytes, not codepoints); in other words,
+     *  aSize includes the terminating null character.
+     *
+     *  Does NOT call cleanup() before allocating!
+     *
+     * @throws  std::bad_alloc  On allocation failure. The object is left describing
+     *             a NULL string.
+     */
+    void alloc(size_t cw)
+    {
+        if (cw)
         {
+            m_bstr = ::SysAllocStringLen(NULL, (unsigned int)cw - 1);
+#ifdef RT_EXCEPTIONS_ENABLED
+            if (!m_bstr)
+                throw std::bad_alloc();
+#endif
+        }
+    }
+
+    /**
+     * Protected internal helper to copy a string, ignoring the previous object state.
+     *
+     * copyFrom() unconditionally sets the members to a copy of the given other
+     * strings and makes no assumptions about previous contents. Can therefore be
+     * used both in copy constructors, when member variables have no defined value,
+     * and in assignments after having called cleanup().
+     *
+     * This variant copies from another Bstr. Since Bstr does _not_ cache string lengths,
+     * this is not fast.
+     *
+     * @param   s               The source string.
+     *
+     * @throws  std::bad_alloc  On allocation failure. The object is left describing
+     *             a NULL string.
+     */
+    void copyFrom(const Bstr &s)
+    {
+        copyFrom(s.raw());
+    }
+
+    /**
+     * Protected internal helper to copy a string, ignoring the previous object state.
+     *
+     * See copyFrom() above.
+     *
+     * This variant copies from a wide char C string.
+     *
+     * @param   pcsz            The source string.
+     *
+     * @throws  std::bad_alloc  On allocation failure. The object is left describing
+     *             a NULL string.
+     */
+    void copyFrom(CBSTR pw)
+    {
+        size_t cwLength;
+        if (    (pw)
+             && ((cwLength = ::SysStringLen((BSTR)pw)))
+           )
+        {
+            size_t cwAllocated = cwLength + 1;
+            alloc(cwAllocated);
+            memcpy(m_bstr, pw, cwAllocated * sizeof(OLECHAR));     // include 0 terminator
+        }
+        else
+            m_bstr = NULL;
+    }
+
+    /**
+     * Protected internal helper to copy a string, ignoring the previous object state.
+     *
+     * See copyFrom() above.
+     *
+     * This variant converts from a Utf-8 C string.
+     *
+     * @param   pcsz            The source string.
+     *
+     * @throws  std::bad_alloc  On allocation failure. The object is left describing
+     *             a NULL string.
+     */
+    void copyFrom(const char *pcsz)
+    {
+        if (pcsz && *pcsz)
+        {
+            // @todo r=dj apparently this was copied twice in the original because our buffers
+            // use memory from SysAllocMem and IPRT doesn't, but check if this can be made faster
             PRTUTF16 s = NULL;
-            ::RTStrToUtf16(rs, &s);
-            raw_copy(ls, (BSTR)s);
+            ::RTStrToUtf16(pcsz, &s);
+            copyFrom((BSTR)s);              // @todo r=dj this is not exception safe
             ::RTUtf16Free(s);
         }
-    }
-
-    BSTR bstr;
-
-    friend class Utf8Str; /* to access our raw_copy() */
+        else
+            m_bstr = NULL;
+    }
+
+    BSTR    m_bstr;                     /**< The string buffer. */
 };
 
 /* symmetric compare operators */
-inline bool operator==(CBSTR l, const Bstr &r) { return r.operator==(l); }
-inline bool operator!=(CBSTR l, const Bstr &r) { return r.operator!=(l); }
-inline bool operator==(BSTR l, const Bstr &r) { return r.operator==(l); }
-inline bool operator!=(BSTR l, const Bstr &r) { return r.operator!=(l); }
+// inline bool operator==(CBSTR l, const Bstr &r) { return r.operator==(l); }
+// inline bool operator!=(CBSTR l, const Bstr &r) { return r.operator!=(l); }
+// inline bool operator==(BSTR l, const Bstr &r) { return r.operator==(l); }
+// inline bool operator!=(BSTR l, const Bstr &r) { return r.operator!=(l); }
 
 ////////////////////////////////////////////////////////////////////////////////
 
 /**
- *  Helper class that represents UTF8 (|char *|) strings. Useful in
- *  conjunction with Bstr to simplify conversions between UTF16 (|BSTR|)
- *  and UTF8.
- *
- *  This class uses COM/XPCOM-provided memory management routines to allocate
- *  and free string buffers. This makes it possible to:
- *  - use it as a type of member variables of COM/XPCOM components and pass
- *    their values to callers through component methods' output parameters
- *    using the #cloneTo() operation;
- *  - adopt (take ownership of) string buffers returned in output parameters
- *    of COM methods using the #asOutParam() operation and correctly free them
- *    afterwards.
+ *  String class used universally in Main for Utf-8 strings.
+ *
+ *  This is based on iprt::MiniString, to which some functionality has been
+ *  moved. Here we keep things that are specific to Main, such as conversions
+ *  with UTF-16 strings (Bstr).
+ *
+ *  Like iprt::MiniString, Utf8Str does not differentiate between NULL strings
+ *  and empty strings. In other words, Utf8Str("") and Utf8Str(NULL)
+ *  behave the same. In both cases, MiniString allocates no memory, reports
+ *  a zero length and zero allocated bytes for both, and returns an empty
+ *  C string from c_str().
  */
 class Utf8Str : public iprt::MiniString
@@ -340 +472 @@
     Utf8Str(const Bstr &that)
     {
-        copyFrom(that);
+        copyFrom(that.raw());
     }
 
@@ -361 +493 @@
 
     Utf8Str& operator=(const Bstr &that)
+    {
+        cleanup();
+        copyFrom(that.raw());
+        return *this;
+    }
+
+    Utf8Str& operator=(CBSTR that)
     {
         cleanup();
@@ -367 +506 @@
     }
 
-    Utf8Str& operator=(CBSTR that)
-    {
-        cleanup();
-        copyFrom(that);
-        return *this;
-    }
-
     /**
      * Intended to assign instances to |char *| out parameters from within the
@@ -379 +511 @@
      * caller.
      *
+     * This allocates a single 0 byte in the target if the member string is empty.
+     *
      * @remarks The returned string must be freed by RTStrFree, not RTMemFree.
      */
     const Utf8Str& cloneTo(char **pstr) const
     {
-        if (pstr) /** @todo r=bird: This needs to if m_psz is NULL. Shouldn't it also throw std::bad_alloc? */
-            *pstr = RTStrDup(m_psz);
-        return *this;
-    }
-
-    /**
-     *  Intended to assign instances to |char *| out parameters from within the
-     *  interface method. Transfers the ownership of the original string to the
-     *  caller and resets the instance to null.
-     *
-     *  As opposed to cloneTo(), this method doesn't create a copy of the
-     *  string.
-     */
-    Utf8Str& detachTo(char **pstr)
-    {
-        *pstr = m_psz;
-        m_psz = NULL;
-        m_cbAllocated = 0;
-        m_cbLength = 0;
+        if (pstr)
+        {
+            *pstr = RTStrDup(raw());
+#ifdef RT_EXCEPTIONS_ENABLED
+            if (!*pstr)
+                throw std::bad_alloc();
+#endif
+        }
         return *this;
     }
@@ -409 +532 @@
      *  interface method. Transfers the ownership of the duplicated string to the
      *  caller.
+     *
+     *  This allocates a single 0 byte in the target if the member string is empty.
      */
     const Utf8Str& cloneTo(BSTR *pstr) const
@@ -414 +539 @@
         if (pstr)
         {
+            Bstr bstr(c_str());
             *pstr = NULL;
-            Bstr::raw_copy(*pstr, m_psz);
+            bstr.detachTo(pstr);
         }
         return *this;
@@ -507 +633 @@
         if (s)
         {
-            RTUtf16ToUtf8((PRTUTF16)s, &m_psz); /** @todo r=bird: This isn't throwing std::bad_alloc / handling return codes.
-                                                 * Also, this technically requires using RTStrFree, ministring::cleanup() uses RTMemFree. */
+            RTUtf16ToUtf8((PRTUTF16)s, &m_psz); /** @todo r=bird: This technically requires using RTStrFree, ministring::cleanup() uses RTMemFree. */
+#ifdef RT_EXCEPTIONS_ENABLED
+            if (!m_psz)
+                throw std::bad_alloc();
+#endif
             m_cbLength = strlen(m_psz);         /** @todo optimize by using a different RTUtf* function */
             m_cbAllocated = m_cbLength + 1;
@@ -524 +653 @@
 
 // work around error C2593 of the stupid MSVC 7.x ambiguity resolver
-WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP(Bstr)
-
-////////////////////////////////////////////////////////////////////////////////
-
-// inlined Bstr members that depend on Utf8Str
-
-inline Bstr::Bstr(const iprt::MiniString &that)
-    : bstr(NULL)
-{
-    raw_copy(bstr, that.c_str());
-}
-
-inline Bstr::Bstr(const char *that)
-    : bstr(NULL)
-{
-    raw_copy(bstr, that);
-}
-
-inline Bstr &Bstr::operator=(const Utf8Str &that)
-{
-    setNull();
-    raw_copy(bstr, that.c_str());
-    return *this;
-}
-inline Bstr &Bstr::operator=(const char *that)
-{
-    setNull();
-    raw_copy(bstr, that);
-    return *this;
-}
-
-inline const Bstr& Bstr::cloneTo(char **pstr) const
-{
-    if (pstr)
-    {
-        Utf8Str ustr(*this);
-        ustr.detachTo(pstr);
-    }
-    return *this;
-}
+// @todo r=dj if I enable this I get about five warnings every time this header
+// is included, figure out what that is... for now I have modified the calling code instead
+// WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP(Bstr)
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -654 +746 @@
         va_list args;
         va_start(args, aFormat);
-        raw_copy(bstr, Utf8StrFmtVA(aFormat, args).c_str());
+        copyFrom(Utf8StrFmtVA(aFormat, args).c_str());
         va_end(args);
     }
@@ -675 +767 @@
     BstrFmtVA(const char *aFormat, va_list aArgs)
     {
-        raw_copy(bstr, Utf8StrFmtVA(aFormat, aArgs).c_str());
+        copyFrom(Utf8StrFmtVA(aFormat, aArgs).c_str());
     }
 };

trunk/include/iprt/cdefs.h

@@ -1920 +1920 @@
 #if defined(_MSC_VER)
 # define WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP(Cls) \
-    inline bool operator! (const Cls &that) { return !bool (that); } \
-    inline bool operator&& (const Cls &that, bool b) { return bool (that) && b; } \
-    inline bool operator|| (const Cls &that, bool b) { return bool (that) || b; } \
-    inline bool operator&& (bool b, const Cls &that) { return b && bool (that); } \
-    inline bool operator|| (bool b, const Cls &that) { return b || bool (that); }
+    inline bool operator! (const Cls &that) { return !bool(that); } \
+    inline bool operator&& (const Cls &that, bool b) { return bool(that) && b; } \
+    inline bool operator|| (const Cls &that, bool b) { return bool(that) || b; } \
+    inline bool operator&& (bool b, const Cls &that) { return b && bool(that); } \
+    inline bool operator|| (bool b, const Cls &that) { return b || bool(that); }
 #else
 # define WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP(Cls)

trunk/include/iprt/cpp/ministring.h

@@ -45 +45 @@
  * else except IPRT memory management functions.  Semantics are like in
  * std::string, except it can do a lot less.
+ *
+ * Note that MiniString does not differentiate between NULL strings and
+ * empty strings. In other words, MiniString("") and MiniString(NULL)
+ * behave the same. In both cases, MiniString allocates no memory, reports
+ * a zero length and zero allocated bytes for both, and returns an empty
+ * C string from c_str().
  */
 #ifdef VBOX
@@ -71 +77 @@
      * Creates a copy of another MiniString.
      *
-     * This allocates s.length() + 1 bytes for the new instance.
+     * This allocates s.length() + 1 bytes for the new instance, unless s is empty.
      *
      * @param   s               The source string.
@@ -83 +89 @@
 
     /**
-     * Creates a copy of another MiniString.
-     *
-     * This allocates strlen(pcsz) + 1 bytes for the new instance.
+     * Creates a copy of a C string.
+     *
+     * This allocates strlen(pcsz) + 1 bytes for the new instance, unless s is empty.
      *
      * @param   pcsz            The source string.
@@ -123 +129 @@
      *
      * Returns the number of bytes allocated in the internal string buffer, which is
-     * at least length() + 1 if length() > 0.
+     * at least length() + 1 if length() > 0. Returns 0 for an empty string.
      *
      * @returns m_cbAllocated.
@@ -275 +281 @@
      * Returns the byte at the given index, or a null byte if the index is not
      * smaller than length().  This does _not_ count codepoints but simply points
-     * into the member C string.
+     * into the member C string; the result may not be a valid UTF-8 character.
      *
      * @param   i       The index into the string buffer.
@@ -289 +295 @@
     /**
      * Returns the contained string as a C-style const char* pointer.
+     * This never returns NULL; if the string is empty, returns a
+     * pointer to static null byte.
      *
      * @returns const pointer to C-style string.
@@ -294 +302 @@
     inline const char *c_str() const
     {
-        return m_psz;
+        return (m_psz) ? m_psz : "";
     }
 
     /**
      * Like c_str(), for compatibility with lots of VirtualBox Main code.
+     * This never returns NULL; if the string is empty, returns a
+     * pointer to static null byte.
      *
      * @returns const pointer to C-style string.
@@ -304 +314 @@
     inline const char *raw() const
     {
-        return m_psz;
-    }
-
-    /**
-     * Emptry string or not?
+        return (m_psz) ? m_psz : "";
+    }
+
+    /**
+     * Empty string or not?
      *
      * Returns true if the member string has no length.  This states nothing about
@@ -472 +482 @@
 
     /**
-     * Hide operator bool() to force people to use isEmpty() explicitly.
-     */
-    operator bool() const { return false; }
-
-    /**
      * Destructor implementation, also used to clean up in operator=() before
      * assigning a new string.
@@ -492 +497 @@
 
     /**
-     * Protected internal helper for copy a string that completely ignors the
-     * current object state.
+     * Protected internal helper to copy a string, ignoring the previous object state.
      *
      * copyFrom() unconditionally sets the members to a copy of the given other
@@ -501 +505 @@
      *
      * This variant copies from another MiniString and is fast since
-     * the length of source string is known.
+     * the length of the source string is known.
      *
      * @param   s               The source string.
@@ -533 +537 @@
 
     /**
-     * Protected internal helper for copy a string that completely ignors the
-     * current object state.
+     * Protected internal helper to copy a string, ignoring the previous object state.
      *
      * See copyFrom() above.
@@ -572 +575 @@
     }
 
+private:
+
+    /**
+     * Hide operator bool() to force people to use isEmpty() explicitly.
+     */
+    operator bool() const;
+
+protected:
+
     char    *m_psz;                     /**< The string buffer. */
     size_t  m_cbLength;                 /**< strlen(m_psz) - i.e. no terminator included. */