Changeset 21358 in vbox for trunk/include

Timestamp:

Jul 7, 2009 4:19:32 PM (16 years ago)

Author:

vboxsync

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

49707

Message:

IPRT: ministring crash fix + documentation

File:

• trunk/include/iprt/ministring_cpp.h (modified) (19 diffs)

trunk/include/iprt/ministring_cpp.h

@@ -43 +43 @@
  *  Semantics are like in std::string, except it can do a lot less.
  *
- *  Much of the code in here used to be in Utf8Str so that Utf8Str can now
- *  derive from ministring and only contain code that is COM-specific, such
- *  as com::Bstr conversions. Compared to the old Utf8Str though, ministring
+ *  Much of the code in here used to be in com::Utf8Str so that com::Utf8Str
+ *  can now derive from ministring and only contain code that is COM-specific,
+ *  such as com::Bstr conversions. Compared to the old Utf8Str though, ministring
  *  always knows the length of its member string and the size of the buffer
  *  so it can use memcpy() instead of strdup().
@@ -53 +53 @@
 {
 public:
+    /**
+     * Creates an empty string that has no memory allocated.
+     */
     ministring()
         : m_psz(NULL),
@@ -60 +63 @@
     }
 
+    /**
+     * Creates a copy of another ministring. This allocates
+     * s.length() + 1 bytes for the new instance.
+     * @param s
+     */
     ministring(const ministring &s)
     {
@@ -65 +73 @@
     }
 
+    /**
+     * Creates a copy of another ministring. This allocates
+     * strlen(pcsz) + 1 bytes for the new instance.
+     * @param pcsz
+     */
     ministring(const char *pcsz)
     {
@@ -70 +83 @@
     }
 
+    /**
+     * Destructor.
+     */
     virtual ~ministring()
     {
@@ -75 +91 @@
     }
 
+    /**
+     * Returns the length of the member string. This is always cached
+     * so calling this is cheap and requires no strlen() invocation.
+     * @return
+     */
     size_t length() const
     {
@@ -81 +102 @@
 
     /**
-     * Returns the no. of bytes allocated in the internal string buffer,
-     * which is at least m_cbLength + 1 if m_cbLength != 0.
+     * Returns the number of bytes allocated in the internal string buffer,
+     * which is at least length() + 1 if length() > 0.
      * @return
      */
@@ -93 +114 @@
      * Requests that the contained memory buffer have at least cb bytes allocated.
      * This may expand or shrink the string's storage, but will never truncate the
-     * contained string.
+     * contained string. In other words, cb will be ignored if it's smaller than
+     * length() + 1.
      * @param cb new minimum size of member memory buffer
      */
@@ -107 +129 @@
     }
 
+    /**
+     * Deallocates all memory.
+     */
     inline void setNull()
     {
@@ -146 +171 @@
     }
 
+    /**
+     * Assigns a copy of pcsz to "this".
+     * @param pcsz
+     * @return
+     */
     ministring& operator=(const char *pcsz)
     {
@@ -156 +186 @@
     }
 
+    /**
+     * Assigns a copy of s to "this".
+     * @param s
+     * @return
+     */
     ministring& operator=(const ministring &s)
     {
@@ -166 +201 @@
     }
 
+    /**
+     * Appends a copy of @a that to "this".
+     * @param that
+     */
     void append(const ministring &that)
     {
@@ -184 +223 @@
     }
 
+    /**
+     * Returns the contained string as a C-style const char* pointer.
+     * @return
+     */
     inline const char* c_str() const
     {
@@ -189 +232 @@
     }
 
+    /**
+     * Like c_str(), for compatibility with lots of VirtualBox Main code.
+     * @return
+     */
     inline const char* raw() const
     {
@@ -200 +247 @@
     }
 
+    /**
+     * Returns true if the member string has no length. This states nothing about
+     * how much memory might be allocated.
+     * @return
+     */
     bool isEmpty() const
     {
@@ -205 +257 @@
     }
 
+    /**
+     * Returns true if no memory is currently allocated.
+     * @return
+     */
     bool isNull() const
     {
@@ -216 +272 @@
     };
 
+    /**
+     * Compares the member string to pcsz.
+     * @param pcsz
+     * @param cs Whether comparison should be case-sensitive.
+     * @return
+     */
     int compare(const char *pcsz, CaseSensitivity cs = CaseSensitive) const
     {
@@ -265 +327 @@
 
     /**
+     * Protected internal helper.
      * copyFrom() unconditionally sets the members to a copy of the
      * given other strings and makes no assumptions about previous
@@ -278 +341 @@
     void copyFrom(const ministring &s)
     {
-        m_cbLength = s.m_cbLength;
-        m_cbAllocated = m_cbLength + 1;
-        m_psz = (char*)RTMemAlloc(m_cbAllocated);
-        memcpy(m_psz, s.m_psz, m_cbAllocated);      // include 0 terminator
-    }
-
-    /**
+        if ((m_cbLength = s.m_cbLength))
+        {
+            m_cbAllocated = m_cbLength + 1;
+            m_psz = (char*)RTMemAlloc(m_cbAllocated);
+            memcpy(m_psz, s.m_psz, m_cbAllocated);      // include 0 terminator
+        }
+        else
+        {
+            m_cbAllocated = 0;
+            m_psz = NULL;
+        }
+    }
+
+    /**
+     * Protected internal helper.
      * See copyFrom() above.
      *