path: root/cppawk-iter.1

CPPAWK-ITER(1)                              Iteration                              CPPAWK-ITER(1)

NAME
       iter - powerful, user-extensible iteration language for Awk

SYNOPSIS
         #include <iter.h>

         // Simple, single-variable iteration

         doarray (key, value, arr)       // iterate over Awk assoc array
           statement

         dostring (idx, chr, str)        // iterate over string
           statement

         dofields (idx, val)             // iterate over $1, $2, ..
           statement

         // Multi-clause parallel and nested iteration

         loop (clause1, clause2, ...)    // Parallel iteration
           statement

         loop_nest (clause1,             // Nested iteration
                    clause2,
                    parallel (clause3,
                              clause4, ...),
                    ...)
           statement

         // Clauses for loop/loop_iter

         // numeric stepping clauses
         range (idx, from, to)
         range_step (idx, from, to, step)
         from (idx, from)
         from_step (idx, from, step)

         // general stepping clause
         first_then (var, first, then)

         // container traversal
         str (idx, ch, str)
         list (iter, var, list)
         fields (var)
         keys (key, array)

         // collect items into lists
         collect (var, expr)
         collect_plus (var, expr)

         // calculating clauses
         summing (var, expr)
         counting (var, expr)
         maximizing (var, expr)
         minimizing (var, expr)
         argmax (maxvar, arg, expr)
         argmin (minvar, arg, expr)

         // termination control clauses
         while (expr)
         until (expr)

         // parallel grouping combinator
         // clause1, clause2, ... are parallel even in a loop_nest.
         parallel (clause1, clause2, ...)

         // conditional combinator:
         // dependent clause steps/tests only whenever test is true
         if (test, clause)

OVERVIEW

       The  <iter.h>  header  provides constructs for expressing iteration. For simple loops that
       occur often -- iterating over an array, string or the positional fields --  several  dedi-
       cated  constructs  are  provided:  doarray,  dostring and dofields.  The separate <cons.h>
       header also provides simple iteration, for lists.

       In addition, <iter.h> provides a powerful general iteration facility which allows multiple
       variables  to be iterated in parallel or nested loops, stepping over various kinds of spa-
       ces, with special clauses for calculation, collecting lists, or controlling termination.

       Furthermore, a new clauses may easily be defined by the application programmer, simply  by
       defining six macros according to easy-to-follow rules.

       Clauses  are  susceptible to macro expansion: new clauses can be defined by writing macros
       that expand to existing clauses.

       In all of the iteration constructs of <iter.h> the variables which are supplied by the ap-
       plication are subject to assignment; the constructs do not bind these variables.  It is up
       to the application to control the scope of these variables.

       In general, immediately after the termination of these looping constructs,  the  variables
       explicitly specified by the application code remain visible, and continue to hold the val-
       ues they had immediately prior to loop termination.

SIMPLE ITERATION

   Macro doarray

       Syntax:

         doarray (key, value, arr)
           statement

       Description:

       The doarray macro executes the statement for every element of the associative  array  arr.
       Prior  to each iteration, the variables key and value are set to the next key and value to
       be visited.

       Awk associative arrays are not required to maintain order; thus doarray does not  traverse
       arr in any required order.

       Example:

         // assuming a is prepared like this:
         split("a:b:c", a, /:/)

         // possible output is
         // 3 c
         // 1 a
         // 2 b
         doarray (k, v, a)
           print k, v

   Macro dostring

       Syntax:

         dostring (idx, chr, str)
           statement

       Description:

       The dostring macro evaluates statement for all successive substrings of length 1 of string
       str.  The variable idx steps from 1 up to the length of str, and the chr variable takes on
       string  values  of  length  1. On the first iteration, chr contains the first character of
       str, then on the second iteration the second character and so forth.

       The str expression is evaluated only once.

       Example:

         // output is:
         // 1 a
         // 2 b
         // 3 c
         dostring (i, ch, "abc")
           print i, ch

   Macro dofields

       Syntax:

         dofields (idx, val)
           statement

       Description:

       The dofields macro iterates over the Awk positional fields, executing statement  for  each
       iteration.  The  idx variable is initialized to 1. Before every iteration, idx is compared
       compared to the current value of NR.  The iteration proceeds if i <= NR is true. After the
       execution of statement, idx is incremented by one.

       Before  each  iteration, val is set to the value of the positional field indicated by idx,
       namely $idx.

       Example:

         // set fields, assuming default FS
         $0 = "the quick brown fox"

         // output is:
         // 1 the
         // 2 quick
         // 3 brown
         // 4 fox
         dofields (i, v)
           print i, v

