table.h

Go to the documentation of this file.

#pragma once
/*
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
 */
 
/**
 * $Id: 1ccb12f6bd550c64587949f517ae5e396663ac34 $
 *
 * @file lib/util/table.h
 * @brief Lookup table functions
 *
 * @copyright 2019 The FreeRADIUS server project
 * @copyright 2019 Arran Cudbard-Bell (a.cudbardb@freeradius.org)
 */
RCSIDH(table_h, "$Id: 1ccb12f6bd550c64587949f517ae5e396663ac34 $")
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stddef.h>
#include <stdint.h>
#include <sys/types.h>
 
typedef struct {
        char const              *str;   //!< Literal string.
        size_t                  len;    //!< Literal string length.
} fr_table_elem_t;
 
/** An element in a lexicographically sorted array of name to num mappings
 *
 */
typedef struct {
        fr_table_elem_t         name;
        int                     value;
} fr_table_num_sorted_t;
 
/** An element in an arbitrarily ordered array of name to num mappings
 *
 */
typedef struct {
        fr_table_elem_t         name;
        int                     value;
} fr_table_num_ordered_t;
 
/** An element in a lexicographically sorted array of name to ptr mappings
 *
 */
typedef struct {
        fr_table_elem_t         name;
        void const              *value;
} fr_table_ptr_sorted_t;
 
/** An element in an arbitrarily ordered array of name to ptr mappings
 *
 */
typedef struct {
        fr_table_elem_t         name;
        void const              *value;
} fr_table_ptr_ordered_t;
 
/** An element in a table indexed by bit position
 *
 * i.e. if only the first bit is set in a bitfield, the entry at index 0
 * will be returned.
 */
typedef struct {
        fr_table_elem_t         name;
        uint64_t                value;
} fr_table_num_indexed_bit_pos_t;
 
/** An element in a table indexed by numeric value
 *
 * i.e. if the value is 0, we return the string mapped to the first element of the table.
 */
typedef struct {
        fr_table_elem_t         name;
        unsigned int            value;
} fr_table_num_indexed_t;
 
/** Macro to use as dflt
 *
 */
#define NAME_NUMBER_NOT_FOUND   INT32_MIN
 
char const *_fr_table_ptr_by_str_value(fr_table_ptr_sorted_t const *table, size_t table_len, char const *str_val, char const *def);
 
/** Brute force search a sorted or ordered ptr table, assuming the pointers are strings
 *
 * @param[in] _table            to search in.
 * @param[in] _str_value        to compare against the ptr field.
 * @param[in] _def              default value.
 */
