set_fields: document/test the start index param.

2 files changed, 38 insertions, 4 deletions

diff --git a/cppawk-cons.1 b/cppawk-cons.1
index 64939af..f41abe0 100644
--- a/cppawk-cons.1
+++ b/cppawk-cons.1
@@ -108,7 +108,7 @@ cons \- Lisp-like data representation and control flow macros
   \fI// Field/list conversion\fP
 
   fields([\fIi \fP[, \fIn\fP]]) \fI// convert Awk positional fields to list\fP
-  set_fields(\fIx\fP)     \fI// set Awk positional fields from list x\fP
+  set_fields(\fIx\fP[, \fIi\fP])\fI// set Awk positional fields from list x\fP
 
   \fI// list iteration\fP
 
@@ -1974,7 +1974,7 @@ or unboxed objects.
 
 .ft B
   fields([\fIi \fP[, \fIn\fP]])
-  set_fields(\fIx\fP)
+  set_fields(\fIx\fP[, \fIi\fP])
 .ft R
 
 .B Description
@@ -2013,9 +2013,16 @@ The
 .B set_fields
 function replaces the positional values with the contents of list
 .I x
-setting
+starting at position
+.I i
+which defaults to 1.
+The last element of the list becomes the last field, whose index
+therefore becomes the new value of the
 .B NF
-to the length of the list.
+variable.
+If
+.I i
+is less than 1, it is ignored and the default value 1 is used.
 
 Since the fields and
 .B NF
diff --git a/testcases-cons b/testcases-cons
index e5342c0..ebf9241 100644
--- a/testcases-cons
+++ b/testcases-cons
@@ -937,3 +937,30 @@ nil
 ("brown" "fox")
 ("fox")
 nil
+--
+47:
+$cppawk '
+#include <cons.h>
+
+BEGIN {
+  $0 = "the quick brown fox"
+  print sexp(fields())
+
+  set_fields(list(1, cons(1, 2), "foo", box_str("foo")), 3)
+
+  for (i = 1; i <= NF; i++)
+    print $i
+
+  set_fields(list("fast", "fox"), 2)
+  print sexp(fields())
+}'
+:
+("the" "quick" "brown" "fox")
+the
+quick
+1
+C1,1:12
+foo
+Tfoo
+("the" "fast" "fox")
+--