make-vector documentation is wrong

make-vector documentation is wrong

[Daniel Colascione]

make-vector claims to "[r]eturn a newly created vector of length 
LENGTH", but we always return a singleton when asked to allocate a 
vector of length zero --- that is, (eq (make-vector 0 nil) (make-vector 
0 nil)). Is this behavior necessary? Is it contractual? We should fix 
either the docstring or the behavior of make-vector, and the latter 
seems better to me because it reduces the number of special cases in the 
system.

Re: make-vector documentation is wrong

[Paul Eggert]

On 5/14/20 6:36 PM, Daniel Colascione wrote:
> We should fix either the docstring or the behavior
> of make-vector, and the latter seems better to me because it reduces the number
> of special cases in the system.

That depends on how one counts special cases.

(make-string 0 0), (make-list 0 0), (vector), and (list) all have the property
that (make-vector 0 0) does - that is, each call returns the same empty object
each time. I imagine that make-vector was implemented to be consistent with the
other functions - at least, this behavior appears to be a conscious decision
rather than accidental. So it may make sense to change these functions'
documentation instead of their implementation's longstanding behavior.

Re: make-vector documentation is wrong

[Daniel Colascione]

On 5/14/20 7:46 PM, Paul Eggert wrote:
> On 5/14/20 6:36 PM, Daniel Colascione wrote:
>> We should fix either the docstring or the behavior
>> of make-vector, and the latter seems better to me because it reduces the number
>> of special cases in the system.
> 
> That depends on how one counts special cases.
> 
> (make-string 0 0), (make-list 0 0), (vector), and (list) all have the property
> that (make-vector 0 0) does - that is, each call returns the same empty object
> each time. I imagine that make-vector was implemented to be consistent with the
> other functions - at least, this behavior appears to be a conscious decision
> rather than accidental. So it may make sense to change these functions'
> documentation instead of their implementation's longstanding behavior.

Sure. We should make all of these things consistent. I'm not yet 
convinced that the special treatment of the zero-length object of any of 
these types actually helps though. Do we have any evidence that it does?

Re: make-vector documentation is wrong

[Paul Eggert]

On 5/14/20 7:59 PM, Daniel Colascione wrote:
> We should make all of these things consistent.

We can't reasonably change the behavior of (list) and of (make-list 0 0) in this
regard because there's just one empty list and lots of code relies on this fact.
So if we should make all of these things consistent then we should leave the
behavior alone and change the documentation to match the behavior.

Re: make-vector documentation is wrong

[Stefan Monnier]

> (make-string 0 0), (make-list 0 0), (vector), and (list) all have the property
> that (make-vector 0 0) does - that is, each call returns the same empty object
> each time. I imagine that make-vector was implemented to be consistent with the
> other functions - at least, this behavior appears to be a conscious decision
> rather than accidental. So it may make sense to change these functions'
> documentation instead of their implementation's longstanding behavior.

Actually, IIRC, for vectors it wasn't done "to make things consistent"
but because it simplified the memory management (IIRC the malloc-like
level needed its smallest object to be bigger than a 0-length vector,
so instead of adding an ad-hoc exception for 0-length vectors to
artificially use up more space, we decided to return a constant because
it was both simpler and more efficient).

I can't see any strong argument either for making sure (vector) returns
a fresh object nor for enforcing that it always returns the same object,
so I'd favor a documentation that says both things are valid
(i.e. Elisp code shouldn't rely on either behavior).


        Stefan

Re: make-vector documentation is wrong

[Paul Eggert]

On 5/14/20 8:41 PM, Stefan Monnier wrote:
> I can't see any strong argument either for making sure (vector) returns
> a fresh object nor for enforcing that it always returns the same object,
> so I'd favor a documentation that says both things are valid

Other parts of the documentation already refer to "the empty vector" and "the
empty string", implying that there is only one of each. Should they be rephrased
too? This would require quite a bit of rewording.

Emacs currently has exactly two empty strings (one unibyte and one multibyte),
so the phrase "the empty string" is wrong for the current implementation anyway.

It is a bit of a mess....

Re: make-vector documentation is wrong

[Eli Zaretskii]

> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Thu, 14 May 2020 23:34:12 -0700
> Cc: Daniel Colascione <dancol@dancol.org>,
>  Emacs developers <emacs-devel@gnu.org>
> 
> Emacs currently has exactly two empty strings (one unibyte and one multibyte),
> so the phrase "the empty string" is wrong for the current implementation anyway.

the documentation doesn't have to describe the implementation, it just
needs to tell enough for the Lisp programmers to understand how to use
this stuff.

Re: make-vector documentation is wrong

[Eli Zaretskii]

> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Thu, 14 May 2020 19:46:09 -0700
> Cc: Emacs developers <emacs-devel@gnu.org>
> 
> (make-string 0 0), (make-list 0 0), (vector), and (list) all have the property
> that (make-vector 0 0) does - that is, each call returns the same empty object
> each time. I imagine that make-vector was implemented to be consistent with the
> other functions - at least, this behavior appears to be a conscious decision
> rather than accidental. So it may make sense to change these functions'
> documentation instead of their implementation's longstanding behavior.

I'm fine with documenting this long-standing behavior (although we
should think whether this subtle issue should be in the doc strings or
only in the ELisp manual).