[thirdparty/git.git] / vcs-svn / string_pool.txt

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.
Commit	Line	Data
1d73b52f DB	1	string_pool API
	2	===============
	3
	4	The string_pool API provides facilities for replacing strings
	5	with integer keys that can be more easily compared and stored.
	6	The facilities are designed so that one could teach Git without
	7	too much trouble to store the information needed for these keys to
	8	remain valid over multiple executions.
	9
	10	Functions
	11	---------
	12
	13	pool_intern::
	14	Include a string in the string pool and get its key.
	15	If that string is already in the pool, retrieves its
	16	existing key.
	17
	18	pool_fetch::
	19	Retrieve the string associated to a given key.
	20
	21	pool_tok_r::
	22	Extract the key of the next token from a string.
	23	Interface mimics strtok_r.
	24
	25	pool_print_seq::
	26	Print a sequence of strings named by key to a file, using the
	27	specified delimiter to separate them.
	28
	29	If NULL (key ~0) appears in the sequence, the sequence ends
	30	early.
	31
	32	pool_tok_seq::
	33	Split a string into tokens, storing the keys of segments
	34	into a caller-provided array.
	35
	36	Unless sz is 0, the array will always be ~0-terminated.
	37	If there is not enough room for all the tokens, the
	38	array holds as many tokens as fit in the entries before
	39	the terminating ~0. Return value is the index after the
	40	last token, or sz if the tokens did not fit.
	41
	42	pool_reset::
	43	Deallocate storage for the string pool.