Value comparison flags

ss_val_cmp_t is a collection of related C preprocessor symbols defined in ssval.h.

Synopsis:

SS_VAL_CMP_DFLT:

SS_VAL_CMP_SUBSTR: Strings: NUL terminated substring

SS_VAL_CMP_SUBMEM: Strings: binary comparison of substring

SS_VAL_CMP_RE: Strings: NUL terminated regular expression

SS_VAL_CMP_RE_EXTENDED:

SS_VAL_CMP_RE_ICASE:

SS_VAL_CMP_RE_NEWLINE:

SS_VAL_CMP_EQ: Link: compare with ss_pers_eq

SS_VAL_CMP_EQUAL: Link: compare with ss_pers_equal

Description: The various comparison functions (such as ss_val_cmp) can be influenced to use different algorithms during their operation by passing a bit vector describing the mode of operation. For ss_val_cmp the bit vector is contained in the first non-zero byte of the mask for each value being compared. Generally, if the flags bits are unrecognized or unsupported by a particular comparator a default algorithm is used.

The Default Algorithm

All comparison functions support a notion of a default comparison algorithm. This is indicated by setting all eight low-order bits in the flag, which can be done with the constant SS_VAL_CMP_DFLT.

String Comparisons

SS_VAL_CMP_SUBSTR: If the key value is a substring of the buffer being tested then the comparator
reports that they are equal. Otherwise the key is always considered to be less than the buffer. Both the key and buffer must be C-style NUL-terminated strings in order for a match to be detected.
SS_VAL_CMP_SUBMEM: This is similar to SS_VAL_CMP_SUBSTRING except the key and mask are considered to be
bytes of memory and all bytes of the key (including NUL bytes if any) must match at some location in buffer. If there is no match then the key is considered to be less than the buffer.
SS_VAL_CMP_RE: The key value is interpreted as a POSIX regular expression and if that regular
expression matches the contents of buffer then the comparator reports that key and buffer are equal, otherwise the key is considered to be less than the buffer.

If the SS_VAL_CMP_RE bit is set then the following bits are also supported (they actually each contain the SS_VAL_CMP_RE bit as well):

SS_VAL_CMP_RE_EXTENDED: The key value is treated as an extended regular expression rather than a basic
regular expression. Refer to the documentation for the REG_EXTENDED flag of regcomp for details.

SS_VAL_CMP_RE_ICASE: Ignore case when matching letters.

SS_VAL_CMP_RE_NEWLINE: Treat a newline in key as dividing buffer into multiple lines, so that a dollar
sign can match before the newline and a carat can match after. Also, don’t permit a dot to match a newline, and don’t permit a complemented character class (square brackets with a leading carat) to match a newline. Otherwise, newline acts like any other ordinary character.

Object Link Comparisons

SS_VAL_CMP_EQ: When comparing two persistent object links use ss_pers_eq. This is the default.

SS_VAL_CMP_EQUAL: When comparing two persistent object links use ss_pers_equal.

Issues: Since these bits must be passed as the bytes of a mask they must be only eight bits wide. The type, however, is defined as unsigned because of argument promotion rules.

See Also: