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

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

[Drew Adams]

1. The set-text-properties doc string should say what the function returns.

2. Wouldn't it be more useful for set-text-properties,
remove-set-properties, and add-text-properties to return the modified OBJECT
(or nil if no modification occurred)? In case OBJECT is a buffer (or nil),
the modified buffer substring could be returned.

Perhaps it's too late to make the change in #2, if existing code depends on
the current value - but maybe not:

 - In the case of set-text-properties, that value is not even documented.

 - In the case of remove-set-properties and add-text-properties, perhaps
existing code only tests whether the returned value is null (instead of
testing equality with t).

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

[Stefan Monnier]

> 1. The set-text-properties doc string should say what the function returns.

Why?

> 2. Wouldn't it be more useful for set-text-properties,
> remove-set-properties, and add-text-properties to return the modified
> OBJECT (or nil if no modification occurred)? In case OBJECT is a buffer
> (or nil), the modified buffer substring could be returned.

Why would that be useful?


        Stefan

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

[Drew Adams]

    > 1. The set-text-properties doc string should say what the
    >    function returns.

    Why?

I should have said, "Does the value of set-text-properties change, or is it
always the same? If it changes, then the value is significant and it should
be documented."

    > 2. Wouldn't it be more useful for set-text-properties,
    > remove-set-properties, and add-text-properties to return the modified
    > OBJECT (or nil if no modification occurred)? In case OBJECT
    > is a buffer (or nil), the modified buffer substring could be returned.

    Why would that be useful?

Why is it useful for `push' and `pop' to return values that correspond to
the updated list and the removed car?

It would be convenient to say

 (setq foo (or (remove-text-properties start end props toto) ...))

Of course, you can always write

 (setq foo (if (remove-text-properties start end props toto)
               toto
              ...))

As for `push' and `pop' and many other "functions", returning a richer value
offers only a slight convenience, but why not?

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

[Richard M. Stallman]

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.

I am not sure whether this is useful to document.

Now is not the time to consider changing the return value.
This is not a new feature, and the current value is not a bug.

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;
============================================================

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

[Luc Teirlinck]

Richard Stallman wrote:

   I am not sure whether this is useful to document.

I do not believe that the return value is very useful (given that only
a nil return value provides any reliable info).  But since the return
value is sometimes nil and sometimes t, it might be good to document
it, just to avoid a situation where a user _believes_ that he
understands the return value and writes code relying on his mistaken
belief.

I could add:

    This function returns nil if it _knows_ that it did not replace any
    properties, non-nil otherwise.

to both the docstring and the Elisp manual, if desired.

Sincerely,

Luc.

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

[David Kastrup]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> I could add:
>
>     This function returns nil if it _knows_ that it did not replace any
>     properties, non-nil otherwise.
>
> to both the docstring and the Elisp manual, if desired.

Since the programmer has no way of guessing what a function might or
might not know (interesting word choice, anyway), this sounds like the
worst of all solutions.

I'd rather have "no useful value is returned".

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

[Kim F. Storm]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> 2. Wouldn't it be more useful for set-text-properties,
>> remove-set-properties, and add-text-properties to return the modified
>> OBJECT (or nil if no modification occurred)? In case OBJECT is a buffer
>> (or nil), the modified buffer substring could be returned.
>
> Why would that be useful?

Even if it was useful in some cases, it would be extremely wasteful in general.


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

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

[Drew Adams]

    >> 2. Wouldn't it be more useful for set-text-properties,
    >> remove-set-properties, and add-text-properties to return the modified
    >> OBJECT (or nil if no modification occurred)? In case OBJECT
    >> is a buffer (or nil), the modified buffer substring could be
returned.
    >
    > Why would that be useful?

    Even if it was useful in some cases, it would be extremely
    wasteful in general.

I believe you, but could you explain why, so I can learn? I don't know much
about how C interfaces with Lisp. Is it because a new OBJECT would in fact
need to be created? I was thinking that the operation could just return (the
equivalent of) a pointer to the original OBJECT. IOW, where is the waste?

I guess, in the case of a buffer, a new string would need to be created. Is
that what you meant, or is there also a problem when the OBJECT (string)
argument is explicitly supplied?

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

[Kevin Rodgers]

Drew Adams wrote:
>     >> 2. Wouldn't it be more useful for set-text-properties,
>     >> remove-set-properties, and add-text-properties to return the modified
>     >> OBJECT (or nil if no modification occurred)? In case OBJECT
>     >> is a buffer (or nil), the modified buffer substring could be
> returned.
>     >
>     > Why would that be useful?
> 
>     Even if it was useful in some cases, it would be extremely
>     wasteful in general.
> 
> I believe you, but could you explain why, so I can learn? I don't know much
> about how C interfaces with Lisp. Is it because a new OBJECT would in fact
> need to be created? I was thinking that the operation could just return (the
> equivalent of) a pointer to the original OBJECT. IOW, where is the waste?
> 
> I guess, in the case of a buffer, a new string would need to be created. Is
> that what you meant, or is there also a problem when the OBJECT (string)
> argument is explicitly supplied?

Exactly.  I think it should just return OBJECT, whether that is a buffer
(or the current buffer, when nil) or a string.

-- 
Kevin Rodgers

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

[Juri Linkov]

> Exactly.  I think it should just return OBJECT, whether that is a buffer
> (or the current buffer, when nil) or a string.

I agree.  `propertize' returns its input argument with added properties.
So why `add-text-properties', `set-text-properties' can't do the same.

-- 
Juri Linkov
http://www.jurta.org/emacs/

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

[Drew Adams]

    > Exactly.  I think it should just return OBJECT, whether that
    > is a buffer (or the current buffer, when nil) or a string.

    I agree.  `propertize' returns its input argument with added
    properties. So why `add-text-properties', `set-text-properties'
    can't do the same.

Sorry to stir this pot again. I have the same question now for
`put-text-property'. It seems to always return nil (true? - the doc string
says nothing about its return value).

What about giving some meaning to the value returned by `put-text-property'?
What about using a return value like `propertize' uses - that is, return the
OBJECT?

As Richard mentioned for `set-text-properties', this would be a new feature,
not a bug fix, so it would be for after the release.

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

[Stefan Monnier]

> What about giving some meaning to the value returned by `put-text-property'?
> What about using a return value like `propertize' uses - that is, return the
> OBJECT?

What for?  How often would that be useful?


        Stefan

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

[Kim F. Storm]

"Drew Adams" <drew.adams@oracle.com> writes:

> I guess, in the case of a buffer, a new string would need to be created.

Exactly -- and a string with all properties duplicated.  Very wasteful, since
the value would be discarded in most (all) cases.

> Is
> that what you meant, or is there also a problem when the OBJECT (string)
> argument is explicitly supplied?

Not performancewise, but IMO it is not worth the efforts to change this just
for the string case.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk