flist.h

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

Generated on Tue Jun 19 20:38:26 2007 for lucid by  doxygen 1.5.2