Add string-specific memory pool

Intern strings so they can be compared by address and stored without
wasting space.

This library uses the macros in the obj_pool.h and trp.h to create a
memory pool for strings and expose an API for handling them.

[rr: added API docs]
[jn: with some API simplifications, new documentation and tests]

Signed-off-by: David Barr <david.barr@cordelta.com>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

1 files changed, 43 insertions, 0 deletions

diff --git a/vcs-svn/string_pool.txt b/vcs-svn/string_pool.txt
new file mode 100644
index 000000000..1b41f1562
--- /dev/null
+++ b/vcs-svn/string_pool.txt
@@ -0,0 +1,43 @@
+string_pool API
+===============
+
+The string_pool API provides facilities for replacing strings
+with integer keys that can be more easily compared and stored.
+The facilities are designed so that one could teach Git without
+too much trouble to store the information needed for these keys to
+remain valid over multiple executions.
+
+Functions
+---------
+
+pool_intern::
+	Include a string in the string pool and get its key.
+	If that string is already in the pool, retrieves its
+	existing key.
+
+pool_fetch::
+	Retrieve the string associated to a given key.
+
+pool_tok_r::
+	Extract the key of the next token from a string.
+	Interface mimics strtok_r.
+
+pool_print_seq::
+	Print a sequence of strings named by key to a file, using the
+	specified delimiter to separate them.
+
+	If NULL (key ~0) appears in the sequence, the sequence ends
+	early.
+
+pool_tok_seq::
+	Split a string into tokens, storing the keys of segments
+	into a caller-provided array.
+
+	Unless sz is 0, the array will always be ~0-terminated.
+	If there is not enough room for all the tokens, the
+	array holds as many tokens as fit in the entries before
+	the terminating ~0.  Return value is the index after the
+	last token, or sz if the tokens did not fit.
+
+pool_reset::
+	Deallocate storage for the string pool.