os: Improve String with more comments and checks.

[apitrace] / common / os_string.hpp

diff --git a/common/os_string.hpp b/common/os_string.hpp
index 35156a101b0f16d74e8af79c5c0c7b1f5aa88c3f..996c6191e2313a7677024f703b05147aeee39651 100644 (file)
--- a/common/os_string.hpp
+++ b/common/os_string.hpp
@@ -68,8 +68,20 @@ namespace os {
 
 
 /**
- * Vector based zero-terminate string, suitable for passing strings or paths
- * to/from OS calls.
+ * Class to represent zero-terminated strings, based upon std::vector<char>,
+ * suitable for passing strings or paths to/from OS calls.
+ *
+ * Both Win32 and POSIX APIs return strings as zero length buffers.  Although
+ * std::string provides an easy method to obtain a read-only pointer to a zero
+ * terminated string, it lacks the ability to return a read-write pointer. So
+ * there is no way to tell OS calls to write into a std::string directly -- a
+ * temporary malloc'ed string would be necessary --, which would be
+ * unnecessarily inefficient, specially considering that these strings would
+ * ultimately passed back to the OS, which would again expect zero-terminated
+ * strings.
+ *
+ * This class is not, however, a full replacement for std::string, which should
+ * be otherwise used whenever possible.
  */
 class String {
 protected:
@@ -312,6 +324,15 @@ public:
         buffer.erase(first, last);
     }
 
+    /**
+     * Get a writable buffer with the specified size.
+     *
+     * truncate() must be called after the buffer is written, and before any other
+     * method is called.
+     *
+     * Between the call to buf() and truncate() methods, the `buffer.back() ==
+     * 0` invariant will not hold true.
+     */
     char *buf(size_t size) {
         buffer.resize(size);
         return &buffer[0];
@@ -324,14 +345,21 @@ public:
         return size - 1;
     }
 
+    /**
+     * Truncate the string to the specified length.
+     */
     void truncate(size_t length) {
         assert(length < buffer.size());
         buffer[length] = 0;
+        assert(strlen(&buffer[0]) == length);
         buffer.resize(length + 1);
     }
 
+    /**
+     * Truncate the string to the first zero character.
+     */
     void truncate(void) {
-        truncate(strlen(str()));
+        truncate(strlen(&buffer[0]));
     }