X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=common%2Fos_string.hpp;h=996c6191e2313a7677024f703b05147aeee39651;hb=ad6f60ff31d1cc912e947989afea39d698181ac4;hp=3a8eab688552b1bb39f187bc57fc2981f4e5bd1c;hpb=cbac4128897a0346e66a6cacabf083789ef07f83;p=apitrace

diff --git a/common/os_string.hpp b/common/os_string.hpp
index 3a8eab6..996c619 100644
--- a/common/os_string.hpp
+++ b/common/os_string.hpp
@@ -57,8 +57,10 @@ extern "C" _CRTIMP int _vscprintf(const char *format, va_list argptr);
 
 #ifdef _WIN32
 #define OS_DIR_SEP '\\'
+#define OS_PATH_SEP ';'
 #else /* !_WIN32 */
 #define OS_DIR_SEP '/'
+#define OS_PATH_SEP ':'
 #endif /* !_WIN32 */
 
 
@@ -66,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:
@@ -310,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];
@@ -322,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]));
     }