String Pool API.
Data types:

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