Function: next-single-char-property-change

next-single-char-property-change is a function defined in textprop.c.

Signature

(next-single-char-property-change POSITION PROP &optional OBJECT LIMIT)

Documentation

Return the position of next text property or overlay change for a specific property.

Scans characters forward from POSITION till it finds a change in the PROP property, then returns the position of the change. If the optional third argument OBJECT is a buffer (or nil, which means the current buffer), POSITION is a buffer position (integer or marker). If OBJECT is a string, POSITION is a 0-based index into it.

In a string, scan runs to the end of the string, unless LIMIT is non-nil. In a buffer, scan runs to end of buffer, unless LIMIT is non-nil. If the optional fourth argument LIMIT is non-nil, don't search past position LIMIT; return LIMIT if nothing is found before LIMIT. However, if OBJECT is a buffer and LIMIT is beyond the end of the buffer, this function returns point-max, not LIMIT.

The property values are compared with eq.

Aliases

allout-next-single-char-property-change (obsolete since 28.1)

Source Code

// Defined in /usr/src/emacs/src/textprop.c
{
  if (STRINGP (object))
    {
      position = Fnext_single_property_change (position, prop, object, limit);
      if (NILP (position))
	{
	  if (NILP (limit))
	    position = make_fixnum (SCHARS (object));
	  else
	    {
	      CHECK_FIXNUM (limit);
	      position = limit;
	    }
	}
    }
  else
    {
      Lisp_Object initial_value, value;
      ptrdiff_t count = SPECPDL_INDEX ();

      if (! NILP (object))
	CHECK_BUFFER (object);

      if (BUFFERP (object) && current_buffer != XBUFFER (object))
	{
	  record_unwind_current_buffer ();
	  Fset_buffer (object);
	}

      CHECK_FIXNUM_COERCE_MARKER (position);

      initial_value = Fget_char_property (position, prop, object);

      if (NILP (limit))
	XSETFASTINT (limit, ZV);
      else
	CHECK_FIXNUM_COERCE_MARKER (limit);

      if (XFIXNUM (position) >= XFIXNUM (limit))
	{
	  position = limit;
	  if (XFIXNUM (position) > ZV)
	    XSETFASTINT (position, ZV);
	}
      else
	while (true)
	  {
	    position = Fnext_char_property_change (position, limit);
	    if (XFIXNAT (position) >= XFIXNAT (limit))
	      {
		position = limit;
		break;
	      }

	    value = Fget_char_property (position, prop, object);
	    if (!EQ (value, initial_value))
	      break;

	    if (XFIXNAT (position) >= ZV)
	      break;
	  }

      position = unbind_to (count, position);
    }

  return position;
}