FEATURE: zerocopy insert into dictionary
For storing text content in dictionary. Parser have to allocate new
strings anyway to translate character/entity references so dictionary
should allow storing these strings into dictionary directly, without
a second copy.
diff --git a/src/dict.h b/src/dict.h
index 627863a..5043033 100644
--- a/src/dict.h
+++ b/src/dict.h
@@ -22,7 +22,44 @@
#ifndef LY_DICT_H_
#define LY_DICT_H_
-char *dict_insert(const char *value, size_t len);
-void dict_remove(const char *value);
+/**
+ * @brief Insert string into dictionary. If the string is already present,
+ * only a reference counter is incremented and no memory allocation is
+ * performed.
+ *
+ * @param[in] value String to be stored in the dictionary.
+ * @param[in] len Number of bytes to store. The value is not required to be
+ * NULL terminated string, the len parameter says number of bytes stored in
+ * dictionary. The specified number of bytes is duplicated and terminating NULL
+ * byte is added automatically.
+ * @return pointer to the string stored in the dictionary
+ */
+char *lydict_insert(const char *value, size_t len);
+
+/**
+ * @brief Insert string into dictionary - zerocopy version. If the string is
+ * already present, only a reference counter is incremented and no memory
+ * allocation is performed. This insert function variant avoids duplication of
+ * specified value - it is inserted into the dictionary directly.
+ *
+ * @param[in] value NULL-terminated string to be stored in the dictionary. If
+ * the string is not present in dictionary, the pointer is directly used by the
+ * dictionary. Otherwise, the reference counter is incremented and the value is
+ * freed. So, after calling the function, caller is supposed to not use the
+ * value address anymore.
+ * @return pointer to the string stored in the dictionary
+ */
+char *lydict_insert_zc(char *value);
+
+
+/**
+ * @brief Remove specified string from the dictionary. It decrement reference
+ * counter for the string and if it is zero, the string itself is freed.
+ *
+ * @param value[in] String to be freed. Note, that not only the string itself
+ * must match the stored value, but also the address is being compared and the
+ * counter is decremented only if it matches.
+ */
+void lydict_remove(const char *value);
#endif /* LY_DICT_H_ */