elisp: Property Search
31.19.3 Text Property Search Functions
--------------------------------------
In typical use of text properties, most of the time several or many
consecutive characters have the same value for a property. Rather than
writing your programs to examine characters one by one, it is much
faster to process chunks of text that have the same property value.
Here are functions you can use to do this. They use ‘eq’ for
comparing property values. In all cases, OBJECT defaults to the current
buffer.
For good performance, it’s very important to use the LIMIT argument
to these functions, especially the ones that search for a single
property—otherwise, they may spend a long time scanning to the end of
the buffer, if the property you are interested in does not change.
These functions do not move point; instead, they return a position
(or ‘nil’). Remember that a position is always between two characters;
the position returned by these functions is between two characters with
different properties.
-- Function: next-property-change pos &optional object limit
The function scans the text forward from position POS in the string
or buffer OBJECT until it finds a change in some text property,
then returns the position of the change. In other words, it
returns the position of the first character beyond POS whose
properties are not identical to those of the character just after
POS.
If LIMIT is non-‘nil’, then the scan ends at position LIMIT. If
there is no property change before that point, this function
returns LIMIT.
The value is ‘nil’ if the properties remain unchanged all the way
to the end of OBJECT and LIMIT is ‘nil’. If the value is
non-‘nil’, it is a position greater than or equal to POS. The
value equals POS only when LIMIT equals POS.
Here is an example of how to scan the buffer by chunks of text
within which all properties are constant:
(while (not (eobp))
(let ((plist (text-properties-at (point)))
(next-change
(or (next-property-change (point) (current-buffer))
(point-max))))
Process text from point to NEXT-CHANGE...
(goto-char next-change)))
-- Function: previous-property-change pos &optional object limit
This is like ‘next-property-change’, but scans back from POS
instead of forward. If the value is non-‘nil’, it is a position
less than or equal to POS; it equals POS only if LIMIT equals POS.
-- Function: next-single-property-change pos prop &optional object
limit
The function scans text for a change in the PROP property, then
returns the position of the change. The scan goes forward from
position POS in the string or buffer OBJECT. In other words, this
function returns the position of the first character beyond POS
whose PROP property differs from that of the character just after
POS.
If LIMIT is non-‘nil’, then the scan ends at position LIMIT. If
there is no property change before that point,
‘next-single-property-change’ returns LIMIT.
The value is ‘nil’ if the property remains unchanged all the way to
the end of OBJECT and LIMIT is ‘nil’. If the value is non-‘nil’,
it is a position greater than or equal to POS; it equals POS only
if LIMIT equals POS.
-- Function: previous-single-property-change pos prop &optional object
limit
This is like ‘next-single-property-change’, but scans back from POS
instead of forward. If the value is non-‘nil’, it is a position
less than or equal to POS; it equals POS only if LIMIT equals POS.
-- Function: next-char-property-change pos &optional limit
This is like ‘next-property-change’ except that it considers
overlay properties as well as text properties, and if no change is
found before the end of the buffer, it returns the maximum buffer
position rather than ‘nil’ (in this sense, it resembles the
corresponding overlay function ‘next-overlay-change’, rather than
‘next-property-change’). There is no OBJECT operand because this
function operates only on the current buffer. It returns the next
address at which either kind of property changes.
-- Function: previous-char-property-change pos &optional limit
This is like ‘next-char-property-change’, but scans back from POS
instead of forward, and returns the minimum buffer position if no
change is found.
-- Function: next-single-char-property-change pos prop &optional object
limit
This is like ‘next-single-property-change’ except that it considers
overlay properties as well as text properties, and if no change is
found before the end of the OBJECT, it returns the maximum valid
position in OBJECT rather than ‘nil’. Unlike
‘next-char-property-change’, this function _does_ have an OBJECT
operand; if OBJECT is not a buffer, only text-properties are
considered.
-- Function: previous-single-char-property-change pos prop &optional
object limit
This is like ‘next-single-char-property-change’, but scans back
from POS instead of forward, and returns the minimum valid position
in OBJECT if no change is found.
-- Function: text-property-any start end prop value &optional object
This function returns non-‘nil’ if at least one character between
START and END has a property PROP whose value is VALUE. More
precisely, it returns the position of the first such character.
Otherwise, it returns ‘nil’.
The optional fifth argument, OBJECT, specifies the string or buffer
to scan. Positions are relative to OBJECT. The default for OBJECT
is the current buffer.
-- Function: text-property-not-all start end prop value &optional
object
This function returns non-‘nil’ if at least one character between
START and END does not have a property PROP with value VALUE. More
precisely, it returns the position of the first such character.
Otherwise, it returns ‘nil’.
The optional fifth argument, OBJECT, specifies the string or buffer
to scan. Positions are relative to OBJECT. The default for OBJECT
is the current buffer.
Info Catalog
elisp: Changing Properties
elisp: Text Properties
elisp: Special Properties