Mapping between names and values

Overview

Definition of the mapping functions. More…

// typedefs

typedef struct te_enum_map te_enum_map;

// structs

struct te_enum_map;

// global functions

int te_enum_map_from_str(const te_enum_map map[], const char* name, int unknown_val);
const char* te_enum_map_from_any_value(const te_enum_map map[], int value, const char* unknown);
static const char* te_enum_map_from_value(const te_enum_map map[], int value);
int te_enum_parse_longest_match(const te_enum_map map[], int defval, bool exact_match, const char* str, char** next);
void te_enum_map_fill_by_conversion(te_enum_map map[], int minval, int maxval, const char*(*)(int val) val2str);

// macros

#define TE_ENUM_MAP_ACTION(ftype_)
#define TE_ENUM_MAP_END

Detailed Documentation

Definition of the mapping functions.

Typedefs

typedef struct te_enum_map te_enum_map

A mapping between names and integral values.

An array of mappings should end with TE_ENUM_MAP_END

Global Functions

int te_enum_map_from_str(const te_enum_map map[], const char* name, int unknown_val)

Convert a symbolic name into a value.

If there are several mappings with the same name, the first one is used.

Parameters:

map	Mapping
name	Name
unknown_val	Value to return if the name is not found

Returns:

the value corresponding to name or unknown_val

const char* te_enum_map_from_any_value(const te_enum_map map[], int value, const char* unknown)

Convert a value into a symbolic name.

If there are several mappings with the same value, the first one is used.

Parameters:

map	Mapping
value	Value
unknown	Label to return if `value` is not found

Returns:

A string matching the value or unknown

static const char* te_enum_map_from_value(const te_enum_map map[], int value)

Same as te_enum_map_from_any_value() but aborts the program if the value is not found.

This is to be used where a set of values is known to be closed, so any value not in that set results from the programmer’s error.

Parameters:

map	Mapping
value	Value

Returns:

A string matching the value

int te_enum_parse_longest_match(const te_enum_map map[], int defval, bool exact_match, const char* str, char** next)

Parse the longest label from map at the start of str.

If exact_match is true, str must start with one of the labels from map. If there are several candidate labels, the longest one is chosen.

If exact_match is false, str must have a non-empty common prefix with one of the labels from map. If there are several such labels, the one with the longest common prefix is chosen (i.e. in this case the length of the label does not matter as such).

If there are multiple matches of the same length, the first one is chosen.

If a match is found, a corresponding value from map is returned and if next is not NULL, it is set to point to the rest of str.

If no match is found, defval is returned and next would contain unchanged str.

For example:

static const te_enum_map map[] = {
    { "ERROR", LEVEL_ERROR },
    { "WARNING", LEVEL_WARNING },
    TE_ENUM_MAP_END
};
...
val = te_enum_parse_longest_match(map, -1, false, "ERR message", &next);
// val is LEVEL_ERROR, next is " message"
// "ERR" and "ERROR" have a 3-character common prefix

val = te_enum_parse_longest_match(map, -1, true, "ERR message", &next);
// exact match is required, but "ERR message" does not start
// with any of labels in map, val is -1, next is "ERR message"

val = te_enum_parse_longest_match(map, -1, false, "WARN", &next);
// val is LEVEL_WARNING, next is ""

val = te_enum_parse_longest_match(map, -1, false, "INFO", &next);
// even though match is not exact, there is no label in map
// that would have a non-empty common prefix with "INFO",
// so val is -1, next is "INFO"

This function may be used on non-zero terminated byte arrays, if it can be ensured there are always valid characters after the prefix:

char bytes[13] = "ERROR message"; // no terminating zero
te_enum_parse_longest_match(map, -1, false, bytes, &next);
// ok, we know there are valid characters after the label

char bytes[3] = "ERR"; // no terminating zero
te_enum_parse_longest_match(map, -1, false, bytes, &next);
// not ok: the function will look past the last valid character

Parameters:

map	Mapping.
defval	Default return value.
exact_match	If `true`, prefixes of map labels are matched.
str	Input string.
next	If not `NULL`, the rest of `str` is stored here.

Returns:

A corresponding enum value from map or defval.

void te_enum_map_fill_by_conversion(te_enum_map map[], int minval, int maxval, const char*(*)(int val) val2str)

Fill in an enum mapping array based on the mapping function.

The purpose of the function is to bridge te_enum API and pre-existing value-to-string functions such as used in RPC libraries

Parameters:

map	An array of sufficient size (`maxval` - `minval` + 2) to be filled. The terminating TE_ENUM_MAP_END will be appended
minval	Minimal enum value
maxval	Maximum enum value
val2str	Conversion function

Macros

#define TE_ENUM_MAP_ACTION(ftype_)

Define a structure to map names to actions.

The structure will have two fields:

name
action

The structure is intended to be used with TE_ENUM_DISPATCH.

An array of such structures should be terminated with TE_ENUM_MAP_END.

Parameters:

ftype_

type of actions: a pointer to function type

#define TE_ENUM_MAP_END

Terminating element of an enum mapping array