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 ++++++++++++++++++++++++++++++++++++++
 testcases-cons | 20 ++++++++++++++++++++
 2 files changed, 58 insertions(+)

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)
diff --git a/testcases-cons b/testcases-cons
index 1295cbc..6d14401 100644
--- a/testcases-cons
+++ b/testcases-cons
@@ -579,3 +579,23 @@ BEGIN {
 nil
 nil
 nil
+--
+32:
+$cppawk '
+#include <cons.h>
+
+BEGIN {
+  print sexp(position(1, list(1, 2, 3)))
+  print sexp(position(2, list(1, 2, 3)))
+  print sexp(position(3, list(1, 2, 3)))
+  print sexp(position(4, list(1, 2, 3)))
+  print sexp(position(1, nil))
+  print sexp(position(nil, nil))
+}'
+:
+0
+1
+2
+nil
+nil
+nil
-- 
cgit v1.2.3