CMB(3)

NAME
cmb - combinatorics library

LIBRARY
libcmb

SYNOPSIS
#include <cmb.h>
int
cmb(struct cmb_config *config, uint32_t nitems, char *items[]);
uint64_t
cmb_count(struct cmb_config *config, uint32_t nitems);
char **
cmb_parse(struct cmb_config *config, int fd, uint32_t *nitems, uint32_t max);
char **
cmb_parse_file(struct cmb_config *config, char *path, uint32_t *nitems, uint32_t max);
int
cmb_print(struct cmb_config *config, uint64_t seq, uint32_t nitems, char *items[]);
const char *
cmb_version(int type);

/* OpenSSL bn(3) support */

int
cmb_bn(struct cmb_config *config, uint32_t nitems, char *items[]);
BIGNUM *
cmb_count_bn(struct cmb_config *config, uint32_t nitems);
int
cmb_print_bn(struct cmb_config *config, BIGNUM *seq, uint32_t nitems, char *items[]);

DESCRIPTION
The cmb library provides a light-weight, portable, and fast interface for enumerating combinations.

Anatomy of config argument to cmb*():

    struct cmb_config {
        uint8_t options;       /* CMB_OPT_* bitmask. Default 0 */
        char    *delimiter;    /* Item separator (default is " ") */
        char    *prefix;       /* Prefix for each combination */
        char    *suffix;       /* Suffix for each combination */
        uint32_t size_min;     /* Minimum elements in combination */
        uint32_t size_max;     /* Maximum elements in combination */
        uint64_t count;        /* Number of combinations */
        uint64_t start;        /* Starting combination */
        void *data;            /* Reserved for action callback */
        /*
         * cmb(3) function callback; called for each combination
         * (default is cmb_print()). If the return from action() is non-
         * zero, cmb() will stop calculation. The cmb() return value is
         * the first non-zero result from action(), zero otherwise.
         */
        CMB_ACTION((*action));
        /* OpenSSL bn(3) support */
        BIGNUM  *count_bn;     /* Number of combinations */
        BIGNUM  *start_bn;     /* Starting combination */
        /*
         * cmb_bn(3) function callback; called for each combination
         * (default is cmb_print_bn()). If the return from action_bn()
         * is non-zero, cmb_bn() will stop calculation. The cmb_bn()
         * return value is the first non-zero result from action_bn(),
         * zero otherwise.
         */
        CMB_ACTION_BN((*action_bn));
    };

The macro CMB_ACTION(x) is defined as:

    int x(struct cmb_config *config, uint64_t seq, uint32_t nitems,
        char *items[]);

When compiled with OpenSSL/LibreSSL support (default), the macro CMB_ACTION_BN(x) is defined as:

    int x(struct cmb_config *config, BIGNUM *seq, uint32_t nitems,
        char *items[]);

Macros for cmb_config options bitmask:

    CMB_OPT_DEBUG           /* Enable debugging */
    CMB_OPT_NULPARSE        /* NUL delimit cmb_parse*() */
    CMB_OPT_NULPRINT        /* NUL delimit cmb_print*() */
    CMB_OPT_EMPTY           /* Show empty set with no items */
    CMB_OPT_NUMBERS         /* Show combination sequence numbers */
    CMB_OPT_RESERVED        /* Reserved for future use by cmb(3) */
    CMB_OPT_OPTION1         /* Available (unused by cmb(3)) */
    CMB_OPT_OPTION2         /* Available (unused by cmb(3)) */

If CMB_OPT_DEBUG is set and cmb(3) was compiled with ‘CMB_DEBUG’, enable debugging information on stderr.

If CMB_OPT_NULPARSE is set, cmb_parse() and cmb_parse_file() will read items separated by ASCII NUL character (character code 0). Otherwise, newline (character code 10) is used.

If CMB_OPT_NULPRINT is set, cmb_print() and cmb_print_bn() will print combination items separated by ASCII NUL character (character code 0). Otherwise, delimiter is used and if unset, combinations are separated by a single space.

If CMB_OPT_EMPTY is set, the empty set (consisting of a single combination with no items) is enumerated by cmb() / cmb_bn() and counted by cmb_count() / cmb_count_bn().

If CMB_OPT_NUMBERS is set, print combination sequence number before calling action(). Combinations are calculated in arithmetic progression, providing predictable order. The sequence number can be used as start or start_bn value to begin at that combination. The sequence number precedes the prefix and is followed by a single space, regardless of delimiter.

For each combination, if prefix is non-NULL it is printed before the first item in each combination and suffix, if non-NULL, is printed after the last item.

To operate on only a subset or range of subsets, use size_min and size_max. Only combinations containing at minimum size_min items and at most size_max items will be calculated.

To limit the number of combinations that are calculated, set count or count_bn to a non-zero value.

If start or start_bn is greater than one, the cmb library will seek to that number combination before starting.

action_bn, count_bn, and start_bn are only available on platforms with OpenSSL/LibreSSL bn(3) and are used by cmb_bn() and cmb_count_bn() to overcome limitations by 64-bit integers.

cmb_version() takes CMB_VERSION or CMB_VERSION_LONG as type and returns string version. For unknown type, the text “not available” is returned.

HISTORY
The cmb library first appeared in FreeBSD 13.0.

AUTHORS
Devin Teske <dteske@FreeBSD.org>