rpmio/rpmstrpool.h

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