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 ofregcomp
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:
- ss_pers_eq: 7.12: Determine link equality
- ss_pers_equal: 7.13: Determine object equality
- Values: Introduction for current chapter