Re: set-text-properties, remove-set-properties, add-text-properties: 1) doc string 2) return value

[Luc Teirlinck]

Richard Stallman wrote:

   I can see from the C source that set-text-properties returns t
   if that text had any properties before, nil if it had none.

Well, it is a little bit more complex than that.  It returns nil if
the _entire_ string or buffer had no text properties and the
PROPERTIES arg is nil.  But it also returns nil if set-text-properties
specifies an empty interval.  I believe that the function returns nil
if it _knows_ that no text properties were changed, but that it makes
no effort to determine reliably whether any text properties were
changed.

There is an inconsistency.  If a string has no text properties and
set-text-properties wants to remove all text-properties from _part_ of
the string, the return value is nil (makes sense).  If it wants to
remove them from the entire string, the return value is t (makes no
sense):

ELISP> (setq str "123456789")
"123456789"
ELISP> (set-text-properties 0 9 nil str)
t
ELISP> (set-text-properties 0 8 nil str)
nil

This appears to be a small buglet.  The patch below fixes the buglet
and documents, I believe, the return value more accurately.  I can
install if desired.

===File ~/textprop.c-diff===================================
*** textprop.c  07 Aug 2005 10:28:42 -0500      1.143
--- textprop.c  29 Dec 2005 21:04:56 -0600      
***************
*** 1316,1323 ****
     properties PROPERTIES.  OBJECT is the buffer or string containing
     the text.  OBJECT nil means use the current buffer.
     SIGNAL_AFTER_CHANGE_P nil means don't signal after changes.  Value
!    is non-nil if properties were replaced; it is nil if there weren't
!    any properties to replace.  */
  
  Lisp_Object
  set_text_properties (start, end, properties, object, signal_after_change_p)
--- 1316,1323 ----
     properties PROPERTIES.  OBJECT is the buffer or string containing
     the text.  OBJECT nil means use the current buffer.
     SIGNAL_AFTER_CHANGE_P nil means don't signal after changes.  Value
!    is nil if the function _knows_ that it did not replace any
!    properties, non-nil otherwise.  */
  
  Lisp_Object
  set_text_properties (start, end, properties, object, signal_after_change_p)
***************
*** 1341,1347 ****
        && XFASTINT (end) == SCHARS (object))
      {
        if (! STRING_INTERVALS (object))
!       return Qt;
  
        STRING_SET_INTERVALS (object, NULL_INTERVAL);
        return Qt;
--- 1341,1347 ----
        && XFASTINT (end) == SCHARS (object))
      {
        if (! STRING_INTERVALS (object))
!       return Qnil;
  
        STRING_SET_INTERVALS (object, NULL_INTERVAL);
        return Qt;
============================================================