From 9de0b06e7470cc047c96c59befe40077dc72b98d Mon Sep 17 00:00:00 2001 From: =?utf8?q?Mattias=20Engdeg=C3=A5rd?= Date: Mon, 18 Jul 2022 12:19:38 +0200 Subject: [PATCH] Clarify `take` and `ntake` documentation (bug#56521) * doc/lispref/lists.texi (List Elements): Describe `ntake` better. * src/fns.c (Ftake, Fntake): Rephrase doc strings. --- doc/lispref/lists.texi | 13 +++++++++++-- src/fns.c | 5 +++-- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 2a9ad1d5e00..bfdba897848 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -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 diff --git a/src/fns.c b/src/fns.c index 84cfec6c3f0..7e78bba3a04 100644 --- a/src/fns.c +++ b/src/fns.c @@ -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); -- 2.39.5