The documentation is correct except that .NEXT() returns a number 0 / 1 rather than a string. But as it suggests, the function is mainly used internally to implement the next <iterator> statement. Unlike a normal for/next loop, there's no simplistic way to examine the next value without actually advancing to it.
However, you could create a do-it-yourself version of the foreach...next loop as follows:
dimx $sequence, ordmap(varstr;varstr)
map1 i,i,2
$sequence("aaa") = "one"
$sequence("bbb") = "two"
$sequence("ccc") = "three"
$sequence("xxx") = "done"
dimx $$i, iterator($sequence(), "", "", 0) ! stkey="", endkey="", fwd
do
i += 1
? "Loop iter #";i; .key($$i);" -> ";$$i
if .next($$i) then
? " next: ";.key($$i);" -> ";$$i
else
? "<end>"
exit
endif
loop
.run iternext
Loop iter # 1 aaa -> one
next: bbb -> two
Loop iter # 2 bbb -> two
next: ccc -> three
Loop iter # 3 ccc -> three
next: xxx -> done
Loop iter # 4 xxx -> done
<end>
Otherwise, it would be relatively simple (I think) to implement a
.PREV($$i) function, in which case your loop would look something like:
FOREACH $$i in $countyUnitTotals()
Trace.Print "A:"+.KEY($$i)
if .NEXT($$i) then
Trace.Print "B:"+.KEY($$i)
if .PREV($$i) = 0 then
? "<end>"
exit
endif
endif
NEXT $$i
I suppose we could take that one step further and implement a
.NEXTKEY($$i) function that combined the
.NEXT($$i),
.KEY($$i) and
.PREV($$i) functions, but it would probably need to be logically paired with a
.NEXTVALUE($$i) corresponding to
$$i to be complete. Is it worth it?
