Flag list conversion


Detailed Description

The flag list family of functions manages a list of possible values of a bitmap using strings as key into the list.

A bitmap is simply an integer with certain bits being 1 (enabled) and 0 (disabled).

The FLIST32_START and FLIST64_START macros provides a shortcut for list declaration and initialization; followed by one or more of FLIST32_NODE, FLIST32_NODE1, FLIST64_NODE and FLIST64_NODE1 to insert nodes into the list. The FLIST32_NODE1 and FLIST64_NODE1 macros are the same as FLIST32_NODE and FLIST64_NODE, respectively, except that they convert the bit index to a bitmap value before storing it in the list. The list should then be terminated using FLIST32_END or FLIST64_END, respectively.

The flist32_getval(), flist64_getval(), flist32_getkey() and flist64_getkey() functions provide lookup routines by key and value, respectively.

The flist32_from_str() and flist64_from_str() functions convert a string consisting of zero or more flag list keys seperated by a delimiter and optionally prefixed with a clear modifier to a bitmap/bitmask pair according to a given list.

The flist32_to_str() and flist64_to_str() functions convert a bitmap according to a given list to a string consisting of zero or more flag list keys seperated by a delimiter.


Data Structures

struct  flist32_t
 32 bit list object More...
struct  flist64_t
 64 bit list object More...

Defines

#define FLIST32_START(LIST)   const flist32_t LIST[] = {
 32 bit list initialization
#define FLIST32_NODE(PREFIX, NAME)   { #NAME, PREFIX ## _ ## NAME },
 32 bit list node
#define FLIST32_NODE1(PREFIX, NAME)   { #NAME, (1 << PREFIX ## _ ## NAME) },
 32 bit list node from index
#define FLIST32_END   { NULL, 0 } };
 32 bit list termination
#define FLIST64_START(LIST)   const flist64_t LIST[] = {
 64 bit list initialization
#define FLIST64_NODE(PREFIX, NAME)   { #NAME, PREFIX ## _ ## NAME },
 64 bit list node
#define FLIST64_NODE1(PREFIX, NAME)   { #NAME, (1 << PREFIX ## _ ## NAME) },
 64 bit list node from index
#define FLIST64_END   { NULL, 0 } };
 64 bit list termination

Functions

uint32_t flist32_getval (const flist32_t list[], const char *key)
 get 32 bit value by key
const char * flist32_getkey (const flist32_t list[], uint32_t val)
 get key from 32 bit value
int flist32_from_str (const char *str, const flist32_t list[], uint32_t *flags, uint32_t *mask, char clmod, char delim)
 parse flag list string
char * flist32_to_str (const flist32_t list[], uint32_t val, char delim)
 convert bit mask to flag list string
uint64_t flist64_getval (const flist64_t list[], const char *key)
 get 64 bit value by key
const char * flist64_getkey (const flist64_t list[], uint64_t val)
 get key from 64 bit value
int flist64_from_str (const char *str, const flist64_t list[], uint64_t *flags, uint64_t *mask, char clmod, char delim)
 parse flag list string
char * flist64_to_str (const flist64_t list[], uint64_t val, char delim)
 convert bit mask to flag list string


Define Documentation

#define FLIST32_START ( LIST   )     const flist32_t LIST[] = {

32 bit list initialization

Definition at line 62 of file flist.h.

