GNU Info
(elisp)Property Search
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 high 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 till 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,
`next-property-change' 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: next-single-property-change pos prop &optional object limit
The function scans the text forward from position POS in the
string or buffer OBJECT till it finds a change in the PROP
property, then returns the position of the change. In other
words, it 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-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: 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.
automatically generated by info2www version 1.2.2.9