revise hashvector_contents to optionally create the target vector

[rrq/rrqmisc.git] / vector / hashvector.h

diff --git a/vector/hashvector.h b/vector/hashvector.h
index 2754fb1fc737ed674821e11cd98b43193770434c..b57aede5a0a5e9241993adb6aab4b324c87e4596 100644 (file)
--- a/vector/hashvector.h
+++ b/vector/hashvector.h
@@ -134,16 +134,23 @@ extern int hashvector_delete(hashvector *hv,void *item);
  * 
  * \param hv is the \ref hashvector concerned.
  *
- * \param pv is the \ref vector to copy the content into.
+ * \param variant is the desired vector variant.
  *
- * \returns \b -1 if the required resizing of the \ref vector to the
- * \ref hashvector \b fill fails, otherwise \b 0 after having copied
- * the hashvector items in their internal order of appearance into the
- * \ref vector.
+ * \param pv is the optional \ref vector to copy the content into.
+ *
+ * \returns the \ref vector with the \ref hashvector content
+ *
+ * If \pv is null, then a new vector is allocated and handed out for
+ * the caller to reclaim unless the hashvector is empty in which case
+ * this function returns 0.
+ *
+ * If \b pv is not null, it is first cleared, and then populated with
+ * the content from the hashvector. The populated vector is returned.
  *
  * \related hashvector
  */
-extern int hashvector_contents(hashvector *hv,vector *pv);
+extern vector *hashvector_contents(
+    hashvector *hv,enum vector_variant variant,vector *pv);
 
 /**
  * \brief This is a utility function to compute and return a hashcode