iter: argmax, argmin: argument need not be variable!

1 files changed, 66 insertions, 36 deletions

diff --git a/cppawk-iter.1 b/cppawk-iter.1
index 531a4a6..d55fb24 100644
--- a/cppawk-iter.1
+++ b/cppawk-iter.1
@@ -86,8 +86,8 @@ iter \- powerful, user-extensible iteration language for Awk
   summing (\fIvar\fP, \fIexpr\fP)
   maximizing (\fIvar\fP, \fIexpr\fP)
   minimizing (\fIvar\fP, \fIexpr\fP)
-  argmax (\fImaxvar\fP, \fIargvar\fP, \fIexpr\fP)
-  argmin (\fIminvar\fP, \fIargvar\fP, \fIexpr\fP)
+  argmax (\fImaxvar\fP, \fIarg\fP, \fIexpr\fP)
+  argmin (\fIminvar\fP, \fIarg\fP, \fIexpr\fP)
 
   \fI// termination control clauses\fP
   while (\fIexpr\fP)
@@ -864,8 +864,8 @@ value indicating that no minimum or maximum had been found.
 .B Syntax:
 
 .ft B
-  argmax (\fImaxvar\fP, \fIargvar\fP, \fIexpr\fP)
-  argmin (\fIminvar\fP, \fIargvar\fP, \fIexpr\fP)
+  argmax (\fImaxvar\fP, \fIarg\fP, \fIexpr\fP)
+  argmin (\fIminvar\fP, \fIarg\fP, \fIexpr\fP)
 .ft R
 
 .B Description:
@@ -874,26 +874,71 @@ The
 .B argmax
 and
 .B argmin
-clauses calculate the value of a variable
-.I argvar
-which maximize or minimizes the value of
-.IR expr .
+clauses calculate the value of the expression
+.I arg
+which is observed when the maximum or minimum value of
+.I expr
+occurs.
 
-This maximum or minimum value appears in
+This value of
+.I arg
+associated with the maximum or minimum value of
+.I expr
+then appears in
 .I maxvar
 or
 .IR minvar
-respectively.
+respectively. (The actual maximum or minimum value of
+.I expr
+is itself not made available.)
 
-The purpose of the
-.I argvar
-argument is to name the variable that is being maximized
-or minimized. It is expected that the
+The
+.B argmax
+and
+.B argmin
+operations are most useful when
+.I arg
+and
+.I expr
+are related, such as
+.I expr
+being a function of
+.IR arg .
+For instance
+.I expr
+might be
+.BI sin( x )
+and
+.I arg
+might be
+.IR x .
+This is the situation which inspires the term "argmax":
+.I arg
+is the argument of the
 .I expr
-expression contains
-.I argvar
-and thus its value is dependent on
-.IR argvar .
+function.
+
+
+This is not a requirement, though:
+.I arg
+and
+.I expr
+might simply be independent properties of the same datum. For example,
+.I arg
+might be
+.BI miles_per_gallon( car )
+and
+.I expr
+might be
+.BI trunk_space( car )
+in which case
+.BI argmax( mpg ", miles_per_gallon(" car "), trunk_space(" car ))
+will calculate and store into
+.I mpg
+the miles per gallon value of the car which has the maximum trunk space,
+assuming that the loop will step the value of
+.I car
+through a sequence of different car objects.
 
 Like
 .B minimize
@@ -927,13 +972,13 @@ is evaluated. If it is the first iteration, then
 or
 .I minvar
 is set to the value of
-.IR argvar .
+.IR arg .
 If it is the second or subsequent iteration, then
 .B argmax
 sets
 .I maxvar
 to the value of
-.I argvar
+.I arg
 if
 .I expr
 is higher than the previously seen maximum value of
@@ -943,7 +988,7 @@ Likewise,
 sets
 .I minvar
 to the value of
-.I argvar
+.I arg
 if
 .I expr
 is lower than the previously seen minimum value of
@@ -960,21 +1005,6 @@ has a maximum and minimum value, over the
 range 0 to 3.14159 examined in
 increments of 0.001.
 
-Note that the variable used as
-.IR argvar ,
-namely
-.I x
-is made to vary by the use of a
-.I range_step
-clause. For
-.B argmax
-and
-.B argmin
-to be useful, the argument variable has to vary from one iteration
-to the next, and the
-.I expr
-has to be a function of that variable.
-
 .ft B
   #include <iter.h>