C-h f text-property-search:
text-property-search-forward is an autoloaded interactive
byte-compiled Lisp function in
(text-property-search-forward PROPERTY &optional VALUE PREDICATE NOT-CURRENT)
Search for next region of text where
PREDICATE returns non-nil for
PREDICATE is used to decide whether the value of
PROPERTY at a given
buffer position should be considered as a match for
VALUE defaults to nil if omitted.
PREDICATE is a function, it will be called with two arguments:
VALUE and the value of
PROPERTY at some buffer position. The function
should return non-
nil if these two values are to be considered a match.
Two special values of
PREDICATE can also be used:
t, that means the value of
to be considered a match.
nil (which is the default), the value of
match if it is not
VALUE. Furthermore, a nil
means that the match region ends where the value changes. For
instance, this means that if you loop with
(while (setq prop (text-property-search-forward 'face)) ...)
you will get all the distinct regions with non-nil
face values in
the buffer, and the
prop object will have the details about the
match. See the manual for more details and examples about how
NOT-CURRENT is non-
nil, current buffer position is not examined for
matches: the function will search for the first region that doesn’t
include point and has a value of
PROPERTY that matches
If no matches can be found, return
nil and don’t move point.
If found, move point to the end of the region and return a
prop-match object describing the match. To access the details
of the match, use
the buffer positions that limit the region, and
for the value of
PROPERTY in the region.
Other relevant functions are documented in the text-properties
group. Probably introduced at or before Emacs version 27.1.