THE LOOP MACRO

Macro loop

       Syntax:

         loop (clause1, clause2, ...)
           statement

       Description: The loop macro repeatedly executes statement under the control of one or more
       clauses: clause1,

       Each  clause  contributes to the initial loop conditions, termination testing, and actions
       of the loop. Under loop the clauses act in parallel. The same clauses may be combined into
       a  nested  loop using the loop_nest macro. The term parallel here doesn't refer to concur-
       rent processing with threads or processors, but to the lock-step performance of loop iter-
       ation steps.

       Each clause communicates to loop the following:

       initialization
              What variable are to be be prepared with what initial values.

       termination
              What  conditions  will terminate the loop. Prior to each iteration, the termination
              test from every clause is interrogated. The loop statement  executes  only  if  all
              clauses indicate continued execution. If at least one clause calls for termination,
              the loop ends.

       preparation
              Whenever all clauses indicate that the loop continues, each clause has the opportu-
              nity to make some preparation prior to the execution of the loop, such as calculat-
              ing the values of some variables.

       stepping
              After the execution of each statement, each clause has the opportunity  to  perform
              some increment step.

       finalization
              When  the  loop terminates, some clauses execute some special code to bring about a
              needed final state in their variables, or for some other reason.

       The Awk break and continue statements are usable inside loop and behave like they  do  in-
       side  the  for construct. The break statement terminates the loop, and continue terminates
       the statement only, proceeding to the increment step which prepares for  the  next  itera-
       tion.

       Example:

         // step variable i from 1 to 5 by 1,
         // and variable j from 100 to 500 in steps of 100.

         // output is:
         // 1 100
         // 2 200
         // 3 300
         // 4 400
         // 5 500

         loop (range (i, 1, 5),
               range_step (j, 100, 500, 100))
         {
           print i, j
         }

       More example are given in the documentation of the clauses.

Macro loop_nest

       Syntax:

         loop_nest (clause1, clause2, ...)
           statement

       Description:  The  loop_nest  macro has a syntax resembling that of loop.  Unlike loop, it
       generates a nested loop: the logic of the clauses is arranged  into  loop  nestings.  Each
       clause  controls its own loop, in which the loops of subsequent clauses are nested. In ef-
       fect, the loop_nest syntax is a shorthand for writing:

         loop (clause1)
           loop (clause2)
             loop (clause3)
               ...
                 loop (clauseN)
                   statement

       There is a special clause called parallel which is useful inside  a  loop_nest.   Detailed
       documentation  for  it  is given in its own section. The parallel clause combines multiple
       clauses into a single clause, in such a way that those clauses are  executed  in  parallel
       regardless of which loop macro is used. Therefore the following equivalence also holds:

       Note:  consistently with the semantics of loop_nest being that of the above shorthand, the
       break and continue statements affect only the innermost loop  corresponding  to  the  last
       clause,  clauseN.   The  break  statement  only breaks out of that loop, and continue only
       skips to the iteration part of that loop.

       Note: the semantics of all clauses such as termination control clauses and list collection
       clauses must also be understood in terms of the nesting.  For instance if a collect clause
       is nested inside another loop which repeats three times, then that collection will be  re-
       peated  three  times:  the collection variable will be initialized three times, collection
       will be performed three times. Only the items collected by the last of the  three  repeti-
       tions of the collect loop will be retained. Or, if instead of collect, maximize is used to
       calculate a maximum value, then three maxima will be calculated over the three invocations
       of the maximizing loop, only the effect of the last of which will be retained in the vari-
       able which receives the maximum value.

         loop (clause1, clause2, ..., clause)
           statement

       may be achieved using

         loop_nest (parallel (clause1, clause2, ..., clauseN))
           statement

       Example:

         #include <iter.h>
         #include <cons.h>

         BEGIN {
           loop_nest (list(it, let, list("a", "b", "c")),
                      range(x, 1, 3))
             print let "-" x
         }

         Output:

         a-1
         a-2
         a-3
         b-1
         b-2
         b-3
         c-1
         c-2
         c-3

LOOP CLAUSES: NUMERIC AND GENERAL STEPPING

   Loop clauses range and range_step

       Syntax:

         range (idx, from, to)
         range_step (idx, from, to, step)

       Description:

       The range loop clause initializes the idx variable to the value of  the  from  expression.
       Prior  to  each  loop iteration, the expression idx <= (to) is tested. If it is false, the
       loop terminates.  After each execution of statement, idx is incremented by 1.  The to  ex-
       pression is reevaluated at the beginning of each iteration, so its value may change.

       The  range_step  clause is a variation of range which allows the amount added to idx to be
       specified as the step expression. The step expression is evaluated after  each  iteration,
       so its value may change. That value is added to idx .

       Note:  loop  clauses may not have optional arguments; it is not possible to write a single
       loop clause which takes an optional step size that defaults to 1.

   Loop clauses from and from_step

       Syntax:

         from (idx, from)
         from_step (idx, from, step)

       Description:

       The from clause is similar to range, except that the to expression is missing. The  clause
       performs  no  termination test; it initializes idx to the from value and then executes in-
       definitely, forever incrementing idx by one. In order for the loop to  terminate,  another
       clause must be present which requests termination, or else break must be used to terminate
       the loop abruptly.

       The from_step clause is a variant of from which allows the amount added to idx at the  in-
       crement  step  to  be determined by the value of the step expression, which is reevaluated
       each time.

LOOP CLAUSES: CONTAINER TRAVERSAL

   Loop clause str

       Syntax:

         str (idx, ch, str)

       Description:

       The str loop clause iterates over a string. The str expression is evaluated once  to  pro-
       duce  a  string.  The idx variable steps from 1 to up to the length of the string.  If the
       string is empty, the loop terminates without any iterations taking place.  Prior  to  each
       iteration, the ch variable is set to a one-character-long substring of the string starting
       at the idx position.

   Loop clause list

       Syntax:

         list (iter, var, list)

       Description:

       The list loop clause iterates over the elements of a list.  Note:  the  inclusion  of  the
       <iter.h> header does not make visible list manipulation libraries such as <cons.h>,

       The  iter  variable  is  initialized to list.  Prior to each iteration, iter is tested for
       termination as if using the endp function. If iter refers to a nonempty list, and thus it-
       eration  may  continue, then var is set to the first item in iter, car(iter), prior to the
       execution of the loop statement.

       After each iteration, iter is replaced with cdr(iter).

   Loop clause fields

       Syntax:

         fields (var)

       Description:

       The fields loop clause iterates over the Awk positional fields.  An  internal  counter  is
       initialized  to 1. Iteration proceeds if this counter is less than or equal to the current
       value of NF.  The counter is incremented by 1 after each iteration.

       Prior to the execution of the loop statement, var is set to the field indicated by the in-
       ternal counter.

   Loop clause keys

       Syntax:

         keys (key, array)

       Description:

       The keys loop clause iterates over the keys (indices) of an Awk associative array named by
       the array parameter. The key variable is set to each index in turn. The keys are not  vis-
       ited in any specific, required order.

LOOP CLAUSES: COLLECTION INTO LISTS

   Loop clauses collect and collect_plus

       Syntax:

         collect (var, expr)
         collect_plus (var, expr)

       Description:

       The  collect  clause  initializes  var to an empty bag object as if by using the list_init
       macro from <cons.h>.  The clause provides no termination test; if the only  clauses  in  a
       loop  are  collect clauses, then it will not terminate. Prior each execution of the state-
       ment, the collect clause evaluates expr and replaces var with a  new  bag  which  contains
       that  value, as if by the expression var = list_add(var, expr).  When the loop terminates,
       var is replaced with a list formed from the bag which it used to hold,  as  if  by  var  =
       list_end(var).  The effect is that var ends up with a list of the values of expr that were
       sampled before each iteration of the loop.

       The collect_plus clause is almost exactly the same as collect except in regard to the  fi-
       nal  behavior.  When the loop terminates, collect_plus collects the value of expr one more
       time prior to the conversion to list.  The effect is that var ends up with a list  of  all
       the  values  of  expr  that were sampled before each iteration of the loop, as well as one
       more sample of expr taken after loop termination.

LOOP CLAUSES: CALCULATION

   Loop clause summing

       Syntax:

         summing (var, expr)

       Description:

       The summing clause calculates the sum of the values of expr over the course of  the  loop.
       The  clause contains no provision for termination; if the only clause in a loop is summing
       then it will not terminate.

       The summing clause initializes var to zero. Prior to each execution of the  loop's  state-
       ment, expr is evaluated and its value added to to var.

       The  effect  is that after the loop terminates, var ends up with the sum of the samples of
       the value of expr from before each iteration of the loop.

   Loop clause counting

       Syntax:

         counting (var, expr)

       Description

       The counting clause initialized var to zero. Prior to each iteration of the loop, expr  is
       evaluated and if it yields a true value, then var is incremented.

       Thus, var ends up with a count of the number of iterations in which expr was true.

   Loop clauses minimizing and maximizing

       Syntax:

         maximizing (var, expr)
         minimizing (var, expr)

       Description:

       The  minimizing  and maximizing clauses initialize var to the value nil.  (See the cppawk-
       cons manual page for <cons.h>).

       Prior to each execution of the loop statement, var is updated as follows.  If var is  nil,
       then it receives the value of expr, thereby establishing that value as the hitherto calcu-
       lated minimum or maximum. If var is not already nil, then minimize  updates  it  with  the
       value of expr if that value is smaller than var, and similarly, maximize replaces var with
       the value of expr if that value is greater than var.

       Neither minimize nor maximize bring about loop termination.

       The effect of these clauses it to calculate the minimum or maximum observed  of  value  of
       expr  as  sampled before each execution of the loop statement.  If the loop never executes
       the statement, then var retains the nil value indicating that no minimum  or  maximum  had
       been found.

   Loop clauses argmax and argmin

       Syntax:

         argmax (maxvar, arg, expr)
         argmin (minvar, arg, expr)

       Description:

       The  argmax and argmin clauses calculate the value of the expression arg which is observed
       when the maximum or minimum value of expr occurs.

       This value of arg associated with the maximum or minimum value of  expr  then  appears  in
       maxvar  or minvar respectively. (The actual maximum or minimum value of expr is itself not
       made available.)

       The argmax and argmin operations are most useful when arg and expr are  related,  such  as
       expr being a function of arg.  For instance expr might be sin(x) and arg might be x.  This
       is the situation which inspires the term "argmax": arg is the argument of the  expr  func-
       tion.

       This  is not a requirement, though: arg and expr might simply be independent properties of
       the same datum. For  example,  arg  might  be  miles_per_gallon(car)  and  expr  might  be
       trunk_space(car)  in  which case argmax(mpg, miles_per_gallon(car), trunk_space(car)) will
       calculate and store into mpg the miles per gallon value of the car which has  the  maximum
       trunk  space, assuming that the loop will step the value of car through a sequence of dif-
       ferent car objects.

       Like minimize and maximize, these clauses never bring about loop termination.

       First, minvar or maxvar is initialized to the nil value.  (See the cppawk-cons manual page
       for <cons.h>).

       If  the  loop statement never executes, then these variables retain the nil value to indi-
       cate that no argument maximum or minimum was calculated.

       Prior to each execution of statement, expr is evaluated. If it  is  the  first  iteration,
       then maxvar or minvar is set to the value of arg.  If it is the second or subsequent iter-
       ation, then argmax sets maxvar to the value of arg if expr is higher than  the  previously
       seen  maximum  value of expr.  Likewise, argmin sets minvar to the value of arg if expr is
       lower than the previously seen minimum value of expr.

       Example:

       Find the values of x where the expression sin(x) * cos(x) has a maximum and minimum value,
       over the x range 0 to 3.14159 examined in increments of 0.001.

         #include <iter.h>

         BEGIN {
           loop (range_step  (x, 0, 3.14159, 0.001),
                 argmax      (mx, x, sin(x) * cos(x)),
                 argmin      (mi, x, sin(x) * cos(x)))
             ; // empty

           print "max x =", mx
           print "min x =", mi
         }

       Output:

         max x = 0.785
         min x = 2.356

