[ovs-dev] [PATCH] dynamic-string: Document a few functions.
Ben Pfaff
blp at nicira.com
Thu Feb 23 17:00:01 UTC 2012
Signed-off-by: Ben Pfaff <blp at nicira.com>
---
lib/dynamic-string.c | 13 ++++++++++++-
lib/dynamic-string.h | 9 ++++++++-
2 files changed, 20 insertions(+), 2 deletions(-)
diff --git a/lib/dynamic-string.c b/lib/dynamic-string.c
index 8c675d1..8e58302 100644
--- a/lib/dynamic-string.c
+++ b/lib/dynamic-string.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2008, 2009, 2010, 2011 Nicira Networks.
+ * Copyright (c) 2008, 2009, 2010, 2011, 2012 Nicira Networks.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -23,6 +23,7 @@
#include "timeval.h"
#include "util.h"
+/* Initializes 'ds' as an empty string buffer. */
void
ds_init(struct ds *ds)
{
@@ -31,12 +32,16 @@ ds_init(struct ds *ds)
ds->allocated = 0;
}
+/* Sets 'ds''s length to 0, effectively clearing any existing content. Does
+ * not free any memory. */
void
ds_clear(struct ds *ds)
{
ds->length = 0;
}
+/* Reduces 'ds''s length to no more than 'new_length'. (If its length is
+ * already 'new_length' or less, does nothing.) */
void
ds_truncate(struct ds *ds, size_t new_length)
{
@@ -46,6 +51,9 @@ ds_truncate(struct ds *ds, size_t new_length)
}
}
+/* Ensures that at least 'min_length + 1' bytes (including space for a null
+ * terminator) are allocated for ds->string, allocating or reallocating memory
+ * as necessary. */
void
ds_reserve(struct ds *ds, size_t min_length)
{
@@ -56,6 +64,9 @@ ds_reserve(struct ds *ds, size_t min_length)
}
}
+/* Appends space for 'n' bytes to the end of 'ds->string', increasing
+ * 'ds->length' by the same amount, and returns the first appended byte. The
+ * caller should fill in all 'n' bytes starting at the return value. */
char *
ds_put_uninit(struct ds *ds, size_t n)
{
diff --git a/lib/dynamic-string.h b/lib/dynamic-string.h
index 35a0357..a8a27ad 100644
--- a/lib/dynamic-string.h
+++ b/lib/dynamic-string.h
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2008, 2009, 2010, 2011 Nicira Networks.
+ * Copyright (c) 2008, 2009, 2010, 2011, 2012 Nicira Networks.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -26,6 +26,13 @@
struct tm;
+/* A "dynamic string", that is, a buffer that can be used to construct a
+ * string across a series of operations that extend or modify it.
+ *
+ * The 'string' member does not always point to a null-terminated string.
+ * Initially it is NULL, and even when it is nonnull, some operations do not
+ * ensure that it is null-terminated. Use ds_cstr() to ensure that memory is
+ * allocated for the string and that it is null-terminated. */
struct ds {
char *string; /* Null-terminated string. */
size_t length; /* Bytes used, not including null terminator. */
--
1.7.2.5
More information about the dev
mailing list