iprt

Timestamp:

Feb 24, 2010 4:24:33 PM (15 years ago)

Author:

vboxsync

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

58004

Message:

Main: Bstr makeover (third 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

File:

: 1 edited

trunk/include/iprt/cpp/ministring.h (modified) (11 diffs)

Legend:

: Unmodified
: Added
: Removed

trunk/include/iprt/cpp/ministring.h

-              r26603
+              r26753
  * 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
 …
      * 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.
 …
     /**
      * 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.
 …
+     *
      * 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; for an empty string, this returns 0.
+     *
      * @returns m_cbAllocated.
 …
     /**
+     * Assigns a copy of pcsz to "this".
+     *
+     * @param   pcsz            The source string.
+     *
+     * @throws  std::bad_alloc  On allocation failure.  The object is left describing
+     *             a NULL string.
+     *
+     * @returns Reference to the object.
+     */
+    MiniString &operator=(const char *pcsz)
+    {
+        if (m_psz != pcsz)
+        {
+            cleanup();
+            copyFrom(pcsz);
+        }
+        return *this;
+    }
+    /**
+     * Assigns a copy of s to "this".
+     *
+     * @param   s               The source string.
+     *
+     * @throws  std::bad_alloc  On allocation failure.  The object is left describing
+     *             a NULL string.
+     *
+     * @returns Reference to the object.
+     */
+    MiniString &operator=(const MiniString &s)
+    {
+        if (this != &s)
+        {
+            cleanup();
+            copyFrom(s);
+        }
+        return *this;
+    }
+    /**
+     * Appends the string "that" to "this".
+     *
+     * @param   that            The string to append.
+     *
+     * @throws  std::bad_alloc  On allocation error.  The object is left unchanged.
+     *
+     * @returns Reference to the object.
+     */
+    MiniString &append(const MiniString &that);
+    /**
+     * Appends the given character to "this".
+     *
+     * @param   c               The character to append.
+     *
+     * @throws  std::bad_alloc  On allocation error.  The object is left unchanged.
+     *
+     * @returns Reference to the object.
+     */
+    MiniString &append(char c);
+    /**
+     * Index operator.
+     *
+     * 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.
+     *
+     * @param   i       The index into the string buffer.
+     * @returns char at the index or null.
+     */
+    inline char operator[](size_t i) const
+    {
+        if (i < length())
+            return m_psz[i];
+        return '\0';
+    }
+    /**
+     * Returns the contained string as a C-style const char* pointer.
+     * This never returns NULL; if the string is empty, this returns a
+     * pointer to static null byte.
+     *
+     * @returns const pointer to C-style string.
+     */
+    inline const char *c_str() const
+    {
+        return (m_psz) ? m_psz : "";
+    }
+    /**
+     * Like c_str(), for compatibility with lots of VirtualBox Main code.
+     *
+     * @returns const pointer to C-style string.
+     */
+    inline const char *raw() const
+    {
+        return (m_psz) ? m_psz : "";
+    }
+    /**
      * Returns a non-const raw pointer that allows to modify the string directly.
+     * As opposed to c_str() and raw(), this DOES return NULL for an empty string
+     * because we cannot return a non-const pointer to a static "" global.
+     *
      * @warning
 …
     /**
+     * Assigns a copy of pcsz to "this".
+     *
+     * @param   pcsz            The source string.
+     *
+     * @throws  std::bad_alloc  On allocation failure.  The object is left describing
+     *             a NULL string.
+     *
+     * @returns Reference to the object.
+     */
+    MiniString &operator=(const char *pcsz)
+    {
+        if (m_psz != pcsz)
+        {
+            cleanup();
+            copyFrom(pcsz);
+        }
+        return *this;
+    }
+    /**
+     * Assigns a copy of s to "this".
+     *
+     * @param   s               The source string.
+     *
+     * @throws  std::bad_alloc  On allocation failure.  The object is left describing
+     *             a NULL string.
+     *
+     * @returns Reference to the object.
+     */
+    MiniString &operator=(const MiniString &s)
+    {
+        if (this != &s)
+        {
+            cleanup();
+            copyFrom(s);
+        }
+        return *this;
+    }
+    /**
+     * Appends the string "that" to "this".
+     *
+     * @param   that            The string to append.
+     *
+     * @throws  std::bad_alloc  On allocation error.  The object is left unchanged.
+     *
+     * @returns Reference to the object.
+     */
+    MiniString &append(const MiniString &that);
+    /**
+     * Appends the given character to "this".
+     *
+     * @param   c               The character to append.
+     *
+     * @throws  std::bad_alloc  On allocation error.  The object is left unchanged.
+     *
+     * @returns Reference to the object.
+     */
+    MiniString &append(char c);
+    /**
+     * Index operator.
+     *
+     * 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.
+     *
+     * @param   i       The index into the string buffer.
+     * @returns char at the index or null.
+     */
+    inline char operator[](size_t i) const
+    {
+        if (i < length())
+            return m_psz[i];
+        return '\0';
+    }
+    /**
+     * Returns the contained string as a C-style const char* pointer.
+     *
+     * @returns const pointer to C-style string.
+     */
+    inline const char *c_str() const
+    {
+        return m_psz;
+    }
+    /**
+     * Like c_str(), for compatibility with lots of VirtualBox Main code.
+     *
+     * @returns const pointer to C-style string.
+     */
+    inline const char *raw() const
+    {
+        return m_psz;
+    }
+    /**
+     * Emptry string or not?
+     *
+     * Returns true if the member string has no length.  This states nothing about
+     * how much memory might be allocated.
+     * Returns true if the member string has no length.
+     * This is true for instances created from both NULL and "" input strings.
+     *
+     * This states nothing about how much memory might be allocated.
+     *
      * @returns true if empty, false if not.
 …
      * Hide operator bool() to force people to use isEmpty() explicitly.
      */
     operator bool() const { return false; }
+    operator bool() const;
     /**
 …
     /**
      * Protected internal helper for copy a string that completely ignors the
      * current object state.
+     * Protected internal helper to copy a string. This ignores the previous object
+     * state, so either call this from a constructor or call cleanup() first.
+     *
      * copyFrom() unconditionally sets the members to a copy of the given other
 …
+     *
      * 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.
 …
     /**
      * Protected internal helper for copy a string that completely ignors the
      * current object state.
+     * Protected internal helper to copy a string. This ignores the previous object
+     * state, so either call this from a constructor or call cleanup() first.
+     *
      * See copyFrom() above.
 …
     void copyFrom(const char *pcsz)
+    {
         if (pcsz)
+        if (pcsz && *pcsz)
+        {
             m_cbLength = strlen(pcsz);

Note: See TracChangeset for help on using the changeset viewer.

Changeset 26753 in vbox for trunk/include/iprt

Legend:

trunk/include/iprt/cpp/ministring.h

Download in other formats: