Clean up cars and cdrs of -nth-item functions

* dash.el (-first-item, -second-item, -third-item, -fifth-item):
Declare as pure and side-effect-free.
(-fourth-item): Ditto.  Define as alias of cadddr in newer Emacsen.
(-last-item): Mention -first-item in docstring.

* dev/examples.el (-first-item, -second-item, -third-item)
(-fourth-item, -fifth-item, -last-item): Extend tests.

* README.md:
* dash.texi: Regenerate docs.

README.md

@@ -2095,11 +2095,11 @@ Return the last x in `list` where (`pred` x) is non-`nil`, else `nil`.
 
 Return the first item of `list`, or `nil` on an empty list.
 
-See also: [`-second-item`](#-second-item-list), [`-last-item`](#-last-item-list).
+See also: [`-second-item`](#-second-item-list), [`-last-item`](#-last-item-list), etc.
 
 ```el
-(-first-item '(1 2 3)) ;; => 1
-(-first-item nil) ;; => nil
+(-first-item ()) ;; => ()
+(-first-item '(1 2 3 4 5)) ;; => 1
 (let ((list (list 1 2 3))) (setf (-first-item list) 5) list) ;; => (5 2 3)
 ```
 
@@ -2107,53 +2107,59 @@ See also: [`-second-item`](#-second-item-list), [`-last-item`](#-last-item-list)
 
 Return the second item of `list`, or `nil` if `list` is too short.
 
-See also: [`-third-item`](#-third-item-list).
+See also: [`-first-item`](#-first-item-list), [`-third-item`](#-third-item-list), etc.
 
 ```el
-(-second-item '(1 2 3)) ;; => 2
-(-second-item nil) ;; => nil
+(-second-item ()) ;; => ()
+(-second-item '(1 2 3 4 5)) ;; => 2
+(let ((list (list 1 2))) (setf (-second-item list) 5) list) ;; => (1 5)
 ```
 
 #### -third-item `(list)`
 
 Return the third item of `list`, or `nil` if `list` is too short.
 
-See also: [`-fourth-item`](#-fourth-item-list).
+See also: [`-second-item`](#-second-item-list), [`-fourth-item`](#-fourth-item-list), etc.
 
 ```el
-(-third-item '(1 2 3)) ;; => 3
-(-third-item nil) ;; => nil
+(-third-item ()) ;; => ()
+(-third-item '(1 2)) ;; => ()
+(-third-item '(1 2 3 4 5)) ;; => 3
 ```
 
 #### -fourth-item `(list)`
 
 Return the fourth item of `list`, or `nil` if `list` is too short.
 
-See also: [`-fifth-item`](#-fifth-item-list).
+See also: [`-third-item`](#-third-item-list), [`-fifth-item`](#-fifth-item-list), etc.
 
 ```el
-(-fourth-item '(1 2 3 4)) ;; => 4
-(-fourth-item nil) ;; => nil
+(-fourth-item ()) ;; => ()
+(-fourth-item '(1 2 3)) ;; => ()
+(-fourth-item '(1 2 3 4 5)) ;; => 4
 ```
 
 #### -fifth-item `(list)`
 
 Return the fifth item of `list`, or `nil` if `list` is too short.
 
-See also: [`-last-item`](#-last-item-list).
+See also: [`-fourth-item`](#-fourth-item-list), [`-last-item`](#-last-item-list), etc.
 
 ```el
+(-fifth-item ()) ;; => ()
+(-fifth-item '(1 2 3 4)) ;; => ()
 (-fifth-item '(1 2 3 4 5)) ;; => 5
-(-fifth-item nil) ;; => nil
 ```
 
 #### -last-item `(list)`
 
 Return the last item of `list`, or `nil` on an empty list.
 
+See also: [`-first-item`](#-first-item-list), etc.
+
 ```el
-(-last-item '(1 2 3)) ;; => 3
-(-last-item nil) ;; => nil
+(-last-item ()) ;; => ()
+(-last-item '(1 2 3 4 5)) ;; => 5
 (let ((list (list 1 2 3))) (setf (-last-item list) 5) list) ;; => (1 2 5)
 ```
 

dash.el

@@ -929,10 +929,10 @@ This function's anaphoric counterpart is `--every'."
   "Return the last x in LIST where (PRED x) is non-nil, else nil."
   (--last (funcall pred it) list))
 
-(defalias '-first-item 'car
+(defalias '-first-item #'car
   "Return the first item of LIST, or nil on an empty list.
 
-See also: `-second-item', `-last-item'.
+See also: `-second-item', `-last-item', etc.
 
 \(fn LIST)")
 
@@ -940,40 +940,56 @@ See also: `-second-item', `-last-item'.
 ;; just like `car'.
 (put '-first-item 'byte-opcode 'byte-car)
 (put '-first-item 'byte-compile 'byte-compile-one-arg)
+(put '-first-item 'pure t)
+(put '-first-item 'side-effect-free t)
 
-(defalias '-second-item 'cadr
+(defalias '-second-item #'cadr
   "Return the second item of LIST, or nil if LIST is too short.
 
-See also: `-third-item'.
+See also: `-first-item', `-third-item', etc.
 
 \(fn LIST)")
 
+(put '-second-item 'pure t)
+(put '-second-item 'side-effect-free t)
+
 (defalias '-third-item
   (if (fboundp 'caddr)
       #'caddr
     (lambda (list) (car (cddr list))))
   "Return the third item of LIST, or nil if LIST is too short.
 
-See also: `-fourth-item'.
+See also: `-second-item', `-fourth-item', etc.
 
 \(fn LIST)")
 
-(defun -fourth-item (list)
+(put '-third-item 'pure t)
+(put '-third-item 'side-effect-free t)
+
+(defalias '-fourth-item
+  (if (fboundp 'cadddr)
+      #'cadddr
+    (lambda (list) (cadr (cddr list))))
   "Return the fourth item of LIST, or nil if LIST is too short.
 
-See also: `-fifth-item'."
-  (declare (pure t) (side-effect-free t))
-  (car (cdr (cdr (cdr list)))))
+See also: `-third-item', `-fifth-item', etc.
+
+\(fn LIST)")
+
+(put '-fourth-item 'pure t)
+(put '-fourth-item 'side-effect-free t)
 
 (defun -fifth-item (list)
   "Return the fifth item of LIST, or nil if LIST is too short.
 
-See also: `-last-item'."
+See also: `-fourth-item', `-last-item', etc."
   (declare (pure t) (side-effect-free t))
-  (car (cdr (cdr (cdr (cdr list))))))
+  (car (cddr (cddr list))))
 
 (defun -last-item (list)
-  "Return the last item of LIST, or nil on an empty list."
+  "Return the last item of LIST, or nil on an empty list.
+
+See also: `-first-item', etc."
   (declare (pure t) (side-effect-free t))
   (car (last list)))
 

dash.texi

@@ -3118,16 +3118,16 @@ Return the last x in @var{list} where (@var{pred} x) is non-@code{nil}, else @co
 @defun -first-item (list)
 Return the first item of @var{list}, or @code{nil} on an empty list.
 
-See also: @code{-second-item} (@pxref{-second-item}), @code{-last-item} (@pxref{-last-item}).
+See also: @code{-second-item} (@pxref{-second-item}), @code{-last-item} (@pxref{-last-item}), etc.
 
 @example
 @group
-(-first-item '(1 2 3))
-    @result{} 1
+(-first-item ())
+    @result{} ()
 @end group
 @group
-(-first-item nil)
-    @result{} nil
+(-first-item '(1 2 3 4 5))
+    @result{} 1
 @end group
 @group
 (let ((list (list 1 2 3))) (setf (-first-item list) 5) list)
@@ -3140,16 +3140,20 @@ See also: @code{-second-item} (@pxref{-second-item}), @code{-last-item} (@pxref{
 @defun -second-item (list)
 Return the second item of @var{list}, or @code{nil} if @var{list} is too short.
 
-See also: @code{-third-item} (@pxref{-third-item}).
+See also: @code{-first-item} (@pxref{-first-item}), @code{-third-item} (@pxref{-third-item}), etc.
 
 @example
 @group
-(-second-item '(1 2 3))
+(-second-item ())
+    @result{} ()
+@end group
+@group
+(-second-item '(1 2 3 4 5))
     @result{} 2
 @end group
 @group
-(-second-item nil)
-    @result{} nil
+(let ((list (list 1 2))) (setf (-second-item list) 5) list)
+    @result{} (1 5)
 @end group
 @end example
 @end defun
@@ -3158,16 +3162,20 @@ See also: @code{-third-item} (@pxref{-third-item}).
 @defun -third-item (list)
 Return the third item of @var{list}, or @code{nil} if @var{list} is too short.
 
-See also: @code{-fourth-item} (@pxref{-fourth-item}).
+See also: @code{-second-item} (@pxref{-second-item}), @code{-fourth-item} (@pxref{-fourth-item}), etc.
 
 @example
 @group
-(-third-item '(1 2 3))
-    @result{} 3
+(-third-item ())
+    @result{} ()
 @end group
 @group
-(-third-item nil)
-    @result{} nil
+(-third-item '(1 2))
+    @result{} ()
+@end group
+@group
+(-third-item '(1 2 3 4 5))
+    @result{} 3
 @end group
 @end example
 @end defun
@@ -3176,16 +3184,20 @@ See also: @code{-fourth-item} (@pxref{-fourth-item}).
 @defun -fourth-item (list)
 Return the fourth item of @var{list}, or @code{nil} if @var{list} is too short.
 
-See also: @code{-fifth-item} (@pxref{-fifth-item}).
+See also: @code{-third-item} (@pxref{-third-item}), @code{-fifth-item} (@pxref{-fifth-item}), etc.
 
 @example
 @group
-(-fourth-item '(1 2 3 4))
-    @result{} 4
+(-fourth-item ())
+    @result{} ()
 @end group
 @group
-(-fourth-item nil)
-    @result{} nil
+(-fourth-item '(1 2 3))
+    @result{} ()
+@end group
+@group
+(-fourth-item '(1 2 3 4 5))
+    @result{} 4
 @end group
 @end example
 @end defun
@@ -3194,16 +3206,20 @@ See also: @code{-fifth-item} (@pxref{-fifth-item}).
 @defun -fifth-item (list)
 Return the fifth item of @var{list}, or @code{nil} if @var{list} is too short.
 
-See also: @code{-last-item} (@pxref{-last-item}).
+See also: @code{-fourth-item} (@pxref{-fourth-item}), @code{-last-item} (@pxref{-last-item}), etc.
 
 @example
 @group
-(-fifth-item '(1 2 3 4 5))
-    @result{} 5
+(-fifth-item ())
+    @result{} ()
 @end group
 @group
-(-fifth-item nil)
-    @result{} nil
+(-fifth-item '(1 2 3 4))
+    @result{} ()
+@end group
+@group
+(-fifth-item '(1 2 3 4 5))
+    @result{} 5
 @end group
 @end example
 @end defun
@@ -3212,14 +3228,16 @@ See also: @code{-last-item} (@pxref{-last-item}).
 @defun -last-item (list)
 Return the last item of @var{list}, or @code{nil} on an empty list.
 
+See also: @code{-first-item} (@pxref{-first-item}), etc.
+
 @example
 @group
-(-last-item '(1 2 3))
-    @result{} 3
+(-last-item ())
+    @result{} ()
 @end group
 @group
-(-last-item nil)
-    @result{} nil
+(-last-item '(1 2 3 4 5))
+    @result{} 5
 @end group
 @group
 (let ((list (list 1 2 3))) (setf (-last-item list) 5) list)

dev/examples.el

@@ -1229,30 +1229,42 @@ related predicates."
     (--last (> (length it) 3) '("a" "looong" "word" "and" "short" "one")) => "short")
 
   (defexamples -first-item
-    (-first-item '(1 2 3)) => 1
-    (-first-item nil) => nil
-    (let ((list (list 1 2 3))) (setf (-first-item list) 5) list) => '(5 2 3))
+    (-first-item '()) => '()
+    (-first-item '(1 2 3 4 5)) => 1
+    (let ((list (list 1 2 3))) (setf (-first-item list) 5) list) => '(5 2 3)
+    (-first-item 1) !!> wrong-type-argument)
 
   (defexamples -second-item
-    (-second-item '(1 2 3)) => 2
-    (-second-item nil) => nil)
+    (-second-item '()) => '()
+    (-second-item '(1 2 3 4 5)) => 2
+    (let ((list (list 1 2))) (setf (-second-item list) 5) list) => '(1 5)
+    (-second-item '(1)) => '()
+    (-second-item 1) !!> wrong-type-argument)
 
   (defexamples -third-item
-    (-third-item '(1 2 3)) => 3
-    (-third-item nil) => nil)
+    (-third-item '()) => '()
+    (-third-item '(1 2)) => '()
+    (-third-item '(1 2 3 4 5)) => 3
+    (-third-item 1) !!> wrong-type-argument)
 
   (defexamples -fourth-item
-    (-fourth-item '(1 2 3 4)) => 4
-    (-fourth-item nil) => nil)
+    (-fourth-item '()) => '()
+    (-fourth-item '(1 2 3)) => '()
+    (-fourth-item '(1 2 3 4 5)) => 4
+    (-fourth-item 1) !!> wrong-type-argument)
 
   (defexamples -fifth-item
+    (-fifth-item '()) => '()
+    (-fifth-item '(1 2 3 4)) => '()
     (-fifth-item '(1 2 3 4 5)) => 5
-    (-fifth-item nil) => nil)
+    (-fifth-item 1) !!> wrong-type-argument)
 
   (defexamples -last-item
-    (-last-item '(1 2 3)) => 3
-    (-last-item nil) => nil
-    (let ((list (list 1 2 3))) (setf (-last-item list) 5) list) => '(1 2 5))
+    (-last-item '()) => '()
+    (-last-item '(1 2 3 4 5)) => 5
+    (let ((list (list 1 2 3))) (setf (-last-item list) 5) list) => '(1 2 5)
+    (-last-item '(1)) => 1
+    (-last-item 1) !!> wrong-type-argument)
 
   (defexamples -butlast
     (-butlast '(1 2 3)) => '(1 2)