rpmio/rpmstrpool.h

   1 #ifndef _RPMSTRPOOL_H
   2 #define _RPMSTRPOOL_H
   3
   4 #include <rpm/rpmtypes.h>
   5
   6 #ifdef __cplusplus
   7 extern "C" {
   8 #endif
   9
  10 /** \ingroup rpmstrpool
  11  * Create a new, empty string pool.
  12  * @return              new string pool
  13  */
  14 rpmstrPool rpmstrPoolCreate(void);
  15
  16 /** \ingroup rpmstrpool
  17  * Free a string pool and its contents. While other references exist,
  18  * this only decrements the reference count.
  19  * @param pool          string pool
  20  * @return              NULL always
  21  */
  22 rpmstrPool rpmstrPoolFree(rpmstrPool pool);
  23
  24 /** \ingroup rpmstrpool
  25  * Reference a string pool
  26  * @param pool          string pool
  27  * @return              new string pool reference
  28  */
  29 rpmstrPool rpmstrPoolLink(rpmstrPool pool);
  30
  31 /** \ingroup rpmstrpool
  32  * Freeze a string pool: new strings cannot be added to a frozen pool.
  33  * If keephash is 0, memory usage is minimized but string -> id lookups
  34  * are no longer possible and unfreezing is an expensive operation.
  35  * Id -> string lookups are always possible on a frozen pool too.
  36  * @param pool          string pool
  37  * @param keephash      should string -> id hash be kept around?
  38  */
  39 void rpmstrPoolFreeze(rpmstrPool pool, int keephash);
  40
  41 /** \ingroup rpmstrpool
  42  * Unfreeze a string pool to allow new additions again.
  43  * If keephash was not specified on freezing, this requires rehashing
  44  * the entire pool contents.
  45  * @param pool          string pool
  46  */
  47 void rpmstrPoolUnfreeze(rpmstrPool pool);
  48
  49 /** \ingroup rpmstrpool
  50  * Look up the id of a string. If create is specified the string is
  51  * added to the pool if it does not already exist. Creation can only
  52  * fail if the pool is in frozen state.
  53  * @param pool          string pool
  54  * @param s             \0-terminated string to look up
  55  * @param create        should an id be created if not already present?
  56  * @return              id of the string or 0 for not found
  57  */
  58 rpmsid rpmstrPoolId(rpmstrPool pool, const char *s, int create);
  59
  60 /** \ingroup rpmstrpool
  61  * Look up the id of a string with predetermined length. The string does
  62  * not have to be \0-terminated. If create is specified the string is
  63  * added to the pool if it does not already exist. Creation can only
  64  * fail if the pool is in frozen state.
  65  * @param pool          string pool
  66  * @param s             string to look up
  67  * @param slen          number of characters from s to consider
  68  * @param create        should an id be created if not already present?
  69  * @return              id of the string or 0 for not found
  70  */
  71 rpmsid rpmstrPoolIdn(rpmstrPool pool, const char *s, size_t slen, int create);
  72
  73 /** \ingroup rpmstrpool
  74  * Look up a string by its pool id.
  75  * @param pool          string pool
  76  * @param sid           pool id of a string
  77  * @return              pointer to the string or NULL for invalid id
  78  */
  79 const char * rpmstrPoolStr(rpmstrPool pool, rpmsid sid);
  80
  81 /** \ingroup rpmstrpool
  82  * Return length of a string by its pool id. The result is equal to
  83  * calling strlen() on a string retrieved through rpmstrPoolStr() but
  84  * runs in constant time regardless of the length of the string.
  85  * @param pool          string pool
  86  * @param sid           pool id of a string
  87  * @return              length of the string
  88  */
  89 size_t rpmstrPoolStrlen(rpmstrPool pool, rpmsid sid);
  90
  91 /** \ingroup rpmstrpool
  92  * Compare two strings for equality by their ids. The result is equal to
  93  * calling rstreq() on two strings retrieved through rpmstrPoolStr() but
  94  * when the id's are within the same pool, this runs in constant time.
  95  * @param poolA         string pool of the first string
  96  * @param sidA          pool id of the first string
  97  * @param poolB         string pool of the second string
  98  * @param sidB          pool id of the second string
  99  * @return              1 if strings are equal, 0 otherwise
 100  */
 101 int rpmstrPoolStreq(rpmstrPool poolA, rpmsid sidA,
 102                     rpmstrPool poolB, rpmsid sidB);
 103
 104 /** \ingroup rpmstrpool
 105  * Return the number of strings stored in the pool. This number is
 106  * also the highest legal id for the pool.
 107  * @param pool          string pool
 108  * @return              number of strings in the pool
 109  */
 110 rpmsid rpmstrPoolNumStr(rpmstrPool pool);
 111
 112 #ifdef __cplusplus
 113 }
 114 #endif
 115
 116 #endif /* _RPMSIDPOOL_H */