#define fr_table_str_by_str_value(_table, _str_value, _def) \
_Generic((_table), \
         fr_table_ptr_sorted_t const *          : _fr_table_ptr_by_str_value((fr_table_ptr_sorted_t const *)_table, _table ## _len, _str_value, _def), \
         fr_table_ptr_ordered_t const *         : _fr_table_ptr_by_str_value((fr_table_ptr_sorted_t const *)_table, _table ## _len, _str_value, _def), \
         fr_table_ptr_sorted_t *                : _fr_table_ptr_by_str_value((fr_table_ptr_sorted_t const *)_table, _table ## _len, _str_value, _def), \
         fr_table_ptr_ordered_t *               : _fr_table_ptr_by_str_value((fr_table_ptr_sorted_t const *)_table, _table ## _len, _str_value, _def))
 
int             fr_table_sorted_num_by_str(fr_table_num_sorted_t const *table, size_t table_len,
                                           char const *name, int def);
 
int             fr_table_ordered_num_by_str(fr_table_num_ordered_t const *table, size_t table_len,
                                            char const *name, int def);
 
void            *fr_table_sorted_ptr_by_str(fr_table_ptr_sorted_t const *table, size_t table_len,
                                            char const *name, void const *def);
 
void            *fr_table_ordered_ptr_by_str(fr_table_ptr_ordered_t const *table, size_t table_len,
                                             char const *name, void const *def);
 
/** Convert a string to a value using a sorted or ordered table
 *
 * @param[in] _table    to search in.
 * @param[in] _name     to resolve to a number.
 * @param[in] _def      Default value if no entry matched.
 * @return
 *      - _def if name matched no entries in the table.
 *      - the numeric value of the matching entry.
 */
#define fr_table_value_by_str(_table, _name, _def) \
_Generic((_table), \
         fr_table_num_sorted_t const *          : fr_table_sorted_num_by_str,                   \
         fr_table_num_ordered_t const *         : fr_table_ordered_num_by_str,                  \
         fr_table_num_sorted_t *                : fr_table_sorted_num_by_str,                   \
         fr_table_num_ordered_t *               : fr_table_ordered_num_by_str,                  \
         fr_table_ptr_sorted_t const *          : fr_table_sorted_ptr_by_str,                   \
         fr_table_ptr_ordered_t const *         : fr_table_ordered_ptr_by_str,                  \
         fr_table_ptr_sorted_t *                : fr_table_sorted_ptr_by_str,                   \
         fr_table_ptr_ordered_t *               : fr_table_ordered_ptr_by_str,                  \
         fr_table_num_indexed_bit_pos_t *       : fr_table_ordered_num_by_str,                  \
         fr_table_num_indexed_bit_pos_t const * : fr_table_ordered_num_by_str,                  \
         fr_table_num_indexed_t *               : fr_table_ordered_num_by_str,                  \
         fr_table_num_indexed_t const *         : fr_table_ordered_num_by_str                   \
)(_table, _table ## _len, _name, _def)
 
int             fr_table_sorted_num_by_substr(fr_table_num_sorted_t const *table, size_t table_len,
                                              char const *name, ssize_t name_len, int def);
 
int             fr_table_ordered_num_by_substr(fr_table_num_ordered_t const *table, size_t table_len,
                                               char const *name, ssize_t name_len, int def);
 
void            *fr_table_sorted_ptr_by_substr(fr_table_ptr_sorted_t const *table, size_t table_len,
                                               char const *name, ssize_t name_len, void const *def);
 
void            *fr_table_ordered_ptr_by_substr(fr_table_ptr_ordered_t const *table, size_t table_len,
                                                char const *name, ssize_t name_len, void const *def);
 
/** Convert a partial string to a value using an ordered or sorted table
 *
 * @param[in] _table    to search in.
 * @param[in] _name     to resolve to a number.
 * @param[in] _name_len The amount of name to match.
 *                      If < 0, the length of the name in the table element
 *                      will be used as the maximum match length.
 * @param[in] _def      Default value if no entry matched.
 * @return
 *      - _def if name matched no entries in the table.
 *      - the numeric value of the matching entry.
 */
#define fr_table_value_by_substr(_table, _name, _name_len, _def) \
_Generic((_table), \
         fr_table_num_sorted_t const *          : fr_table_sorted_num_by_substr,                \
         fr_table_num_ordered_t const *         : fr_table_ordered_num_by_substr,               \
         fr_table_num_sorted_t *                : fr_table_sorted_num_by_substr,                \
         fr_table_num_ordered_t *               : fr_table_ordered_num_by_substr,               \
         fr_table_ptr_sorted_t const *          : fr_table_sorted_ptr_by_substr,                \
         fr_table_ptr_ordered_t const *         : fr_table_ordered_ptr_by_substr,               \
         fr_table_ptr_sorted_t *                : fr_table_sorted_ptr_by_substr,                \
         fr_table_ptr_ordered_t *               : fr_table_ordered_ptr_by_substr,               \
         fr_table_num_indexed_bit_pos_t *       : fr_table_ordered_num_by_substr,               \
         fr_table_num_indexed_bit_pos_t const * : fr_table_ordered_num_by_substr,               \
         fr_table_num_indexed_t *               : fr_table_ordered_num_by_substr,               \
         fr_table_num_indexed_t const *         : fr_table_ordered_num_by_substr                \
)(_table, _table ## _len, _name, _name_len, _def)
 
int     fr_table_sorted_num_by_longest_prefix(size_t *match_len, fr_table_num_sorted_t const *table, size_t table_len,
                                              char const *name, ssize_t name_len, int def);
 
int     fr_table_ordered_num_by_longest_prefix(size_t *match_len, fr_table_num_ordered_t const *table, size_t table_len,
                                               char const *name, ssize_t name_len, int def);
 
void    *fr_table_sorted_ptr_by_longest_prefix(size_t *match_len, fr_table_ptr_sorted_t const *table, size_t table_len,
                                               char const *name, ssize_t name_len, void const *def);
 
void    *fr_table_ordered_ptr_by_longest_prefix(size_t *match_len, fr_table_ptr_ordered_t const *table, size_t table_len,
                                                char const *name, ssize_t name_len, void const *def);
 
/** Find the longest string match using a sorted or ordered table
 *
 * @param[out] _match_len       How much of the input string matched.
 * @param[in] _table            to search in.
 * @param[in] _name             to resolve to a number.
 * @param[in] _name_len         The amount of name to match.
 * @param[in] _def              Default value if no entry matched.
 * @return
 *      - _def if name matched no entries in the table.
 *      - the value of the matching entry.
 */
#define fr_table_value_by_longest_prefix(_match_len, _table, _name, _name_len, _def) \
_Generic((_table), \
         fr_table_num_sorted_t const *          : fr_table_sorted_num_by_longest_prefix,        \
         fr_table_num_ordered_t const *         : fr_table_ordered_num_by_longest_prefix,       \
         fr_table_num_sorted_t *                : fr_table_sorted_num_by_longest_prefix,        \
         fr_table_num_ordered_t *               : fr_table_ordered_num_by_longest_prefix,       \
         fr_table_ptr_sorted_t const *          : fr_table_sorted_ptr_by_longest_prefix,        \
         fr_table_ptr_ordered_t const *         : fr_table_ordered_ptr_by_longest_prefix,       \
         fr_table_ptr_sorted_t *                : fr_table_sorted_ptr_by_longest_prefix,        \
         fr_table_ptr_ordered_t *               : fr_table_ordered_ptr_by_longest_prefix,       \
         fr_table_num_indexed_bit_pos_t *       : fr_table_ordered_num_by_longest_prefix,       \
         fr_table_num_indexed_bit_pos_t const * : fr_table_ordered_num_by_longest_prefix,       \
         fr_table_num_indexed_t *               : fr_table_ordered_num_by_longest_prefix,       \
         fr_table_num_indexed_t const *         : fr_table_ordered_num_by_longest_prefix        \
)(_match_len, _table, _table ## _len, _name, _name_len, _def)
 
char const      *fr_table_ordered_str_by_num(fr_table_num_ordered_t const *table, size_t table_len,
                                             int number, char const *def);
char const      *fr_table_sorted_str_by_num(fr_table_num_sorted_t const *table, size_t table_len,
                                            int number, char const *def);
char const      *fr_table_ordered_str_by_ptr(fr_table_ptr_ordered_t const *table, size_t table_len,
                                             void const *ptr, char const *def);
char const      *fr_table_sorted_str_by_ptr(fr_table_ptr_sorted_t const *table, size_t table_len,
                                            void const *ptr, char const *def);
 
char const      *fr_table_indexed_str_by_bit_field(fr_table_num_indexed_bit_pos_t const *table, size_t table_len,
                                                   uint64_t number, char const *def);
 
char const      *fr_table_indexed_str_by_num(fr_table_num_indexed_t const *table, size_t table_len,
                                             unsigned int number, char const *def);
 
/** Convert an integer to a string
 *
 * @param[in] _table            to search in.
 * @param[in] _number           to resolve to a string.
 * @param[in] _def              Default string to return if there's no match.
 * @return
 *      - _def if _number name matched no entries in the table.
 *      - the string value of the matching entry.
 */
#define fr_table_str_by_value(_table, _number, _def) \
_Generic((_table), \
         fr_table_num_sorted_t const *          : fr_table_sorted_str_by_num,                   \
         fr_table_num_ordered_t const *         : fr_table_ordered_str_by_num,                  \
         fr_table_num_sorted_t *                : fr_table_sorted_str_by_num,                   \
         fr_table_num_ordered_t *               : fr_table_ordered_str_by_num,                  \
         fr_table_ptr_sorted_t const *          : fr_table_sorted_str_by_ptr,                   \
         fr_table_ptr_ordered_t const *         : fr_table_ordered_str_by_ptr,                  \
         fr_table_ptr_sorted_t *                : fr_table_sorted_str_by_ptr,                   \
         fr_table_ptr_ordered_t *               : fr_table_ordered_str_by_ptr,                  \
         fr_table_num_indexed_bit_pos_t *       : fr_table_indexed_str_by_bit_field,            \
         fr_table_num_indexed_bit_pos_t const * : fr_table_indexed_str_by_bit_field,            \
         fr_table_num_indexed_t *               : fr_table_indexed_str_by_num,                  \
         fr_table_num_indexed_t const *         : fr_table_indexed_str_by_num                   \
)(_table, _table ## _len, _number, _def)
 
#define TABLE_TYPE_NEEDLE_LEN_FUNC(_our_table_type, _our_name) \
static inline size_t _our_name(_our_table_type table, size_t table_len) \
{ \
        size_t i, max = 0; \
        for (i = 0; i < table_len; i++) if (table->name.len > max) max = table->name.len; \
        return max; \
}
 
TABLE_TYPE_NEEDLE_LEN_FUNC(fr_table_num_sorted_t const *, fr_table_num_sorted_max_needle_len)
TABLE_TYPE_NEEDLE_LEN_FUNC(fr_table_num_ordered_t const *, fr_table_num_ordered_max_needle_len)
TABLE_TYPE_NEEDLE_LEN_FUNC(fr_table_ptr_sorted_t const *, fr_table_ptr_sorted_max_needle_len)
TABLE_TYPE_NEEDLE_LEN_FUNC(fr_table_ptr_ordered_t const *, fr_table_ptr_ordered_max_needle_len)
TABLE_TYPE_NEEDLE_LEN_FUNC(fr_table_num_indexed_bit_pos_t const *, fr_table_num_indexed_bit_pos_max_needle_len)
TABLE_TYPE_NEEDLE_LEN_FUNC(fr_table_num_indexed_t const *, fr_table_num_indexed_max_needle_len)
 
#define fr_table_max_needle_len(_table) \
_Generic((_table), \
         fr_table_num_sorted_t const *          : fr_table_num_sorted_max_needle_len,           \
         fr_table_num_ordered_t const *         : fr_table_num_ordered_max_needle_len,          \
         fr_table_num_sorted_t *                : fr_table_num_sorted_max_needle_len,           \
         fr_table_num_ordered_t *               : fr_table_num_ordered_max_needle_len,          \
         fr_table_ptr_sorted_t const *          : fr_table_ptr_sorted_max_needle_len,           \
         fr_table_ptr_ordered_t const *         : fr_table_ptr_ordered_max_needle_len,          \
         fr_table_ptr_sorted_t *                : fr_table_ptr_sorted_max_needle_len,           \
         fr_table_ptr_ordered_t *               : fr_table_ptr_ordered_max_needle_len,          \
         fr_table_num_indexed_bit_pos_t *       : fr_table_num_indexed_bit_pos_max_needle_len,  \
         fr_table_num_indexed_bit_pos_t const * : fr_table_num_indexed_bit_pos_max_needle_len,  \
         fr_table_num_indexed_t *               : fr_table_num_indexed_max_needle_len,          \
         fr_table_num_indexed_t const *         : fr_table_num_indexed_max_needle_len           \
)(_table, _table ## _len)
 
#ifdef __cplusplus
}
#endif