diff --git a/README.md b/README.md index 0611975..885f5f0 100644 --- a/README.md +++ b/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) ``` diff --git a/dash.el b/dash.el index 08f4697..746b15a 100644 --- a/dash.el +++ b/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))) diff --git a/dash.texi b/dash.texi index 31e1896..a3c22bd 100644 --- a/dash.texi +++ b/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) diff --git a/dev/examples.el b/dev/examples.el index e94a334..783b518 100644 --- a/dev/examples.el +++ b/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)