bug#20411: 24.3; Docstring of `next-single-property-change'

bug#20411: 24.3; Docstring of `next-single-property-change'

[Eli Barzilay]

The documentation for `next-single-property-change' has:

  Return nil if the property is constant all the way to the end of
  object.  If the value is non-nil, it is a position greater than
  position, never equal.

Both of these are wrong when a bound is given.

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!

bug#20411: 24.3; Docstring of `next-single-property-change'

[Eli Zaretskii]

> From: Eli Barzilay <eli@barzilay.org>
> Date: Thu, 23 Apr 2015 10:08:01 -0400
> 
> The documentation for `next-single-property-change' has:
> 
>   Return nil if the property is constant all the way to the end of
>   object.  If the value is non-nil, it is a position greater than
>   position, never equal.
> 
> Both of these are wrong when a bound is given.

Which is why the doc string says, right after the text you cited:

  If the optional fourth argument LIMIT is non-nil, don't search
  past position LIMIT; return LIMIT if nothing is found before LIMIT.

Isn't this exactly what you were looking for?

bug#20411: 24.3; Docstring of `next-single-property-change'

[Eli Barzilay]

Bah.  Yes, I completely missed that.  Looking at it again, I think that
it's that "never equal" that threw me off and write code that assumes
that.  To make it worse, it reads like an interface very similar to
`re-search-forward' up to that paragraph, and that "helped" me miss the
last sentence.

So I still think that it's confusing -- maybe "except when LIMIT is
non-nil" and possibly a warning that this is different from the
searching functions?

On Thu, Apr 23, 2015 at 11:31 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Eli Barzilay <eli@barzilay.org>
>> Date: Thu, 23 Apr 2015 10:08:01 -0400
>>
>> The documentation for `next-single-property-change' has:
>>
>>   Return nil if the property is constant all the way to the end of
>>   object.  If the value is non-nil, it is a position greater than
>>   position, never equal.
>>
>> Both of these are wrong when a bound is given.
>
> Which is why the doc string says, right after the text you cited:
>
>   If the optional fourth argument LIMIT is non-nil, don't search
>   past position LIMIT; return LIMIT if nothing is found before LIMIT.
>
> Isn't this exactly what you were looking for?



-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!

bug#20411: 24.3; Docstring of `next-single-property-change'

[Eli Zaretskii]

> Date: Thu, 23 Apr 2015 16:29:55 -0400
> From: Eli Barzilay <eli@barzilay.org>
> Cc: 20411@debbugs.gnu.org
> 
> So I still think that it's confusing -- maybe "except when LIMIT is
> non-nil" and possibly a warning that this is different from the
> searching functions?

Thanks, I clarified the doc strings of this and similar functions in
this respect.

bug#20411: 24.3; Docstring of `next-single-property-change'

[Eli Barzilay]

On Fri, Apr 24, 2015 at 4:28 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>
> Thanks, I clarified the doc strings of this and similar functions in
> this respect.

Thanks -- that looks more robust now.

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!