String Pool API.

How to store strings in pools. More...

Collaboration diagram for String Pool API.:

Files
file	rpmstrpool.h
	String pools manipulation helper functions.

Functions
rpmstrPool	rpmstrPoolCreate (void)
	Create a new, empty string pool. More...
rpmstrPool	rpmstrPoolFree (rpmstrPool pool)
	Free a string pool and its contents. More...
rpmstrPool	rpmstrPoolLink (rpmstrPool pool)
	Reference a string pool. More...
void	rpmstrPoolFreeze (rpmstrPool pool, int keephash)
	Freeze a string pool: new strings cannot be added to a frozen pool. More...
void	rpmstrPoolUnfreeze (rpmstrPool pool)
	Unfreeze a string pool to allow new additions again. More...
rpmsid	rpmstrPoolId (rpmstrPool pool, const char *s, int create)
	Look up the id of a string. More...
rpmsid	rpmstrPoolIdn (rpmstrPool pool, const char *s, size_t slen, int create)
	Look up the id of a string with predetermined length. More...
const char *	rpmstrPoolStr (rpmstrPool pool, rpmsid sid)
	Look up a string by its pool id. More...
size_t	rpmstrPoolStrlen (rpmstrPool pool, rpmsid sid)
	Return length of a string by its pool id. More...
int	rpmstrPoolStreq (rpmstrPool poolA, rpmsid sidA, rpmstrPool poolB, rpmsid sidB)
	Compare two strings for equality by their ids. More...
rpmsid	rpmstrPoolNumStr (rpmstrPool pool)
	Return the number of strings stored in the pool. More...

Detailed Description

How to store strings in pools.

Function Documentation

rpmstrPoolCreate()

rpmstrPool rpmstrPoolCreate

(

void

)

Create a new, empty string pool.

Returns

new string pool

rpmstrPoolFree()

rpmstrPool rpmstrPoolFree

(

rpmstrPool

pool

)

Free a string pool and its contents.

While other references exist, this only decrements the reference count.

Parameters

pool	string pool

Returns

NULL always

rpmstrPoolFreeze()

void rpmstrPoolFreeze	(	rpmstrPool	pool,
		int	keephash
	)

Freeze a string pool: new strings cannot be added to a frozen pool.

If keephash is 0, memory usage is minimized but string -> id lookups are no longer possible and unfreezing is an expensive operation. Id -> string lookups are always possible on a frozen pool too.

Parameters

pool	string pool
keephash	should string -> id hash be kept around?

rpmstrPoolId()

rpmsid rpmstrPoolId	(	rpmstrPool	pool,
		const char *	s,
		int	create
	)

Look up the id of a string.

If create is specified the string is added to the pool if it does not already exist. Creation can only fail if the pool is in frozen state.

Parameters

pool	string pool
s	\0-terminated string to look up
create	should an id be created if not already present?

Returns

id of the string or 0 for not found

rpmstrPoolIdn()

rpmsid rpmstrPoolIdn	(	rpmstrPool	pool,
		const char *	s,
		size_t	slen,
		int	create
	)

Look up the id of a string with predetermined length.

The string does not have to be \0-terminated. If create is specified the string is added to the pool if it does not already exist. Creation can only fail if the pool is in frozen state.

Parameters

pool	string pool
s	string to look up
slen	number of characters from s to consider
create	should an id be created if not already present?

Returns

id of the string or 0 for not found

rpmstrPoolLink()

rpmstrPool rpmstrPoolLink

(

rpmstrPool

pool

)

Reference a string pool.

Parameters

pool	string pool

Returns

new string pool reference

rpmstrPoolNumStr()

rpmsid rpmstrPoolNumStr

(

rpmstrPool

pool

)

Return the number of strings stored in the pool.

This number is also the highest legal id for the pool.

Parameters

pool	string pool

Returns

number of strings in the pool

rpmstrPoolStr()

const char* rpmstrPoolStr	(	rpmstrPool	pool,
		rpmsid	sid
	)

Look up a string by its pool id.

Parameters

pool	string pool
sid	pool id of a string

Returns

pointer to the string or NULL for invalid id

rpmstrPoolStreq()

int rpmstrPoolStreq	(	rpmstrPool	poolA,
		rpmsid	sidA,
		rpmstrPool	poolB,
		rpmsid	sidB
	)

Compare two strings for equality by their ids.

The result is equal to calling rstreq() on two strings retrieved through rpmstrPoolStr() but when the id's are within the same pool, this runs in constant time.

Parameters

poolA	string pool of the first string
sidA	pool id of the first string
poolB	string pool of the second string
sidB	pool id of the second string

Returns

1 if strings are equal, 0 otherwise

rpmstrPoolStrlen()

size_t rpmstrPoolStrlen	(	rpmstrPool	pool,
		rpmsid	sid
	)

Return length of a string by its pool id.

The result is equal to calling strlen() on a string retrieved through rpmstrPoolStr(), but the pool might be able to optimize the calculation.

Parameters

pool	string pool
sid	pool id of a string

Returns

length of the string, 0 for invalid pool or id

rpmstrPoolUnfreeze()

void rpmstrPoolUnfreeze

(

rpmstrPool

pool

)

Unfreeze a string pool to allow new additions again.

If keephash was not specified on freezing, this requires rehashing the entire pool contents.

Parameters

pool	string pool