From 346aa8721ef405df343a5de9f4a754fdf262efab Mon Sep 17 00:00:00 2001
From: =?utf8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Sun, 28 Apr 2024 18:38:44 +0200
Subject: [PATCH] Add `drop` as alias for `nthcdr`

It's a common name for this function and symmetric with respect to
`take`.  It's also a lot less awkward to type and say.

* lisp/subr.el (drop): New alias.
* doc/lispref/lists.texi (List Elements): Document.  Mention the
equation tying `take` and `drop` together.
* etc/NEWS: Announce.

(cherry picked from commit 8718a7c7062eb562e2fda0dee5f7bfddb0861f1d)
---
 doc/lispref/lists.texi | 6 ++++++
 etc/NEWS               | 3 +++
 lisp/subr.el           | 1 +
 3 files changed, 10 insertions(+)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index ca42942250c..dce9115c61b 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -317,6 +317,7 @@ For historical reasons, it takes its arguments in the opposite order.
 @xref{Sequence Functions}.
 @end defun
 
+@findex drop
 @defun nthcdr n list
 This function returns the @var{n}th @sc{cdr} of @var{list}.  In other
 words, it skips past the first @var{n} links of @var{list} and returns
@@ -327,6 +328,8 @@ If @var{n} is zero, @code{nthcdr} returns all of
 @var{list}.  If the length of @var{list} is @var{n} or less,
 @code{nthcdr} returns @code{nil}.
 
+An alias for @code{nthcdr} is @code{drop}.
+
 @example
 @group
 (nthcdr 1 '(1 2 3 4))
@@ -350,6 +353,9 @@ it returns the part of @var{list} that @code{nthcdr} skips.
 @code{take} returns @var{list} if shorter than @var{n} elements;
 it returns @code{nil} if @var{n} is zero or negative.
 
+In general, @code{(append (take @var{n} @var{list}) (drop @var{n} @var{list}))}
+will return a list equal to @var{list}.
+
 @example
 @group
 (take 3 '(a b c d))
diff --git a/etc/NEWS b/etc/NEWS
index 794269b0149..4a96d47c1e4 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2151,6 +2151,9 @@ precedence over the variable when present.
 Mostly used internally to do a kind of topological sort of
 inheritance hierarchies.
 
++++
+** 'drop' is now an alias for the function 'nthcdr'.
+
 +++
 ** New polymorphic comparison function 'value<'.
 This function returns non-nil if the first argument is less than the
diff --git a/lisp/subr.el b/lisp/subr.el
index db09fd680d5..e5a8123c7e7 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2036,6 +2036,7 @@ instead; it will indirectly limit the specpdl stack size as well.")
 
 ;;;; Alternate names for functions - these are not being phased out.
 
+(defalias 'drop #'nthcdr)
 (defalias 'send-string #'process-send-string)
 (defalias 'send-region #'process-send-region)
 (defalias 'string= #'string-equal)
-- 
2.39.5