From 50b4efd7e020670f98614aebcaf0980844c55aba Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Tue, 18 Jul 2017 06:25:31 -0700
Subject: new function: nth

Just the ANSI CL nth for lists.

* eval.c (eval_init): Register nth intrinsic.

* lib.c (nth): New function.

* lib.h (nth): Declared.

* share/txr/stdlib/place.tl (nth): New place macro,
trivially takes care of making nth an accessor.
Place macros are terrific!

* txr.1: Documented.
---
 eval.c                    |  1 +
 lib.c                     |  5 +++++
 lib.h                     |  1 +
 share/txr/stdlib/place.tl |  3 +++
 txr.1                     | 34 ++++++++++++++++++++++++++++++++++
 5 files changed, 44 insertions(+)

diff --git a/eval.c b/eval.c
index abd28344..058c7c09 100644
--- a/eval.c
+++ b/eval.c
@@ -5763,6 +5763,7 @@ void eval_init(void)
   reg_fun(intern(lit("butlast"), user_package), func_n2o(butlast, 1));
   reg_fun(intern(lit("nthlast"), user_package), func_n2(nthlast));
   reg_fun(intern(lit("nthcdr"), user_package), func_n2(nthcdr));
+  reg_fun(intern(lit("nth"), user_package), func_n2(nth));
   reg_fun(intern(lit("butlastn"), user_package), func_n2(butlastn));
   reg_fun(intern(lit("flatten"), user_package), func_n1(flatten));
   reg_fun(intern(lit("flatten*"), user_package), func_n1(lazy_flatten));
diff --git a/lib.c b/lib.c
index 58737f69..66142ec1 100644
--- a/lib.c
+++ b/lib.c
@@ -674,6 +674,11 @@ val nthcdr(val pos, val list)
   return list;
 }
 
+val nth(val pos, val list)
+{
+  return car(nthcdr(pos, list));
+}
+
 val nthlast(val pos, val list)
 {
   val iter = list;
diff --git a/lib.h b/lib.h
index a9024443..9b8c997b 100644
--- a/lib.h
+++ b/lib.h
@@ -540,6 +540,7 @@ loc lastcons(val list);
 val last(val list, val n);
 val nthlast(val pos, val list);
 val nthcdr(val pos, val list);
+val nth(val pos, val list);
 val butlastn(val n, val list);
 loc ltail(loc cons);
 val pop(val *plist);
diff --git a/share/txr/stdlib/place.tl b/share/txr/stdlib/place.tl
index 5b22e589..f8bbd580 100644
--- a/share/txr/stdlib/place.tl
+++ b/share/txr/stdlib/place.tl
@@ -972,3 +972,6 @@
     (have-n
      ^(sub ,obj 0 (- (max ,n 0))))
     (t ^(sub ,obj 0 -1))))
+
+(define-place-macro nth (index obj)
+  ^(car (nthcdr ,index ,obj)))
diff --git a/txr.1 b/txr.1
index ee903db4..41659f2e 100644
--- a/txr.1
+++ b/txr.1
@@ -18448,6 +18448,37 @@ and
 .code v
 are evaluated only once, in left-to-right order.
 
+.coNP Accessor @ nth
+.synb
+.mets (nth < index << object )
+.mets (set (nth < index << object ) << new-value )
+.syne
+.desc
+The
+.code nth
+function performs random access on a list, retrieving the n-th
+element indicated by the zero-based index value given by
+.metn index .
+The
+.meta index
+argument must be a non-negative integer.
+
+If
+.meta index
+indicates an element beyond the end of the list, then
+the function returns
+.codn nil .
+
+The following equivalences hold:
+
+.cblk
+  (nth 0 list) <--> (car 0) <--> (first list)
+  (nth 1 list) <--> (cadr list) <--> (second list)
+  (nth 2 list) <--> (caddr list) <--> (third list)
+
+  (nth x y) <--> (car (nthcdr x y))
+.cble
+
 .coNP Accessor @ nthcdr
 .synb
 .mets (nthcdr < index << list )
@@ -18465,12 +18496,15 @@ specifies a nonexistent cons beyond the end of the list,
 then
 .code nthcdr
 yields nil.
+
 The following equivalences hold:
 
 .cblk
   (nthcdr 0 list) <--> list
   (nthcdr 1 list) <--> (cdr list)
   (nthcdr 2 list) <--> (cddr list)
+
+  (car (nthcdr x y)) <--> (nth x y)
 .cble
 
 An
-- 
cgit v1.2.3