#define FLIST32_NODE ( PREFIX,
NAME   )     { #NAME, PREFIX ## _ ## NAME },

32 bit list node

Definition at line 65 of file flist.h.

#define FLIST32_NODE1 ( PREFIX,
NAME   )     { #NAME, (1 << PREFIX ## _ ## NAME) },

32 bit list node from index

Definition at line 68 of file flist.h.

#define FLIST32_END   { NULL, 0 } };

32 bit list termination

Definition at line 71 of file flist.h.

#define FLIST64_START ( LIST   )     const flist64_t LIST[] = {

64 bit list initialization

Definition at line 140 of file flist.h.

#define FLIST64_NODE ( PREFIX,
NAME   )     { #NAME, PREFIX ## _ ## NAME },

64 bit list node

Definition at line 143 of file flist.h.

#define FLIST64_NODE1 ( PREFIX,
NAME   )     { #NAME, (1 << PREFIX ## _ ## NAME) },

64 bit list node from index

Definition at line 146 of file flist.h.

#define FLIST64_END   { NULL, 0 } };

64 bit list termination

Definition at line 149 of file flist.h.


Function Documentation

uint32_t flist32_getval ( const flist32_t  list[],
const char *  key 
)

get 32 bit value by key

Parameters:
[in] list list to use for conversion
[in] key key to look for
Returns:
32 bit value >= 1 if key found, 0 otherwise

Definition at line 23 of file flist32_getval.c.

References flist32_t::key, and str_cmp().

Referenced by flist32_from_str().

00024 {
00025         int i;
00026         
00027         for (i = 0; list[i].key; i++) {
00028                 if (str_cmp(list[i].key, key) == 0)
00029                         return list[i].val;
00030         }
00031         
00032         return errno = ENOENT, 0;
00033 }

const char* flist32_getkey ( const flist32_t  list[],
uint32_t  val 
)

get key from 32 bit value

Parameters:
[in] list list to use for conversion
[in] val 32 bit key to look for
Returns:
key if value was found, NULL otherwise
Note:
this functions does not reset the flags or mask argument to an empty bitmap, thus allowing incremental changes to the map.

Definition at line 23 of file flist32_getkey.c.

References flist32_t::key.

00024 {
00025         int i;
00026         
00027         for (i = 0; list[i].key; i++) {
00028                 if (list[i].val == val)
00029                         return list[i].key;
00030         }
00031         
00032         return errno = ENOENT, NULL;
00033 }

int flist32_from_str ( const char *  str,
const flist32_t  list[],
uint32_t *  flags,
uint32_t *  mask,
char  clmod,
char  delim 
)

parse flag list string

Parameters:
[in] str string to convert
[in] list list to use for conversion
[out] flags pointer to a bit mask
[out] mask pointer to a set mask
[in] clmod clear flag modifier
[in] delim flag delimiter
Returns:
0 on success, -1 on error with errno set

Definition at line 24 of file flist32_from_str.c.

References char_isspace, flist32_getval(), str_dup(), str_index(), str_isempty, and str_len().

00027 {
00028         char *p, *o, *buf;
00029         int clear = 0;
00030         uint32_t cur_flag;
00031         
00032         if (str_isempty(str))
00033                 return errno = EINVAL, -1;
00034         
00035         buf = p = o = str_dup(str);
00036         
00037         while (1) {
00038                 p = str_index(p, delim, str_len(p));
00039                 
00040                 while (char_isspace(*o))
00041                         o++;
00042                 
00043                 if (p) {
00044                         if (o == p) {
00045                                 p++;
00046                                 continue;
00047                         }
00048                         
00049                         *p++ = '\0';
00050                 }
00051                 
00052                 if (*o == clmod)
00053                         clear = 1;
00054                 
00055                 cur_flag = flist32_getval(list, o+clear);
00056                 
00057                 if (!cur_flag) {
00058                         free(buf);
00059                         return errno = ENOENT, -1;
00060                 }
00061                 
00062                 if (clear) {
00063                         *flags &= ~cur_flag;
00064                         *mask  |=  cur_flag;
00065                 } else {
00066                         *flags |=  cur_flag;
00067                         *mask  |=  cur_flag;
00068                 }
00069                 
00070                 if (!p)
00071                         break;
00072                 else
00073                         o = p;
00074         }
00075         
00076         free(buf);
00077         return 0;
00078 }

char* flist32_to_str ( const flist32_t  list[],
uint32_t  val,
char  delim 
)

convert bit mask to flag list string

Parameters:
[in] list list to use for conversion
[in] val bit mask
[in] delim flag delimiter
Returns:
flags list string (obtained with malloc(3))
Note:
the caller should free obtained memory using free(3)

this function ignores set bits if they do not appear in the list

if no flag was found or the bitmap was empty, an empty string is returned, not NULL

See also:
malloc(3)

free(3)

Definition at line 22 of file flist32_to_str.c.

References flist32_t::key, str_dupn(), stralloc_catf(), stralloc_free(), and stralloc_init().

00023 {
00024         int i;
00025         size_t len;
00026         char *str;
00027         stralloc_t buf;
00028         
00029         stralloc_init(&buf);
00030         
00031         for (i = 0; list[i].key; i++)
00032                 if (val & list[i].val)
00033                         stralloc_catf(&buf, "%s%c", list[i].key, delim);
00034         
00035         if (buf.len == 0)
00036                 len = 0;
00037         else
00038                 len = buf.len - 1;
00039         
00040         str = str_dupn(buf.s, len);
00041         stralloc_free(&buf);
00042         return str;
00043 }

uint64_t flist64_getval ( const flist64_t  list[],
const char *  key 
)

get 64 bit value by key

Parameters:
[in] list list to use for conversion
[in] key key to look for
Returns:
64 bit value >= 1 if key was found, 0 otherwise

Definition at line 23 of file flist64_getval.c.

References flist64_t::key, and str_cmp().

Referenced by flist64_from_str().

00024 {
00025         int i;
00026         
00027         for (i = 0; list[i].key; i++) {
00028                 if (str_cmp(list[i].key, key) == 0)
00029                         return list[i].val;
00030         }
00031         
00032         return errno = ENOENT, 0;
00033 }

const char* flist64_getkey ( const flist64_t  list[],
uint64_t  val 
)

get key from 64 bit value

Parameters:
[in] list list to use for conversion
[in] val 64 bit key to look for
Returns:
key if value was found, NULL otherwise

Definition at line 23 of file flist64_getkey.c.

References flist64_t::key.

00024 {
00025         int i;
00026         
00027         for (i = 0; list[i].key; i++) {
00028                 if (list[i].val == val)
00029                         return list[i].key;
00030         }
00031         
00032         return errno = ENOENT, NULL;
00033 }

int flist64_from_str ( const char *  str,
const flist64_t  list[],
uint64_t *  flags,
uint64_t *  mask,
char  clmod,
char  delim 
)

parse flag list string

Parameters:
[in] str string to convert
[in] list list to use for conversion
[out] flags pointer to a bit mask
[out] mask pointer to a set mask
[in] clmod clear flag modifier
[in] delim flag delimiter
Returns:
0 on success, -1 on error with errno set
Note:
this functions does not reset the flags or mask argument to an empty bitmap, thus allowing incremental changes to the map.

Definition at line 24 of file flist64_from_str.c.

References char_isspace, flist64_getval(), str_dup(), str_index(), str_isempty, and str_len().

00027 {
00028         char *p, *o, *buf;
00029         int clear = 0;
00030         uint64_t cur_flag;
00031         
00032         if (str_isempty(str))
00033                 return errno = EINVAL, -1;
00034         
00035         buf = p = o = str_dup(str);
00036         
00037         while (1) {
00038                 p = str_index(p, delim, str_len(p));
00039                 
00040                 while (char_isspace(*o))
00041                         o++;
00042                 
00043                 if (p) {
00044                         if (o == p) {
00045                                 p++;
00046                                 continue;
00047                         }
00048                         
00049                         *p++ = '\0';
00050                 }
00051                 
00052                 if (*o == clmod)
00053                         clear = 1;
00054                 
00055                 cur_flag = flist64_getval(list, o+clear);
00056                 
00057                 if (!cur_flag) {
00058                         free(buf);
00059                         return errno = ENOENT, -1;
00060                 }
00061                 
00062                 if (clear) {
00063                         *flags &= ~cur_flag;
00064                         *mask  |=  cur_flag;
00065                 } else {
00066                         *flags |=  cur_flag;
00067                         *mask  |=  cur_flag;
00068                 }
00069                 
00070                 if (!p)
00071                         break;
00072                 else
00073                         o = p;
00074         }
00075         
00076         free(buf);
00077         return 0;
00078 }

char* flist64_to_str ( const flist64_t  list[],
uint64_t  val,
char  delim 
)

convert bit mask to flag list string

Parameters:
[in] list list to use for conversion
[in] val bit mask
[in] delim flag delimiter
Returns:
flags list string (obtained with malloc(3))
Note:
the caller should free obtained memory using free(3)

this function ignores set bits if they do not appear in the list

if no flag was found or the bitmap was empty, an empty string is returned, not NULL

See also:
malloc(3)

free(3)

Definition at line 22 of file flist64_to_str.c.

References flist64_t::key, str_dupn(), stralloc_catf(), stralloc_free(), and stralloc_init().

00023 {
00024         int i;
00025         size_t len;
00026         char *str;
00027         stralloc_t buf;
00028         
00029         stralloc_init(&buf);
00030         
00031         for (i = 0; list[i].key; i++)
00032                 if (val & list[i].val)
00033                         stralloc_catf(&buf, "%s%c", list[i].key, delim);
00034         
00035         if (buf.len == 0)
00036                 len = 0;
00037         else
00038                 len = buf.len - 1;
00039         
00040         str = str_dupn(buf.s, len);
00041         stralloc_free(&buf);
00042         return str;
00043 }


Generated on Sun Dec 3 17:46:16 2006 for lucid by  doxygen 1.5.1