From e33a5c88d867eb8b7e518d9ca113757d8c5f650e Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Thu, 14 Apr 2022 21:23:40 -0700
Subject: cons: document position function and add tests

---
 cppawk-cons.1 | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

(limited to 'cppawk-cons.1')

diff --git a/cppawk-cons.1 b/cppawk-cons.1
index 13b4dd8..563f449 100644
--- a/cppawk-cons.1
+++ b/cppawk-cons.1
@@ -1329,6 +1329,44 @@ returns
   member("a", list("c", "d")) -> nil
 .ft R
 
+.SS Function \fIposition\fP
+.bk
+.B Syntax:
+
+.ft B
+  position(\fIy\fP, \fIx\fP)
+.ft R
+
+.B Description
+
+The
+.B position
+function searches list
+.I x
+for the leftmost element which is
+.B equal
+to
+.IR y .
+If such an element is found, its zero-based
+position from the start of the list is returned.
+if it is the first element, then zero is returned;
+if it is second, then one, and so on.
+
+If
+.IR y
+is not found, then
+.B position
+returns
+.BR nil .
+
+.B Examples:
+
+.ft B
+  position(1, list(1, 2, 3)) -> 0
+  position(3, list(1, 2, 3)) -> 2
+  position(4, list(1, 2, 3)) -> nil
+.ft R
+
 .SH "SEE ALSO"
 
 cppawk(1)
-- 
cgit v1.2.3