[ovs-dev] [PATCH] dynamic-string: Document a few functions.

Ethan Jackson ethan at nicira.com
Fri Feb 24 01:58:07 UTC 2012


This looks good to me.

> + * Copyright (c) 2008, 2009, 2010, 2011, 2012 Nicira Networks.

Completely unrelated to this patch, these things are starting to get
fairly long.  I wonder if it makes sense to gradually start changing
our convention to expressing the years with a dash (e.g. 2008-2012).
Thoughts?

Ethan


>  *
>  * 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
>
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> http://openvswitch.org/mailman/listinfo/dev



More information about the dev mailing list