Simplify -cons-pair?

* dash.el (-cons-pair?): Simplify for speed.
* dev/examples.el (-cons-pair?): New test.

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

README.md

@@ -210,6 +210,7 @@ value rather than consuming a list to produce a single value.
 * [-is-prefix?](#-is-prefix-prefix-list) `(prefix list)`
 * [-is-suffix?](#-is-suffix-suffix-list) `(suffix list)`
 * [-is-infix?](#-is-infix-infix-list) `(infix list)`
+* [-cons-pair?](#-cons-pair-obj) `(obj)`
 
 ### Partitioning
 
@@ -1345,6 +1346,18 @@ Alias: `-is-infix-p`
 (-is-infix? '(3 4 5) '(1 2 3 4 5)) ;; => t
 ```
 
+#### -cons-pair? `(obj)`
+
+Return non-nil if `obj` is a true cons pair.
+That is, a cons (`a` . `b`) where `b` is not a list.
+Alias: `-cons-pair-p`.
+
+```el
+(-cons-pair? '(1 . 2)) ;; => t
+(-cons-pair? '(1 2)) ;; => nil
+(-cons-pair? '(1)) ;; => nil
+```
+
 
 ## Partitioning
 

dash.el

@@ -2724,14 +2724,12 @@ the new seed."
   (declare (debug (form form)))
   `(-unfold (lambda (it) ,form) ,seed))
 
-(defun -cons-pair? (con)
+(defun -cons-pair? (obj)
-  "Return non-nil if CON is true cons pair.
+  "Return non-nil if OBJ is a true cons pair.
-That is (A . B) where B is not a list.
+That is, a cons (A . B) where B is not a list.
-
+Alias: `-cons-pair-p'."
-Alias: `-cons-pair-p'"
   (declare (pure t) (side-effect-free t))
-  (and (listp con)
+  (nlistp (cdr-safe obj)))
-       (not (listp (cdr con)))))
 
 (defalias '-cons-pair-p '-cons-pair?)
 

dash.texi

@@ -1903,6 +1903,28 @@ Alias: @code{-is-infix-p}
 @end example
 @end defun
 
+@anchor{-cons-pair?}
+@defun -cons-pair? (obj)
+Return non-nil if @var{obj} is a true cons pair.
+That is, a cons (@var{a} . @var{b}) where @var{b} is not a list.
+Alias: @code{-cons-pair-p}.
+
+@example
+@group
+(-cons-pair? '(1 . 2))
+    @result{} t
+@end group
+@group
+(-cons-pair? '(1 2))
+    @result{} nil
+@end group
+@group
+(-cons-pair? '(1))
+    @result{} nil
+@end group
+@end example
+@end defun
+
 
 @node Partitioning
 @section Partitioning

dev/examples.el

@@ -618,7 +618,16 @@ value rather than consuming a list to produce a single value."
     (-is-infix? '(2 3 4) '(1 2 3 4 5)) => t
     (-is-infix? '(3 4 5) '(1 2 3 4 5)) => t
     (-is-infix? '(2 3 4) '(1 2 4 5)) => nil
-    (-is-infix? '(2 4) '(1 2 3 4 5)) => nil))
+    (-is-infix? '(2 4) '(1 2 3 4 5)) => nil)
+
+  (defexamples -cons-pair?
+    (-cons-pair? '(1 . 2)) => t
+    (-cons-pair? '(1 2)) => nil
+    (-cons-pair? '(1)) => nil
+    (-cons-pair? ()) => nil
+    (-cons-pair? "") => nil
+    (-cons-pair? '(1 2 . 3)) => nil
+    (-cons-pair? '(() . "")) => t))
 
 (def-example-group "Partitioning"
   "Functions partitioning the input list into a list of lists."