LOOP CLAUSES: TERMINATION CONTROL

   Loop clauses while and until

       Syntax:

         while (expr)
         until (expr)

       Description:

       The while and until clauses provide a termination test to the loop.

       Prior to each iteration, expr is evaluated.

       Under the while clause, if expr is false. the loop terminates.

       Under the until clause, if expr is true, the loop terminates.

       Loop  terminations  are  short circuited among parallel clauses.  So that is to say, if an
       earlier clause indicates loop termination, then the termination tests of later clauses are
       not performed.  Moreover, the preparation actions of no clause are performed when the loop
       terminates; only if it has been confirmed that the statement is going to be executed,  due
       to the termination tests from all clauses reporting false, are the preparation actions ex-
       ecuted.  Therefore, in any iteration, later termination tests can rely on earlier termina-
       tion  tests  having  executed. For instance, if the success of an earlier termination test
       implies that a certain variable is safe to use in certain way, then  a  later  termination
       test may use it in that way. Likewise, loop preparations may rely on all termination tests
       having executed.

       All tests in loop, including while and until are top-of-loop tests: tests carried out  be-
       fore  every iteration, including the first.  A bottom-of-loop test is one which is carried
       out after each iteration, which is logically equivalent to a top-of-loop test which is un-
       conditionally  true  before  the  first iteration, and then turns into a bona fide test. A
       bottom-of-loop testing version of while or until isn't provided in <iter.h> but can be de-
       veloped  as  an  application-defined clause. It may also be simulated with the help of the
       first_then clause, according to this pattern:

         loop_for (first_then (first_iter, 1, 0),
                   while (first_iter || other_condition))
           statement

       Here, the first_iter flag is initialized to 1, and then after the first iteration steps to
       0.   Therefore  the  while  clause's  test  is always true before the first iteration, and
       other_condition isn't tested.

LOOP CLAUSES: COMBINATORS

   Loop clause parallel

       Syntax:

         parallel (clause1, clause2, ...)

       Description:

       The parallel construct may be used in the loop_nest macro, to indicate groups  of  clauses
       that should not be nested but treated in parallel.

       The  parallel  clause takes one or more arguments which are loop clauses.  It arranges for
       the argument clauses to be performed in parallel, just like the way clauses are treated by
       the loop construct.

       For instance, the structure:

         loop_nest (clause1,
                    parallel (clause2, clause3),
                    clause4)
           statement

       may be understood as equivalent to:

         loop (clause1)
           loop (clause2, clause3)
             loop (clause4)
               statement

       .bk Syntax:

         if (test, clause)

       Description:

       The if clause activates or deactivates the contained clause based on the value of the test
       expression.

       Firstly, the initializations of clause are performed unconditionally, as if  it  were  not
       embedded in if.

       Prior  to  every  iteration,  if the test expression is false, then clause's tests are not
       performed, and are assumed to be true. Thus while test is true, clause is  prevented  from
       being able to terminate the loop.

       Secondly,  prior  to  the execution of the loop statement, test is evaluated again. If the
       expression is false, then the preparation actions of clause are skipped.

       Lastly, prior to the execution of the iteration step actions.  expression is  false,  then
       the step actions of clause are skipped.

       Effectively, the clause is suspended while the test expression is false.

       Example:

       Print  a row number before the first element of every row. While this specific program can
       be coded much more succinctly, the goal is to demonstrate how the first_then clause is ac-
       tivated by the the condition i % 10 == 1.

         #include <iter.h>

         function row(pg)
         {
           if (pg > 1)
             print
           printf "r%03d", pg
           return pg
         }

         BEGIN {
           loop (range(i, 1, 100),
                 if (i % 10 == 1, first_then(pg, row(1), row(pg + 1))))
             printf " %3d", i
         }

       Output:

         r001   1   2   3   4   5   6   7   8   9  10
         r002  11  12  13  14  15  16  17  18  19  20
         r003  21  22  23  24  25  26  27  28  29  30
         r004  31  32  33  34  35  36  37  38  39  40
         r005  41  42  43  44  45  46  47  48  49  50
         r006  51  52  53  54  55  56  57  58  59  60
         r007  61  62  63  64  65  66  67  68  69  70
         r008  71  72  73  74  75  76  77  78  79  80
         r009  81  82  83  84  85  86  87  88  89  90
         r010  91  92  93  94  95  96  97  98  99 100

