Changeset View
Changeset View
Standalone View
Standalone View
lib/libcmb/cmb.3
- This file was added.
Property | Old Value | New Value |
---|---|---|
svn:eol-style | null | native \ No newline at end of property |
svn:keywords | null | FreeBSD=%H \ No newline at end of property |
svn:mime-type | null | text/plain \ No newline at end of property |
.\" Copyright (c) 2018 Devin Teske <dteske@FreeBSD.org> | ||||||||||
.\" | ||||||||||
pauamma_gundo.com: Needs SPDX licence ID for new files. | ||||||||||
.\" Redistribution and use in source and binary forms, with or without | ||||||||||
.\" modification, are permitted provided that the following conditions | ||||||||||
.\" are met: | ||||||||||
.\" 1. Redistributions of source code must retain the above copyright | ||||||||||
.\" notice, this list of conditions and the following disclaimer. | ||||||||||
.\" 2. Redistributions in binary form must reproduce the above copyright | ||||||||||
.\" notice, this list of conditions and the following disclaimer in the | ||||||||||
.\" documentation and/or other materials provided with the distribution. | ||||||||||
.\" | ||||||||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | ||||||||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||||||||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | ||||||||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | ||||||||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||||||||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | ||||||||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||||||||
.\" SUCH DAMAGE. | ||||||||||
.\" | ||||||||||
.\" $FrauBSD: pkgcenter/depend/libcmb/cmb.3 2018-10-30 16:07:14 -0700 freebsdfrau $ | ||||||||||
.\" $FreeBSD$ | ||||||||||
.\" | ||||||||||
Done Inline ActionsMissing $FreeBSD$. 0mp: Missing $FreeBSD$. | ||||||||||
Not Done Inline ActionsNo longer required, and IIRC being removed. (Can someone confirm the latter?) pauamma_gundo.com: No longer required, and IIRC being removed. (Can someone confirm the latter?) | ||||||||||
.Dd October 30, 2018 | ||||||||||
.Dt CMB 3 | ||||||||||
Not Done Inline ActionsBump. pauamma_gundo.com: Bump. | ||||||||||
.Os | ||||||||||
.Sh NAME | ||||||||||
.Nm cmb | ||||||||||
.Nd combinatorics library | ||||||||||
.Sh LIBRARY | ||||||||||
.Lb libcmb | ||||||||||
.Sh SYNOPSIS | ||||||||||
.In cmb.h | ||||||||||
.Ft int | ||||||||||
.Fn cmb "struct cmb_config *config" "uint32_t nitems" "char *items[]" | ||||||||||
.Ft int | ||||||||||
.Fn cmb_print "uint32_t nitems" "char *items[]" | ||||||||||
.Ft uint64_t | ||||||||||
Not Done Inline ActionsOther than in passing in the description of CMB_OPT_EMPTY (special case), I see no description of this function or cmb_count_bn. Is the omission deliberate? pauamma_gundo.com: Other than in passing in the description of CMB_OPT_EMPTY (special case), I see no description… | ||||||||||
.Fn cmb_count "struct cmb_config *config" "uint32_t nitems" | ||||||||||
.Pp | ||||||||||
/* OpenSSL | ||||||||||
.Xr bn 3 | ||||||||||
support */ | ||||||||||
.Pp | ||||||||||
.Ft int | ||||||||||
.Fn cmb_bn "struct cmb_config *config" "uint32_t nitems" "char *items[]" | ||||||||||
.Ft "BIGNUM *" | ||||||||||
.Fn cmb_count_bn "struct cmb_config *config" "uint32_t nitems" | ||||||||||
.Sh DESCRIPTION | ||||||||||
The | ||||||||||
.Nm | ||||||||||
library provides a light-weight, | ||||||||||
portable, | ||||||||||
and fast interface for enumerating combinations. | ||||||||||
.Pp | ||||||||||
Anatomy of config argument to | ||||||||||
.Fn cmb* : | ||||||||||
.Bd -literal -offset indent | ||||||||||
struct cmb_config { | ||||||||||
uint8_t nul_terminate; /* Terminate combinations with NUL */ | ||||||||||
char *delimiter; /* Item separator (default is " ") */ | ||||||||||
char *prefix; /* Prefix for each combination */ | ||||||||||
char *suffix; /* Suffix for each combination */ | ||||||||||
uint32_t range_min; /* Minimum elements in combination */ | ||||||||||
uint32_t range_max; /* Maximum elements in combination */ | ||||||||||
uint64_t count; /* Number of combinations */ | ||||||||||
uint64_t start; /* Starting combination */ | ||||||||||
/* OpenSSL bn(3) support */ | ||||||||||
BIGNUM *count_bn; /* Number of combinations */ | ||||||||||
BIGNUM *start_bn; /* Starting combination */ | ||||||||||
/* | ||||||||||
* Function pointer; action to perform 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. | ||||||||||
*/ | ||||||||||
int (*action)(uint32_t nitems, char *items[]); | ||||||||||
}; | ||||||||||
.Ed | ||||||||||
.Pp | ||||||||||
If | ||||||||||
.Ar nul_terminate | ||||||||||
is non-zero, | ||||||||||
.Fn cmb_print | ||||||||||
will print combination items separated by ASCII NUL character | ||||||||||
.Pq character code 0 . | ||||||||||
Otherwise, | ||||||||||
if | ||||||||||
.Ar nul_terminate | ||||||||||
is zero | ||||||||||
.Pq default , | ||||||||||
.Ar delimiter | ||||||||||
is used and if unset, | ||||||||||
combinations are separated by a single space. | ||||||||||
.Pp | ||||||||||
For each combination, | ||||||||||
if | ||||||||||
.Ar prefix | ||||||||||
is non-NULL it is printed before the first item and | ||||||||||
if | ||||||||||
.Ar suffix | ||||||||||
is non-NULL it is printed after the last item. | ||||||||||
.Pp | ||||||||||
To operate on only a subset or range of subsets, | ||||||||||
use | ||||||||||
.Ar range_min | ||||||||||
and | ||||||||||
.Ar range_max . | ||||||||||
Only combinations containing at minimum | ||||||||||
.Ar range_min | ||||||||||
items and at most | ||||||||||
.Ar range_max | ||||||||||
items will be calculated. | ||||||||||
.Pp | ||||||||||
To limit the number of combinations that are calculated, | ||||||||||
set | ||||||||||
.Ar count | ||||||||||
to a non-zero value. | ||||||||||
.Pp | ||||||||||
If | ||||||||||
.Ar start | ||||||||||
is greater than one, | ||||||||||
the | ||||||||||
.Nm | ||||||||||
library will seek to that number combination before starting. | ||||||||||
.Pp | ||||||||||
.Ar count_bn | ||||||||||
and | ||||||||||
.Ar start_bn | ||||||||||
are only available on platforms with OpenSSL | ||||||||||
.Xr bn 3 | ||||||||||
and are used by | ||||||||||
.Fn cmb_bn | ||||||||||
and | ||||||||||
.Fn cmb_count_bn | ||||||||||
to overcome limitations by 64-bit integers. | ||||||||||
.Sh HISTORY | ||||||||||
The | ||||||||||
.Nm | ||||||||||
library first appeared in | ||||||||||
.Fx 13.0 . | ||||||||||
.Sh AUTHORS | ||||||||||
.An Devin Teske Aq Mt dteske@FreeBSD.org | ||||||||||
Not Done Inline Actions
pauamma_gundo.com: | ||||||||||
Not Done Inline Actions
pauamma_gundo.com: | ||||||||||
Not Done Inline Actions
pauamma_gundo.com: | ||||||||||
Not Done Inline Actions
pauamma_gundo.com: | ||||||||||
Not Done Inline Actions
For consistency with "at most" below pauamma_gundo.com: For consistency with "at most" below | ||||||||||
Not Done Inline ActionsI guess that should be 15.0 now. pauamma_gundo.com: I guess that should be 15.0 now. |
Needs SPDX licence ID for new files.