[elpa] externals/dash 66e3e94 079/316: Define -second-item through to -fifth-item

[ELPA Syncer]

branch: externals/dash
commit 66e3e9434135aaa02586a904ed0c33139468584f
Author: Wilfred Hughes <me@wilfred.me.uk>
Commit: Wilfred Hughes <me@wilfred.me.uk>

    Define -second-item through to -fifth-item
    
    cl-second is a very useful function that has no dash
    equivalent. Define functions for accessing the second, third, fourth
    and fifth items of a list.
---
 README.md       |  54 ++++++++++++++++
 dash.el         |  30 +++++++++
 dash.info       | 191 ++++++++++++++++++++++++++++++++++++--------------------
 dash.texi       |  78 +++++++++++++++++++++++
 dev/examples.el |  20 ++++++
 5 files changed, 307 insertions(+), 66 deletions(-)

diff --git a/README.md b/README.md
index 072ba9d..0f42e38 100644
--- a/README.md
+++ b/README.md
@@ -233,6 +233,10 @@ Other list functions not fit to be classified elsewhere.
 * [-some](#-some-pred-list) `(pred list)`
 * [-last](#-last-pred-list) `(pred list)`
 * [-first-item](#-first-item-list) `(list)`
+* [-second-item](#-second-item-arg1) `(arg1)`
+* [-third-item](#-third-item-arg1) `(arg1)`
+* [-fourth-item](#-fourth-item-list) `(list)`
+* [-fifth-item](#-fifth-item-list) `(list)`
 * [-last-item](#-last-item-list) `(list)`
 * [-butlast](#-butlast-list) `(list)`
 * [-sort](#-sort-comparator-list) `(comparator list)`
@@ -1732,6 +1736,8 @@ 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-arg1), 
[`-last-item`](#-last-item-list).
+
 (fn `list`)
 
 ```el
@@ -1740,6 +1746,54 @@ Return the first item of `list`, or nil on an empty list.
 (let ((list (list 1 2 3))) (setf (-first-item list) 5) list) ;; => '(5 2 3)
 ```
 
+#### -second-item `(arg1)`
+
+Return the second item of `list`, or nil if `list` is too short.
+
+See also: [`-third-item`](#-third-item-arg1).
+
+(fn `list`)
+
+```el
+(-second-item '(1 2 3)) ;; => 2
+(-second-item nil) ;; => nil
+```
+
+#### -third-item `(arg1)`
+
+Return the third item of `list`, or nil if `list` is too short.
+
+See also: [`-fourth-item`](#-fourth-item-list).
+
+(fn `list`)
+
+```el
+(-third-item '(1 2 3)) ;; => 3
+(-third-item nil) ;; => nil
+```
+
+#### -fourth-item `(list)`
+
+Return the fourth item of `list`, or nil if `list` is too short.
+
+See also: [`-fifth-item`](#-fifth-item-list).
+
+```el
+(-fourth-item '(1 2 3 4)) ;; => 4
+(-fourth-item nil) ;; => nil
+```
+
+#### -fifth-item `(list)`
+
+Return the fifth item of `list`, or nil if `list` is too short.
+
+See also: [`-last-item`](#-last-item-list).
+
+```el
+(-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.
diff --git a/dash.el b/dash.el
index ad56b8c..773f79a 100644
--- a/dash.el
+++ b/dash.el
@@ -582,6 +582,8 @@ Alias: `-any'"
 (defalias '-first-item 'car
   "Return the first item of LIST, or nil on an empty list.
 
+See also: `-second-item', `-last-item'.
+
 \(fn LIST)")
 
 ;; Ensure that calls to `-first-item' are compiled to a single opcode,
@@ -589,6 +591,34 @@ Alias: `-any'"
 (put '-first-item 'byte-opcode 'byte-car)
 (put '-first-item 'byte-compile 'byte-compile-one-arg)
 
+(defalias '-second-item 'cadr
+  "Return the second item of LIST, or nil if LIST is too short.
+
+See also: `-third-item'.
+
+\(fn LIST)")
+
+(defalias '-third-item 'caddr
+  "Return the third item of LIST, or nil if LIST is too short.
+
+See also: `-fourth-item'.
+
+\(fn LIST)")
+
+(defun -fourth-item (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)))))
+
+(defun -fifth-item (list)
+  "Return the fifth item of LIST, or nil if LIST is too short.
+
+See also: `-last-item'."
+  (declare (pure t) (side-effect-free t))
+  (car (cdr (cdr (cdr (cdr list))))))
+
 ;; TODO: emacs23 support, when dropped remove the condition
 (eval-when-compile
   (require 'cl)
diff --git a/dash.info b/dash.info
index 2a73830..b5ebaa7 100644
--- a/dash.info
+++ b/dash.info
@@ -1,4 +1,4 @@
-This is dash.info, produced by makeinfo version 6.5 from dash.texi.
+This is dash.info, produced by makeinfo version 6.4 from dash.texi.
 
 This manual is for ‘dash.el’ version 2.12.1.
 
@@ -1654,6 +1654,9 @@ Other list functions not fit to be classified elsewhere.
  -- Function: -first-item (list)
      Return the first item of LIST, or nil on an empty list.
 
+     See also: ‘-second-item’ (*note -second-item::), ‘-last-item’
+     (*note -last-item::).
+
      (fn LIST)
 
           (-first-item '(1 2 3))
@@ -1663,6 +1666,50 @@ Other list functions not fit to be classified elsewhere.
           (let ((list (list 1 2 3))) (setf (-first-item list) 5) list)
               ⇒ '(5 2 3)
 
+ -- Function: -second-item (arg1)
+     Return the second item of LIST, or nil if LIST is too short.
+
+     See also: ‘-third-item’ (*note -third-item::).
+
+     (fn LIST)
+
+          (-second-item '(1 2 3))
+              ⇒ 2
+          (-second-item nil)
+              ⇒ nil
+
+ -- Function: -third-item (arg1)
+     Return the third item of LIST, or nil if LIST is too short.
+
+     See also: ‘-fourth-item’ (*note -fourth-item::).
+
+     (fn LIST)
+
+          (-third-item '(1 2 3))
+              ⇒ 3
+          (-third-item nil)
+              ⇒ nil
+
+ -- Function: -fourth-item (list)
+     Return the fourth item of LIST, or nil if LIST is too short.
+
+     See also: ‘-fifth-item’ (*note -fifth-item::).
+
+          (-fourth-item '(1 2 3 4))
+              ⇒ 4
+          (-fourth-item nil)
+              ⇒ nil
+
+ -- Function: -fifth-item (list)
+     Return the fifth item of LIST, or nil if LIST is too short.
+
+     See also: ‘-last-item’ (*note -last-item::).
+
+          (-fifth-item '(1 2 3 4 5))
+              ⇒ 5
+          (-fifth-item nil)
+              ⇒ nil
+
  -- Function: -last-item (list)
      Return the last item of LIST, or nil on an empty list.
 
@@ -2714,7 +2761,7 @@ Index
                                                             (line  56)
 * -as->:                                 Threading macros.  (line  47)
 * -butlast:                              Other list operations.
-                                                            (line 264)
+                                                            (line 311)
 * -clone:                                Tree operations.   (line 123)
 * -compose:                              Function combinators.
                                                             (line  42)
@@ -2742,6 +2789,8 @@ Index
 * -each-while:                           Side-effects.      (line  19)
 * -elem-index:                           Indexing.          (line   9)
 * -elem-indices:                         Indexing.          (line  21)
+* -fifth-item:                           Other list operations.
+                                                            (line 291)
 * -filter:                               Sublist selection. (line   8)
 * -find-index:                           Indexing.          (line  32)
 * -find-indices:                         Indexing.          (line  60)
@@ -2751,13 +2800,15 @@ Index
 * -first-item:                           Other list operations.
                                                             (line 242)
 * -fix:                                  Other list operations.
-                                                            (line 300)
+                                                            (line 347)
 * -fixfn:                                Function combinators.
                                                             (line 177)
 * -flatten:                              List to list.      (line  33)
 * -flatten-n:                            List to list.      (line  55)
 * -flip:                                 Function combinators.
                                                             (line  81)
+* -fourth-item:                          Other list operations.
+                                                            (line 281)
 * -grade-down:                           Indexing.          (line  81)
 * -grade-up:                             Indexing.          (line  71)
 * -group-by:                             Partitioning.      (line 187)
@@ -2782,11 +2833,11 @@ Index
 * -last:                                 Other list operations.
                                                             (line 232)
 * -last-item:                            Other list operations.
-                                                            (line 254)
+                                                            (line 301)
 * -let:                                  Binding.           (line  66)
 * -let*:                                 Binding.           (line 200)
 * -list:                                 Other list operations.
-                                                            (line 287)
+                                                            (line 334)
 * -map:                                  Maps.              (line  10)
 * -map-first:                            Maps.              (line  38)
 * -map-indexed:                          Maps.              (line  66)
@@ -2846,6 +2897,8 @@ Index
 * -rpartial:                             Function combinators.
                                                             (line  20)
 * -same-items?:                          Predicates.        (line  72)
+* -second-item:                          Other list operations.
+                                                            (line 257)
 * -select-by-indices:                    Sublist selection. (line 169)
 * -select-column:                        Sublist selection. (line 199)
 * -select-columns:                       Sublist selection. (line 180)
@@ -2859,7 +2912,7 @@ Index
 * -some->:                               Threading macros.  (line  60)
 * -some->>:                              Threading macros.  (line  72)
 * -sort:                                 Other list operations.
-                                                            (line 274)
+                                                            (line 321)
 * -splice:                               Maps.              (line  91)
 * -splice-list:                          Maps.              (line 111)
 * -split-at:                             Partitioning.      (line   8)
@@ -2874,6 +2927,8 @@ Index
 * -take:                                 Sublist selection. (line 102)
 * -take-last:                            Sublist selection. (line 113)
 * -take-while:                           Sublist selection. (line 147)
+* -third-item:                           Other list operations.
+                                                            (line 269)
 * -tree-map:                             Tree operations.   (line  28)
 * -tree-map-nodes:                       Tree operations.   (line  39)
 * -tree-mapreduce:                       Tree operations.   (line  85)
@@ -3020,66 +3075,70 @@ Ref: -first52867
 Ref: -some53239
 Ref: -last53548
 Ref: -first-item53882
-Ref: -last-item54195
-Ref: -butlast54487
-Ref: -sort54734
-Ref: -list55222
-Ref: -fix55553
-Node: Tree operations56093
-Ref: -tree-seq56289
-Ref: -tree-map57147
-Ref: -tree-map-nodes57590
-Ref: -tree-reduce58445
-Ref: -tree-reduce-from59327
-Ref: -tree-mapreduce59928
-Ref: -tree-mapreduce-from60788
-Ref: -clone62074
-Node: Threading macros62402
-Ref: ->62547
-Ref: ->>63039
-Ref: -->63544
-Ref: -as->64105
-Ref: -some->64560
-Ref: -some->>64934
-Ref: -some-->65370
-Node: Binding65841
-Ref: -when-let66053
-Ref: -when-let*66538
-Ref: -if-let67066
-Ref: -if-let*67461
-Ref: -let68078
-Ref: -let*72871
-Ref: -lambda73812
-Node: Side-effects74614
-Ref: -each74808
-Ref: -each-while75215
-Ref: -each-indexed75575
-Ref: -dotimes76093
-Ref: -doto76396
-Node: Destructive operations76823
-Ref: !cons76996
-Ref: !cdr77202
-Node: Function combinators77397
-Ref: -partial77671
-Ref: -rpartial78066
-Ref: -juxt78468
-Ref: -compose78900
-Ref: -applify79458
-Ref: -on79905
-Ref: -flip80428
-Ref: -const80740
-Ref: -cut81084
-Ref: -not81570
-Ref: -orfn81880
-Ref: -andfn82314
-Ref: -iteratefn82809
-Ref: -fixfn83512
-Ref: -prodfn85081
-Node: Development86147
-Node: Contribute86496
-Node: Changes87244
-Node: Contributors90243
-Node: Index91867
+Ref: -second-item54298
+Ref: -third-item54578
+Ref: -fourth-item54856
+Ref: -fifth-item55122
+Ref: -last-item55384
+Ref: -butlast55676
+Ref: -sort55923
+Ref: -list56411
+Ref: -fix56742
+Node: Tree operations57282
+Ref: -tree-seq57478
+Ref: -tree-map58336
+Ref: -tree-map-nodes58779
+Ref: -tree-reduce59634
+Ref: -tree-reduce-from60516
+Ref: -tree-mapreduce61117
+Ref: -tree-mapreduce-from61977
+Ref: -clone63263
+Node: Threading macros63591
+Ref: ->63736
+Ref: ->>64228
+Ref: -->64733
+Ref: -as->65294
+Ref: -some->65749
+Ref: -some->>66123
+Ref: -some-->66559
+Node: Binding67030
+Ref: -when-let67242
+Ref: -when-let*67727
+Ref: -if-let68255
+Ref: -if-let*68650
+Ref: -let69267
+Ref: -let*74060
+Ref: -lambda75001
+Node: Side-effects75803
+Ref: -each75997
+Ref: -each-while76404
+Ref: -each-indexed76764
+Ref: -dotimes77282
+Ref: -doto77585
+Node: Destructive operations78012
+Ref: !cons78185
+Ref: !cdr78391
+Node: Function combinators78586
+Ref: -partial78860
+Ref: -rpartial79255
+Ref: -juxt79657
+Ref: -compose80089
+Ref: -applify80647
+Ref: -on81094
+Ref: -flip81617
+Ref: -const81929
+Ref: -cut82273
+Ref: -not82759
+Ref: -orfn83069
+Ref: -andfn83503
+Ref: -iteratefn83998
+Ref: -fixfn84701
+Ref: -prodfn86270
+Node: Development87336
+Node: Contribute87685
+Node: Changes88433
+Node: Contributors91432
+Node: Index93056
 
 End Tag Table
 
diff --git a/dash.texi b/dash.texi
index 35110d7..909fc7e 100644
--- a/dash.texi
+++ b/dash.texi
@@ -2631,6 +2631,8 @@ Return the last x in @var{list} where (@var{pred} x) is 
non-nil, else nil.
 @defun -first-item (list)
 Return the first item of @var{list}, or nil on an empty list.
 
+See also: @code{-second-item} (@pxref{-second-item}), @code{-last-item} 
(@pxref{-last-item}).
+
 (fn @var{list})
 
 @example
@@ -2649,6 +2651,82 @@ Return the first item of @var{list}, or nil on an empty 
list.
 @end example
 @end defun
 
+@anchor{-second-item}
+@defun -second-item (arg1)
+Return the second item of @var{list}, or nil if @var{list} is too short.
+
+See also: @code{-third-item} (@pxref{-third-item}).
+
+(fn @var{list})
+
+@example
+@group
+(-second-item '(1 2 3))
+    @result{} 2
+@end group
+@group
+(-second-item nil)
+    @result{} nil
+@end group
+@end example
+@end defun
+
+@anchor{-third-item}
+@defun -third-item (arg1)
+Return the third item of @var{list}, or nil if @var{list} is too short.
+
+See also: @code{-fourth-item} (@pxref{-fourth-item}).
+
+(fn @var{list})
+
+@example
+@group
+(-third-item '(1 2 3))
+    @result{} 3
+@end group
+@group
+(-third-item nil)
+    @result{} nil
+@end group
+@end example
+@end defun
+
+@anchor{-fourth-item}
+@defun -fourth-item (list)
+Return the fourth item of @var{list}, or nil if @var{list} is too short.
+
+See also: @code{-fifth-item} (@pxref{-fifth-item}).
+
+@example
+@group
+(-fourth-item '(1 2 3 4))
+    @result{} 4
+@end group
+@group
+(-fourth-item nil)
+    @result{} nil
+@end group
+@end example
+@end defun
+
+@anchor{-fifth-item}
+@defun -fifth-item (list)
+Return the fifth item of @var{list}, or nil if @var{list} is too short.
+
+See also: @code{-last-item} (@pxref{-last-item}).
+
+@example
+@group
+(-fifth-item '(1 2 3 4 5))
+    @result{} 5
+@end group
+@group
+(-fifth-item nil)
+    @result{} nil
+@end group
+@end example
+@end defun
+
 @anchor{-last-item}
 @defun -last-item (list)
 Return the last item of @var{list}, or nil on an empty list.
diff --git a/dev/examples.el b/dev/examples.el
index da9da38..ffdf587 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -723,6 +723,26 @@ new list."
     (-first-item nil) => nil
     (let ((list (list 1 2 3))) (setf (-first-item list) 5) list) => '(5 2 3))
 
+  (defexamples -second-item
+    (-second-item '(1 2 3)) => 2
+    (-second-item nil) => nil)
+
+  (defexamples -third-item
+    (-third-item '(1 2 3)) => 3
+    (-third-item nil) => nil)
+
+  (defexamples -third-item
+    (-third-item '(1 2 3)) => 3
+    (-third-item nil) => nil)
+
+  (defexamples -fourth-item
+    (-fourth-item '(1 2 3 4)) => 4
+    (-fourth-item nil) => nil)
+
+  (defexamples -fifth-item
+    (-fifth-item '(1 2 3 4 5)) => 5
+    (-fifth-item nil) => nil)
+
   (defexamples -last-item
     (-last-item '(1 2 3)) => 3
     (-last-item nil) => nil