USER-DEFINED CLAUSES

       It is possible to define new clauses for the loop macro, in application code.

   Definition via Macro
       One  method  by  which a user defined loop clause is possible is by writing it as a macro.
       This is because clauses look like macro invocations and are susceptible to expansion.

       Example:

       Introduce a repeat(n) clause that repeats n times, where n is an expression.

         #define repeat(n) range(repeat_counter_ ## __LINE__, 1, (n))

   Primary Definition
       An entirely new loop clause is developed by writing six macros, one of which  is  required
       only if the egawk (Enhanced GNU Awk) implementation of Awk is being used.  The macros have
       names which are derived from the name of the clause.

       For example, to implement a clause called myclause, the following macros must be  written:
       __temp_myclause,  __init_myclause,  __test_myclause,  __prep_myclause, __fini_myclause and
       __step_myclause.  The __temp_myclause macro is not used unless the Awk  implementation  is
       egawk .

       All  six  macros  must  accept exactly the same arguments, and those will be the arguments
       that the clause will accept. They are described next:

       __temp_
              The temp macro must expand to a comma-terminated list of temporary  variable  names
              which  are needed by the clause. If the clause needs no hidden temporary variables,
              then this must expand to a terminating comma. Under the egawk implementation, these
              variables  will  be  accumulated  into a @let construct which precedes the loop, so
              that they are introduced as lexical variables visible only inside the loop.

       __init_
              The init macro must expand to an expression  which  performs  variable  initializa-
              tions.   If  the  clause requires no initializations, its expansion must be the nu-
              meric token 1.

       __test_
              The test macro must expand to an expression whose value is true if,  and  only  if,
              the clause wishes the loop to terminate. If the clause does not terminate the loop,
              the expansion of this macro must be the numeric token 1.

       __prep_
              The prep macro must expand to an expression that the clause needs to evaluate prior
              to  the  execution of the loop's iteration statement. This is evaluated only if all
              clauses have indicated that the loop isn't terminating, and hence the statement  is
              going to be executed.

       __fini_
              The  fini  macro  must expand to an expression that the clause needs to evaluate in
              the situation when the loop terminates. If any termination test from any clause  of
              a  loop indicates that the loop must terminate, then the loop statement will not be
              executed any more; instead, the fini expressions of all the clauses will be  evalu-
              ated,  and then the loop ends. If a clause does not have any fini action, then this
              macro must expand to the token 1.

       __step_
              The step macro must expand to an expression which is evaluated after  every  execu-
              tion  of  the loop statement , in order to prepare new values of loop variables for
              the next iteration.  Here is where numeric step variables are  incremented  and  so
              forth.  If the clause doesn't step, then this must expand to 1.

   Example: null clause
       Suppose  we wish to define a clause called null which takes no arguments and does nothing.
       A loop which contains only this clause iterates forever. If the clause  is  added  to  any
       loop, the semantics remains unchanged. The entire implementation is this:

         #include <iter.h>

         #define __temp_null ,
         #define __init_null 1
         #define __test_null 1
         #define __prep_null 1
         #define __fini_null 1
         #define __step_null 1

         BEGIN {
           loop (range (i, 1, 5),
                 null) // does nothing
             print i
         }

   Example: alpha-numeric stepping.

       Suppose we have a function nxstr(s, u) which behaves as follows, on these example inputs:

         nxstr("000", "999") -> "001"
         nxstr("007", "777") -> "010"
         nxstr("abc", "zzz") -> "abd"
         nxstr("xxx", "yyy") -> "xxy"
         nxstr("xxy", "yyy") -> "xya"
         nxstr("yyx", "yyy") -> "yyy"
         nxstr("yyy", "yyy") -> 0

       The  function nxstr implements a relation that could could be called "alpha-numeric step",
       where the second argument indicates limiting characters.

       A precise specification follows.  Firstly, both s and u are alphanumeric strings of  equal
       length, consisting of nothing but digits or the 26 letters of the English alphabet, in ei-
       ther upper or lower case. Furthermore, for every character in s, the corresponding charac-
       ter  in u is in the same category: digit, lower case or upper case, and that corresponding
       character has a rank at least as high.  For instance, where s has the character p , u  may
       have  the  characters p, q, r...  but not o because o has a lower rank, and not X or 7 be-
       cause they are in a different category.

       The u argument gives an upper limit. If s is identical to u then nxstr returns  0.  Other-
       wise  nxstr  returns  the  next alphanumeric string derived from s as follows: if the last
       character is equal to the corresponding one in s then it is reset to the  leading  element
       of the category, otherwise it is replaced by its successor. In the case when the character
       is reset, the procedure is repeated with the character to the left, to increment the  next
       digit. If that one is reset, then again, to the left and so forth.

       We  would  like  to  implement  a  loop clause which steps a variable s through a range of
       strings, as in alpha_range(s, "aa0", "cc9") to step through the strings "aa0", "aa1",  ...
       "aa9", "ab0", ... "ab9", ... "cc0", ... "cc9".

         #include <iter.h>

         // ... implementation of nxstr goes here ...

         #define __temp_alpha_range(s, from, to) 1
         #define __init_alpha_range(s, from, to) s = from
         #define __test_alpha_range(s, from, to) s
         #define __prep_alpha_range(s, from, to) 1
         #define __fini_alpha_range(s, from, to) 1
         #define __step_alpha_range(s, from, to) s = nxstr(s, to)

         BEGIN {
           loop (alpha_range (x, "aa0", "cc9"))
             print x
         }

       A working implementation of nxstr follows:

         // "register nextchar"
         function rn(x, y,
                     c)
         {
           nextchar[x] = y
           if (y in nextchar) {
             resetchar[x] = y
             for (c = y; nextchar[c] != y; c = nextchar[c])
               resetchar[c] = y
           }
         }

         BEGIN {
           rn("0", "1"); rn("1", "2"); rn("2", "3"); rn("3", "4");
           rn("4", "5"); rn("5", "6"); rn("6", "7"); rn("7", "8");
           rn("8", "9"); rn("9", "0");

           rn("a", "b"); rn("b", "c"); rn("c", "d"); rn("d", "e");
           rn("e", "f"); rn("f", "g"); rn("g", "h"); rn("h", "i");
           rn("i", "j"); rn("j", "k"); rn("k", "l"); rn("l", "m");
           rn("m", "n"); rn("n", "o"); rn("o", "p"); rn("p", "q");
           rn("q", "r"); rn("r", "s"); rn("s", "t"); rn("t", "u");
           rn("u", "v"); rn("v", "w"); rn("w", "x"); rn("x", "y");
           rn("y", "z"); rn("z", "a");

           rn("A", "B"); rn("B", "C"); rn("C", "D"); rn("D", "E");
           rn("E", "F"); rn("F", "G"); rn("G", "H"); rn("H", "I");
           rn("I", "J"); rn("J", "K"); rn("K", "L"); rn("L", "M");
           rn("M", "N"); rn("N", "O"); rn("O", "P"); rn("P", "Q");
           rn("Q", "R"); rn("R", "S"); rn("S", "T"); rn("T", "U");
           rn("U", "V"); rn("V", "W"); rn("W", "X"); rn("X", "Y");
           rn("Y", "Z"); rn("Z", "A");
         }

         function nxstr(str, upto,
                        l, sdig, udig, nxdig)
         {
           if (str == upto)
             return 0

           len = length(str)

           for (; len > 0; --len) {
             sdig = substr(str, len, 1)
             udig = substr(upto, len, 1)

             if (sdig == udig)
               nxdig = resetchar[sdig]
             else
               nxdig = nextchar[sdig]

             str = substr(str, 1, len - 1) nxdig substr(str, len + 1)

             if (sdig != udig)
                break
           }

           return str
         }

SEE ALSO
       cppawk(1)

BUGS
       The  parallel  clause cannot be used in loop, which prevents it from being useful in macro
       implementations of clauses. This is because it relies on a macro that is also  being  used
       in the expansion of loop .  This issue is discussed in the BUGS section of the main cppawk
       man page.

AUTHOR
       Kaz Kylheku <kaz@kylheku.com>

COPYRIGHT
       Copyright 2022, BSD2 License.

cppawk Libraries                          19 April 2022                            CPPAWK-ITER(1)