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)
         records (file)

         // 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 clause records

       Syntax:

         records (file)

       Description:

       The  records clause is based on the Awk getline operator. The file expression is evaluated
       once, prior to the loop, and its value is remembered. Then prior to each iteration of  the
       loop,  a  record  is  read from the file using getline which has the effect of setting the
       record parameter $0 and the positional parameters $1, $2, ...  in the manner documented of
       the getline operator.

       When  the loop terminates normally, the file is closed, unless it is the string "-" denot-
       ing standard input.

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

   Loop clause if

       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)