More docs. And test put_filter

include/ucore/dstr.h

@@ -7,11 +7,15 @@
 extern "C" {
 #endif
 
-/** A dynamically managed C-string.
+/** A managed C-string, using dynalically allocated memory for the string.
  *
  * The .str member might not always be nul terminated,
  * Normally, use uc_dstr_str() to retreive the managed string
  * instead of accessing ->str directly.
+ *
+ * Normally, let the DSTR manage the nul terminator as  manually adding 
+ * a nul byte and potintially adding more data to the DStr would append 
+ * it after that nul terminator.
  */
 struct DStr {
     /** Length of the managed string.*/
@@ -31,12 +35,12 @@ struct DStr {
 void uc_dstr_init(struct DStr *str);
 
 /** Destroy/free the string. 
- * (Does not free str itself, only the managed resource of the str)
+ * (Frees str->str, not str itself)
  */
 void uc_dstr_destroy(struct DStr *str);
 
 /**
- * @return the available/unused tail bytes in the string
+ * @return the available/unused tail bytes in the string.
  */
 size_t uc_dstr_available(const struct DStr *str);
 
@@ -60,7 +64,7 @@ void uc_dstr_terminate(struct DStr *str);
  */
 char *uc_dstr_str(struct DStr *str);
 
-/** reserve len bytes for appending to the dstr
+/** Reserve len bytes for appending to the dstr
  *  you must fill in a string in the 0-len range of
  *  the returned pointer.
  *
@@ -90,16 +94,18 @@ int uc_dstr_put_str_sz(struct DStr *str, const char *s, size_t len);
 
 /* Append a string.
  * (The nul terminator is not appended) 
+ *
  *  @return 0 on success (!= 0 if an allocation fail)
  */
 int uc_dstr_put_str(struct DStr *str, const char *s);
 
 /* Append a single char.
+ *
  *  @return 0 on success (!= 0 if an allocation fail)
  */
 int uc_dstr_put_char(struct DStr *str, char c);
 
-/* Make the DStr take ownership of the give dynamically allocated string.
+/* Make the DStr take ownership of the given dynamically allocated string.
  * Any existing string in the DStr is freed.
  */
 void uc_dstr_own(struct DStr *str, char *s);
@@ -112,10 +118,11 @@ void uc_dstr_own(struct DStr *str, char *s);
  */
 char *uc_dstr_steal(struct DStr *str);
 
-/** Swap the A and B dstr */
+/** Swap the A and B DStr */
 void uc_str_swap(struct DStr *a, struct DStr *b);
 
 /** Replace all occurences in the DStr
+ * (This may be used to replace any embedded nul bytes too)
  *
  * @param f char to find
  * @param r char to replace with

test/test_dstr.c

@@ -1,4 +1,5 @@
 #include <check.h>
+#include <ctype.h>
 #include <ucore/dstr.h>
 #include <ucore/utils.h>
 
@@ -107,6 +108,21 @@ START_TEST (test_dstr_replace)
 
 END_TEST
 
+START_TEST (test_dstr_filter)
+    struct DStr str;
+    size_t rc; 
+
+    uc_dstr_init(&str);
+    uc_dstr_put_str(&str, "AB:");
+    rc = uc_dstr_put_str_filter(&str, "1:2,3 4 ", isdigit);
+    ck_assert_int_eq(rc, 4);
+    
+    ck_assert_str_eq(uc_dstr_str(&str), "AB:1234");
+
+    uc_dstr_destroy(&str);
+
+END_TEST
+
 Suite *dstr_suite(void)
 {
     Suite *s = suite_create("dstr");
@@ -115,6 +131,7 @@ Suite *dstr_suite(void)
     tcase_add_test(tc, test_dstr_own_steal);
     tcase_add_test(tc, test_dstr_trim);
     tcase_add_test(tc, test_dstr_replace);
+    tcase_add_test(tc, test_dstr_filter);
 
     suite_add_tcase(s, tc);