From aeca5d81592de6bdbf485505fa867e36301d726a Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Thu, 14 Apr 2022 21:29:25 -0700
Subject: cons: document nth and nthcdr; add tests

Fixing semantics of nth for negative values.
---
 cppawk-cons.1 | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

(limited to 'cppawk-cons.1')

diff --git a/cppawk-cons.1 b/cppawk-cons.1
index 563f449..c1cb640 100644
--- a/cppawk-cons.1
+++ b/cppawk-cons.1
@@ -1367,6 +1367,76 @@ returns
   position(4, list(1, 2, 3)) -> nil
 .ft R
 
+.SS Functions \fInth\fP and \fInthcdr\fP
+.bk
+Syntax:
+
+.ft B
+  nth(\fIi\fP, \fIx\fP)
+  nthcdr(\fIi\fP, \fIx\fP)
+.ft R
+
+The
+.B nth
+and
+.B nthcdr
+functions perform zero-based indexing on lists.
+
+.B nth
+retrieves the
+.IR i -th
+item of the list
+.IR x .
+If
+.I i
+is zero, it finds the first item; if
+.I i
+is one, the second item and so forth.
+If there is no such item,
+.B nth
+returns
+.BR nil .
+
+.B nthcdr
+produces the suffix of the list
+.I x
+starting at the
+.IR i -th
+item, using the same numbering.
+
+Thus, there is a relationship between the two functions:
+
+.ft B
+  nth(\fIi\fP, \fIx\fP)  <--> car(nthcdr(\fIi\fP, \fIx\fP))
+.ft R
+
+.B Examples:
+
+.ft B
+  nth(1, list(1, 2, 3)) -> 2
+  nth(15, list(1, 2, 3)) -> nil
+  nthcdr(0, list(1, 2, 3)) -> (1 2 3)
+  nthcdr(2, list(1, 2, 3)) -> (3)
+.ft R
+
+.B cons
+cell of the list. The
+.B nth
+function finds the
+.B car
+of that
+.B cons
+cell.
+
+If
+.I i
+is a negative integer, then
+.B nth
+returns nil and
+.B nthcdr
+returns
+.BR x .
+
 .SH "SEE ALSO"
 
 cppawk(1)
-- 
cgit v1.2.3