procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clarify take and ntake documentation (bug#56521)

Browse source 
* doc/lispref/lists.texi (List Elements): Describe `ntake` better.
* src/fns.c (Ftake, Fntake): Rephrase doc strings.
This commit is contained in:
Mattias Engdegård 2022-07-18 12:19:38 +02:00
parent 6f7941272b
commit 9de0b06e74
2 changed files with 14 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
doc/lispref/lists.texi
View file

@ -344,7 +344,7 @@ If @var{n} is zero, @code{nthcdr} returns all of
This function returns the @var{n} first elements of @var{list}. Essentially,
it returns the part of @var{list} that @code{nthcdr} skips.
@code{take} returns @var{list} if it is shorter than @var{n} elements;
@code{take} returns @var{list} if shorter than @var{n} elements;
it returns @code{nil} if @var{n} is zero or negative.
@example
@ -366,7 +366,16 @@ it returns @code{nil} if @var{n} is zero or negative.
@defun ntake n list
This is a version of @code{take} that works by destructively modifying
the list structure of the argument. That makes it faster, but the
original value of @var{list} is lost.
original value of @var{list} may be lost.
@code{ntake} returns @var{list} unmodified if shorter than @var{n}
elements; it returns @code{nil} if @var{n} is zero or negative.
Otherwise, @var{list} is returned after being truncated to its first
@var{n} elements.
This means that it is usually a good idea to use the return value and
not just rely on the truncation effect unless @var{n} is known to be
positive.
@end defun
@defun last list &optional n

5
src/fns.c
View file

@ -1560,7 +1560,7 @@ substring_both (Lisp_Object string, ptrdiff_t from, ptrdiff_t from_byte,
DEFUN ("take", Ftake, Stake, 2, 2, 0,
doc: /* Return the first N elements of LIST.
If N is zero or negative, return nil.
If LIST is no more than N elements long, return it (or a copy). */)
If N is greater or equal to the length of LIST, return LIST (or a copy). */)
(Lisp_Object n, Lisp_Object list)
{
CHECK_FIXNUM (n);
@ -1590,7 +1590,8 @@ If LIST is no more than N elements long, return it (or a copy). */)
DEFUN ("ntake", Fntake, Sntake, 2, 2, 0,
doc: /* Modify LIST to keep only the first N elements.
If N is zero or negative, return nil.
If LIST is no more than N elements long, return it. */)
If N is greater or equal to the length of LIST, return LIST unmodified.
Otherwise, return LIST after truncating it. */)
(Lisp_Object n, Lisp_Object list)
{
CHECK_FIXNUM (n);