flist.h

Go to the documentation of this file.
00001 // Copyright 2006 Benedikt Böhm <hollow@gentoo.org>
00002 //
00003 // This program is free software; you can redistribute it and/or modify
00004 // it under the terms of the GNU General Public License as published by
00005 // the Free Software Foundation; either version 2 of the License, or
00006 // (at your option) any later version.
00007 //
00008 // This program is distributed in the hope that it will be useful,
00009 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00010 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00011 // GNU General Public License for more details.
00012 //
00013 // You should have received a copy of the GNU General Public License
00014 // along with this program; if not, write to the
00015 // Free Software Foundation, Inc.,
00016 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
00017 
00018 /*!
00019  * @defgroup flist Flag list conversion
00020  *
00021  * The flag list family of functions manages a list of possible values of a
00022  * bitmap using strings as key into the list.
00023  *
00024  * A bitmap is simply an integer with certain bits being 1 (enabled) and 0
00025  * (disabled).
00026  *
00027  * The FLIST32_START and FLIST64_START macros provides a shortcut for list
00028  * declaration and initialization; followed by one or more of FLIST32_NODE,
00029  * FLIST32_NODE1, FLIST64_NODE and FLIST64_NODE1 to insert nodes into the list.
00030  * The FLIST32_NODE1 and FLIST64_NODE1 macros are the same as FLIST32_NODE and
00031  * FLIST64_NODE, respectively, except that they convert the bit index to a
00032  * bitmap value before storing it in the list. The list should then be
00033  * terminated using FLIST32_END or FLIST64_END, respectively.
00034  *
00035  * The flist32_getval(), flist64_getval(), flist32_getkey() and flist64_getkey()
00036  * functions provide lookup routines by key and value, respectively.
00037  *
00038  * The flist32_from_str() and flist64_from_str() functions convert a string
00039  * consisting of zero or more flag list keys seperated by a delimiter and
00040  * optionally prefixed with a clear modifier to a bitmap/bitmask pair according
00041  * to a given list.
00042  *
00043  * The flist32_to_str() and flist64_to_str() functions convert a bitmap
00044  * according to a given list to a string consisting of zero or more flag list
00045  * keys seperated by a delimiter.
00046  *
00047  * @{
00048  */
00049 
00050 #ifndef _LUCID_FLIST_H
00051 #define _LUCID_FLIST_H
00052 
00053 #include <stdint.h>
00054 
00055 /*! @brief 32 bit list object */
00056 typedef struct {
00057         const char *key;    /*!< Node key (must be unique) */
00058         const uint32_t val; /*!< Node value (32-bit) */
00059 } flist32_t;
00060 
00061 /*! @brief 32 bit list initialization */
00062 #define FLIST32_START(LIST) const flist32_t LIST[] = {
00063 
00064 /*! @brief 32 bit list node */
00065 #define FLIST32_NODE(PREFIX, NAME) { #NAME, PREFIX ## _ ## NAME },
00066 
00067 /*! @brief 32 bit list node from index */
00068 #define FLIST32_NODE1(PREFIX, NAME) { #NAME, (1 << PREFIX ## _ ## NAME) },
00069 
00070 /*! @brief 32 bit list termination */
00071 #define FLIST32_END { NULL, 0 } };
00072 
00073 /*!
00074  * @brief get 32 bit value by key
00075  *
00076  * @param[in] list list to use for conversion
00077  * @param[in] key  key to look for
00078  *
00079  * @return 32 bit value >= 1 if key found, 0 otherwise
00080  */
00081 uint32_t flist32_getval(const flist32_t list[], const char *key);
00082 
00083 /*!
00084  * @brief get key from 32 bit value
00085  *
00086  * @param[in] list list to use for conversion
00087  * @param[in] val  32 bit key to look for
00088  *
00089  * @return key if value was found, NULL otherwise
00090  *
00091  * @note this functions does not reset the flags or mask argument to an empty
00092  *       bitmap, thus allowing incremental changes to the map.
00093  */
00094 const char *flist32_getkey(const flist32_t list[], uint32_t val);
00095 
00096 /*!
00097  * @brief parse flag list string
00098  *
00099  * @param[in]  str   string to convert
00100  * @param[in]  list  list to use for conversion
00101  * @param[out] flags pointer to a bit mask
00102  * @param[out] mask  pointer to a set mask
00103  * @param[in]  clmod clear flag modifier
00104  * @param[in]  delim flag delimiter
00105  *
00106  * @return 0 on success, -1 on error with errno set
00107  */
00108 int flist32_from_str(const char *str, const flist32_t list[],
00109                      uint32_t *flags, uint32_t *mask,
00110                      char clmod, char delim);
00111 
00112 /*!
00113  * @brief convert bit mask to flag list string
00114  *
00115  * @param[in] list  list to use for conversion
00116  * @param[in] val   bit mask
00117  * @param[in] delim flag delimiter
00118  *
00119  * @return flags list string (obtained with malloc(3))
00120  *
00121  * @note the caller should free obtained memory using free(3)
00122  * @note this function ignores set bits if they do not appear in the list
00123  * @note if no flag was found or the bitmap was empty, an empty string is
00124  *       returned, not NULL
00125  *
00126  * @see malloc(3)
00127  * @see free(3)
00128  */
00129 char *flist32_to_str(const flist32_t list[], uint32_t val, char delim);
00130 
00131 
00132 
00133 /*! @brief 64 bit list object */
00134 typedef struct {
00135         const char *key;    /*!< Node key (must be unique) */
00136         const uint64_t val; /*!< Node value (64-bit) */
00137 } flist64_t;
00138 
00139 /*! @brief 64 bit list initialization */
00140 #define FLIST64_START(LIST) const flist64_t LIST[] = {
00141 
00142 /*! @brief 64 bit list node */
00143 #define FLIST64_NODE(PREFIX, NAME) { #NAME, PREFIX ## _ ## NAME },
00144 
00145 /*! @brief 64 bit list node from index */
00146 #define FLIST64_NODE1(PREFIX, NAME) { #NAME, (1 << PREFIX ## _ ## NAME) },
00147 
00148 /*! @brief 64 bit list termination */
00149 #define FLIST64_END { NULL, 0 } };
00150 
00151 /*!
00152  * @brief get 64 bit value by key
00153  *
00154  * @param[in] list list to use for conversion
00155  * @param[in] key  key to look for
00156  *
00157  * @return 64 bit value >= 1 if key was found, 0 otherwise
00158  */
00159 uint64_t flist64_getval(const flist64_t list[], const char *key);
00160 
00161 /*!
00162  * @brief get key from 64 bit value
00163  *
00164  * @param[in] list list to use for conversion
00165  * @param[in] val  64 bit key to look for
00166  *
00167  * @return key if value was found, NULL otherwise
00168  */
00169 const char *flist64_getkey(const flist64_t list[], uint64_t val);
00170 
00171 /*!
00172  * @brief parse flag list string
00173  *
00174  * @param[in]  str   string to convert
00175  * @param[in]  list  list to use for conversion
00176  * @param[out] flags pointer to a bit mask
00177  * @param[out] mask  pointer to a set mask
00178  * @param[in]  clmod clear flag modifier
00179  * @param[in]  delim flag delimiter
00180  *
00181  * @return 0 on success, -1 on error with errno set
00182  *
00183  * @note this functions does not reset the flags or mask argument to an empty
00184  *       bitmap, thus allowing incremental changes to the map.
00185  */
00186 int flist64_from_str(const char *str, const flist64_t list[],
00187                      uint64_t *flags, uint64_t *mask,
00188                      char clmod, char delim);
00189 
00190 /*!
00191  * @brief convert bit mask to flag list string
00192  *
00193  * @param[in] list  list to use for conversion
00194  * @param[in] val   bit mask
00195  * @param[in] delim flag delimiter
00196  *
00197  * @return flags list string (obtained with malloc(3))
00198  *
00199  * @note the caller should free obtained memory using free(3)
00200  * @note this function ignores set bits if they do not appear in the list
00201  * @note if no flag was found or the bitmap was empty, an empty string is
00202  *       returned, not NULL
00203  *
00204  * @see malloc(3)
00205  * @see free(3)
00206  */
00207 char *flist64_to_str(const flist64_t list[], uint64_t val, char delim);
00208 
00209 #endif
00210 
00211 /*! @} flist */

Generated on Sun Dec 3 17:45:53 2006 for lucid by  doxygen 1.5.1