Changeset 558999f


Ignore:
Timestamp:
Aug 23, 2022, 7:24:40 AM (2 years ago)
Author:
Peter A. Buhr <pabuhr@…>
Branches:
ADT, ast-experimental, master, pthread-emulation
Children:
b59d6d1
Parents:
94eff4c
Message:

update user documentation for for-loop control

File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/user/user.tex

    r94eff4c r558999f  
    1111%% Created On       : Wed Apr  6 14:53:29 2016
    1212%% Last Modified By : Peter A. Buhr
    13 %% Last Modified On : Mon Feb 14 17:20:39 2022
    14 %% Update Count     : 5382
     13%% Last Modified On : Mon Aug 22 23:43:30 2022
     14%% Update Count     : 5503
    1515%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    1616
    … …  
    964964
    965965\begin{figure}
    966 \begin{tabular}{@{}l@{\hspace{25pt}}|l@{}}
    967 \multicolumn{1}{@{}c@{\hspace{25pt}}|}{loop control} & \multicolumn{1}{c@{}}{output} \\
     966\begin{tabular}{@{}l@{\hspace{40pt}}|l@{}}
     967\multicolumn{1}{@{}c@{\hspace{40pt}}|}{loop control} & \multicolumn{1}{c@{}}{output} \\
    968968\hline
    969969\begin{cfa}
    970 while ®($\,$)® { sout | "empty"; break; }
    971 do { sout | "empty"; break; } while ®($\,$)®;
    972 for ®($\,$)® { sout | "empty"; break; }
    973 for ( ®0® ) { sout | "A"; } sout | "zero";
    974 for ( ®1® ) { sout | "A"; }
    975 for ( ®10® ) { sout | "A"; }
    976 for ( ®= 10® ) { sout | "A"; }
    977 for ( ®1 ~= 10 ~ 2® ) { sout | "B"; }
    978 for ( ®10 -~= 1 ~ 2® ) { sout | "C"; }
    979 for ( ®0.5 ~ 5.5® ) { sout | "D"; }
    980 for ( ®5.5 -~ 0.5® ) { sout | "E"; }
    981 for ( ®i; 10® ) { sout | i; }
    982 for ( ®i; = 10® ) { sout | i; }
    983 for ( ®i; 1 ~= 10 ~ 2® ) { sout | i; }
    984 for ( ®i; 10 -~= 1 ~ 2® ) { sout | i; }
    985 for ( ®i; 0.5 ~ 5.5® ) { sout | i; }
    986 for ( ®i; 5.5 -~ 0.5® ) { sout | i; }
    987 for ( ®ui; 2u ~= 10u ~ 2u® ) { sout | ui; }
    988 for ( ®ui; 10u -~= 2u ~ 2u® ) { sout | ui; }
     970while () { sout | "empty"; break; }
     971do { sout | "empty"; break; } while ();
     972for () { sout | "empty"; break; }                                                       $\C[3in]{sout | nl | nlOff;}$
     973
     974for ( 0 ) { sout | "A"; } sout | "zero";                                        $\C{sout | nl;}$
     975for ( 1 ) { sout | "A"; }                                                                       $\C{sout | nl;}$
     976for ( 10 ) { sout | "A"; }                                                                      $\C{sout | nl;}$
     977for ( ~= 10 ) { sout | "A"; }                                                           $\C{sout | nl;}$
     978for ( 1 ~= 10 ~ 2 ) { sout | "B"; }                                                     $\C{sout | nl;}$
     979for ( 1 -~= 10 ~ 2 ) { sout | "C"; }                                            $\C{sout | nl;}$
     980for ( 0.5 ~ 5.5 ) { sout | "D"; }                                                       $\C{sout | nl;}$
     981for ( 0.5 -~ 5.5 ) { sout | "E"; }                                                      $\C{sout | nl;}$
     982for ( i; 10 ) { sout | i; }                                                                     $\C{sout | nl;}$
     983for ( i; ~= 10 ) { sout | i; }                                                          $\C{sout | nl;}$
     984for ( i; 1 ~= 10 ~ 2 ) { sout | i; }                                            $\C{sout | nl;}$
     985for ( i; 1 -~= 10 ~ 2 ) { sout | i; }                                           $\C{sout | nl;}$
     986for ( i; 0.5 ~ 5.5 ) { sout | i; }                                                      $\C{sout | nl;}$
     987for ( i; 0.5 -~ 5.5 ) { sout | i; }                                                     $\C{sout | nl;}$
     988for ( ui; 2u ~= 10u ~ 2u ) { sout | ui; }                                       $\C{sout | nl;}$
     989for ( ui; 2u -~= 10u ~ 2u ) { sout | ui; }                                      $\C{sout | nl | nl | nl;}$
     990
    989991enum { N = 10 };
    990 for ( ®N® ) { sout | "N"; }
    991 for ( ®i; N® ) { sout | i; }
    992 for ( ®i; N -~ 0® ) { sout | i; }
    993 const int start = 3, comp = 10, inc = 2;
    994 for ( ®i; start ~ comp ~ inc + 1® ) { sout | i; }
    995 for ( i; 1 ~ ®@® ) { if ( i > 10 ) break; sout | i; }
    996 for ( i; 10 -~ ®@® ) { if ( i < 0 ) break; sout | i; }
    997 for ( i; 2 ~ ®@® ~ 2 ) { if ( i > 10 ) break; sout | i; }
    998 for ( i; 2.1 ~ ®@® ~ ®@® ) { if ( i > 10.5 ) break; sout | i; i += 1.7; }
    999 for ( i; 10 -~ ®@® ~ 2 ) { if ( i < 0 ) break; sout | i; }
    1000 for ( i; 12.1 ~ ®@® ~ ®@® ) { if ( i < 2.5 ) break; sout | i; i -= 1.7; }
    1001 for ( i; 5 ®:® j; -5 ~ @ ) { sout | i | j; }
    1002 for ( i; 5 ®:® j; -5 -~ @ ) { sout | i | j; }
    1003 for ( i; 5 ®:® j; -5 ~ @ ~ 2 ) { sout | i | j; }
    1004 for ( i; 5 ®:® j; -5 -~ @ ~ 2 ) { sout | i | j; }
    1005 for ( i; 5 ®:® j; -5 ~ @ ) { sout | i | j; }
    1006 for ( i; 5 ®:® j; -5 -~ @ ) { sout | i | j; }
    1007 for ( i; 5 ®:® j; -5 ~ @ ~ 2 ) { sout | i | j; }
    1008 for ( i; 5 ®:® j; -5 -~ @ ~ 2 ) { sout | i | j; }
    1009 for ( i; 5 ®:® j; -5 -~ @ ~ 2 ®:® k; 1.5 ~ @ ) { sout | i | j | k; }
    1010 for ( i; 5 ®:® j; -5 -~ @ ~ 2 ®:® k; 1.5 ~ @ ) { sout | i | j | k; }
    1011 for ( i; 5 ®:® k; 1.5 ~ @ ®:® j; -5 -~ @ ~ 2 ) { sout | i | j | k; }
     992for ( N ) { sout | "N"; }                                                                       $\C{sout | nl;}$
     993for ( i; N ) { sout | i; }                                                                      $\C{sout | nl;}$
     994for ( i; -~ N ) { sout | i; }                                                           $\C{sout | nl | nl | nl;}$
     995
     996const int low = 3, high = 10, inc = 2;
     997for ( i; low ~ high ~ inc + 1 ) { sout | i; }                           $\C{sout | nl;}$
     998for ( i; 1 ~ @ ) { if ( i > 10 ) break; sout | i; }                     $\C{sout | nl;}$
     999for ( i; @ -~ 10 ) { if ( i < 0 ) break; sout | i; }            $\C{sout | nl;}$
     1000for ( i; 2 ~ @ ~ 2 ) { if ( i > 10 ) break; sout | i; }         $\C{sout | nl;}$
     1001for ( i; 2.1 ~ @ ~ @ ) { if ( i > 10.5 ) break; sout | i; i += 1.7; } $\C{sout | nl;}$
     1002for ( i; @ -~ 10 ~ 2 ) { if ( i < 0 ) break; sout | i; }        $\C{sout | nl;}$
     1003for ( i; 12.1 ~ @ ~ @ ) { if ( i < 2.5 ) break; sout | i; i -= 1.7; } $\C{sout | nl;}$
     1004for ( i; 5 : j; -5 ~ @ ) { sout | i | j; }                                      $\C{sout | nl;}$
     1005for ( i; 5 : j; @ -~ -5 ) { sout | i | j; }                                     $\C{sout | nl;}$
     1006for ( i; 5 : j; -5 ~ @ ~ 2 ) { sout | i | j; }                          $\C{sout | nl;}$
     1007for ( i; 5 : j; @ -~ -5 ~ 2 ) { sout | i | j; }                         $\C{sout | nl;}$
     1008for ( i; 5 : j; -5 ~ @ ) { sout | i | j; }                                      $\C{sout | nl;}$
     1009for ( i; 5 : j; @ -~ -5 ) { sout | i | j; }                                     $\C{sout | nl;}$
     1010for ( i; 5 : j; -5 ~ @ ~ 2 ) { sout | i | j; }                          $\C{sout | nl;}$
     1011for ( i; 5 : j; @ -~ -5 ~ 2 ) { sout | i | j; }                         $\C{sout | nl;}$
     1012for ( i; 5 : j; @ -~ -5 ~ 2 : k; 1.5 ~ @ ) { sout | i | j | k; } $\C{sout | nl;}$
     1013for ( i; 5 : j; @ -~ -5 ~ 2 : k; 1.5 ~ @ ) { sout | i | j | k; } $\C{sout | nl;}$
     1014for ( i; 5 : k; 1.5 ~ @ : j; @ -~ -5 ~ 2 ) { sout | i | j | k; } $\C{sout | nl;}\CRT$
    10121015\end{cfa}
    10131016&
    … …  
    10161019empty
    10171020empty
     1021
    10181022zero
    10191023A
    … …  
    1033103710 8 6 4 2
    10341038
     1039
    10351040N N N N N N N N N N
    103610410 1 2 3 4 5 6 7 8 9
    1037104210 9 8 7 6 5 4 3 2 1
     1043
    10381044
    103910453 6 9
    … …  
    10731079
    10741080Looping a fixed number of times, possibly with a loop index, occurs frequently.
    1075 \CFA condenses simply looping to facilitate coding speed and safety.
    1076 The \Indexc{for}, \Indexc{while}, and \Indexc{do} loop-control is augmented as follows \see{examples in \VRef[Figure]{f:LoopControlExamples}}:
    1077 \begin{itemize}[itemsep=0pt]
    1078 \item
    1079 ©0© is the implicit start value;
    1080 \item
    1081 ©1© is the implicit increment value.
    1082 \item
    1083 The up-to range uses operator ©+=© for increment;
    1084 \item
    1085 The down-to range uses operator ©-=© for decrement.
    1086 \item
    1087 The loop index is polymorphic in the type of the comparison value N (when the start value is implicit) or the start value M.
    1088 \begin{cfa}
    1089 for ( i; ®5® )                                  $\C[2.5in]{// typeof(5) i; 5 is comparison value}$
    1090 for ( i; ®1.5®~5.5~0.5 )                $\C{// typeof(1.5) i; 1.5 is start value}$
    1091 \end{cfa}
    1092 \item
    1093 An empty conditional implies comparison value of ©1© (true).
     1081\CFA condenses simply looping to facilitate coding speed and safety~\see{examples in \VRef[Figure]{f:LoopControlExamples}}.
     1082
     1083The \Indexc{for}, \Indexc{while}, and \Indexc{do} loop-control allow an empty conditional, which implies a comparison value of ©1© (true).
    10941084\begin{cfa}
    10951085while ( ®/*empty*/®  )                  $\C{// while ( true )}$
    … …  
    10971087do ... while ( ®/*empty*/®  )    $\C{// do ... while ( true )}$
    10981088\end{cfa}
    1099 \item
    1100 A comparison N is implicit up-to exclusive range [0,N\R{)}.
     1089
     1090The ©for© control has 4 new loop-control operators that are not overloadable:
     1091\begin{description}[itemsep=0pt,parsep=0pt]
     1092\item
     1093\Indexc{\~} (tilde) \Index{up-to exclusive range},
     1094\item
     1095\Indexc{\~=} (tilde equal) \Index{up-to inclusive range},
     1096\item
     1097\Indexc{-\~} (minus tilde) \Index{down-to exclusive range},
     1098\item
     1099\Indexc{-\~=} (minus tilde equal) \Index{down-to inclusive range}.
     1100\end{description}
     1101
     1102The ©for© index components, low (L), high (H), and increment (I), are optional.
     1103If missing:
     1104\begin{itemize}[itemsep=0pt,parsep=0pt]
     1105\item
     1106\Indexc{0} is the implicit low value.
     1107\item
     1108\Indexc{1} is the implicit increment value.
     1109\item
     1110The up-to range uses operator \Indexc{+=} for increment.
     1111\item
     1112The down-to range uses operator \Indexc{-=} for decrement.
     1113\end{itemize}
     1114
     1115If no type is specified for the loop index, it is the type of the high value H (when the low value is implicit) or the low value L.
     1116\begin{cfa}
     1117for ( ®5® )                                             $\C{// typeof(5) anonymous-index; 5 is high value}$
     1118for ( i; ®1.5® ~ 5.5 )                  $\C{// typeof(1.5) i; 1.5 is low value}$
     1119for ( ®int i®; 0 ~ 10 ~ 2 )             $\C{// int i; type is explicit}$
     1120\end{cfa}
     1121
     1122The following are examples for constructing different for-control:
     1123\begin{itemize}[itemsep=0pt]
     1124\item
     1125H is implicit up-to exclusive range [0,H\R{)}.
    11011126\begin{cfa}
    11021127for ( ®5® )                                             $\C{// for ( typeof(5) i; i < 5; i += 1 )}$
    11031128\end{cfa}
    11041129\item
    1105 A comparison ©=© N is implicit up-to inclusive range [0,N\R{]}.
    1106 \begin{cfa}
    1107 for ( ®=®5 )                                    $\C{// for ( typeof(5) i; i <= 5; i += 1 )}$
    1108 \end{cfa}
    1109 \item
    1110 The up-to range M ©~©\index{~@©~©} N means exclusive range [M,N\R{)}.
    1111 \begin{cfa}
    1112 for ( 1®~®5 )                                   $\C{// for ( typeof(1) i = 1; i < 5; i += 1 )}$
    1113 \end{cfa}
    1114 \item
    1115 The up-to range M ©~=©\index{~=@©~=©} N means inclusive range [M,N\R{]}.
    1116 \begin{cfa}
    1117 for ( 1®~=®5 )                                  $\C{// for ( typeof(1) i = 1; i <= 5; i += 1 )}$
    1118 \end{cfa}
    1119 \item
    1120 The down-to range M ©-~©\index{-~@©-~©} N means exclusive range [N,M\R{)}.
    1121 \begin{cfa}
    1122 for ( 1®-~®5 )                                  $\C{// for ( typeof(1) i = 5; i > 0; i -= 1 )}$
    1123 \end{cfa}
    1124 \item
    1125 The down-to range M ©-~=©\index{-~=@©-~=©} N means inclusive range [N,M\R{]}.
    1126 \begin{cfa}
    1127 for ( 1®-~=®5 )                                 $\C{// for ( typeof(1) i = 5; i >= 0; i -= 1 )}$
     1130©~=© H is implicit up-to inclusive range [0,H\R{]}.
     1131\begin{cfa}
     1132for ( ®~=® 5 )                                  $\C{// for ( typeof(5) i; i <= 5; i += 1 )}$
     1133\end{cfa}
     1134\item
     1135L ©~©\index{~@©~©} H is explicit up-to exclusive range [L,H\R{)}.
     1136\begin{cfa}
     1137for ( 1 ®~® 5 )                                 $\C{// for ( typeof(1) i = 1; i < 5; i += 1 )}$
     1138\end{cfa}
     1139\item
     1140L ©~=©\index{~=@©~=©} H is explicit up-to inclusive range [L,H\R{]}.
     1141\begin{cfa}
     1142for ( 1 ®~=® 5 )                                        $\C{// for ( typeof(1) i = 1; i <= 5; i += 1 )}$
     1143\end{cfa}
     1144\item
     1145L ©-~©\index{-~@©-~©} H is explicit down-to exclusive range [H,L\R{)}, where L and H are implicitly interchanged to make the range down-to.
     1146\begin{cfa}
     1147for ( 1 ®-~® 5 )                                        $\C{// for ( typeof(1) i = 5; i > 0; i -= 1 )}$
     1148\end{cfa}
     1149\item
     1150L ©-~=©\index{-~=@©-~=©} H is explicit down-to inclusive range [H,L\R{]}, where L and H are implicitly interchanged to make the range down-to.
     1151\begin{cfa}
     1152for ( 1 ®-~=® 5 )                                       $\C{// for ( typeof(1) i = 5; i >= 0; i -= 1 )}$
    11281153\end{cfa}
    11291154\item
    11301155©@© means put nothing in this field.
    11311156\begin{cfa}
    1132 for ( 1~®@®~2 )                                 $\C{// for ( typeof(1) i = 1; /*empty*/; i += 2 )}$
    1133 \end{cfa}
    1134 \item
    1135 ©:© means start another index.
    1136 \begin{cfa}
    1137 for ( i; 5 ®:® j; 2~12~3 )              $\C{// for ( typeof(i) i = 1, j = 2; i < 5 \&\& j < 12; i += 1, j += 3 )}\CRT$
     1157for ( i; 1 ~ ®@® ~ 2 )                  $\C{// for ( typeof(1) i = 1; \R{/* empty */}; i += 2 )}$
     1158for ( i; 1 ~ 10 ~ ®@® )                 $\C{// for ( typeof(1) i = 1; i < 10; \R{/* empty */} )}$
     1159for ( i; 1 ~ ®@® ~ ®@® )                $\C{// for ( typeof(1) i = 1; /*empty*/; \R{/* empty */} )}$
     1160\end{cfa}
     1161L cannot be elided for the up-to range, \lstinline{@ ~ 5}, and H for the down-to range, \lstinline{1 -~ @}, because then the loop index is uninitialized.
     1162Similarly, the high value cannot be elided is an anonymous loop index (©1 ~ @©), as there is no index to stop the loop.
     1163\item
     1164©:© means low another index.
     1165\begin{cfa}
     1166for ( i; 5 ®:® j; 2 ~ 12 ~ 3 )          $\C{// for ( typeof(i) i = 1, j = 2; i < 5 \&\& j < 12; i += 1, j += 3 )}$
    11381167\end{cfa}
    11391168\end{itemize}
     1169\R{Warning}: specifying the down-to range maybe unexcepted because the loop control \emph{implicitly} switches the L and H values (and toggles the increment/decrement for I):
     1170\begin{cfa}
     1171for ( i; 1 ~ 10 )       ${\C[1.5in]{// up range}$
     1172for ( i; 1 -~ 10 )      ${\C{// down range}$
     1173for ( i; ®10 -~ 1® )    ${\C{// \R{WRONG down range!}}\CRT}$
     1174\end{cfa}
     1175The reason for this sematics is that the range direction can be toggled by adding/removing the minus, ©'-'©, versus interchanging the L and H expressions, which has a greater chance of introducing errors.
    11401176
    11411177
    … …  
    47944830        int id;
    47954831        float size;
    4796         Parts * optionalParts;
     4832        int * optionalint;
    47974833};
    47984834
    … …  
    48014837// Subsequent arguments can be specified for initialization
    48024838
    4803 void ?{}(Widget &w) { // default constructor
     4839void ?{}( Widget & w ) { $\C{// default constructor}$
    48044840        w.id = -1;
    48054841        w.size = 0.0;
    4806         w.optionalParts = 0;
     4842        w.optionalint = 0p;
    48074843}
    48084844
    48094845// constructor with values (does not need to include all fields)
    4810 void ?{}(Widget &w, int id, float size) {
     4846void ?{}( Widget & w, int id, float size ) {
    48114847        w.id = id;
    48124848        w.size = size;
    4813         w.optionalParts = 0;
    4814 }
    4815 
    4816 // ^? is the destructor operator identifier
    4817 void ^?(Widget &w) { // destructor
     4849        w.optionalint = 0p;
     4850}
     4851
     4852// ^?{} is the destructor operator identifier
     4853void ^?{}( Widget & w ) { $\C{// destructor}$
    48184854        w.id = 0;
    48194855        w.size = 0.0;
    4820         if (w.optionalParts != 0) {
    4821         // This is the only pointer to optionalParts, free it
    4822         free(w.optionalParts);
    4823         w.optionalParts = 0;
     4856        if ( w.optionalint != 0p ) {
     4857                free( w.optionalint );
     4858                w.optionalint = 0p;
    48244859        }
    48254860}
    48264861
    4827 Widget baz; // reserve space only
    4828 Widget foo{}; // calls default constructor
    4829 Widget bar{23, 2.45}; // calls constructor with values
    4830 baz{24, 0.91}; // calls constructor with values
    4831 ?{}(baz, 24, 0.91}; // explicit call to constructor
    4832 ^bar; // explicit call to destructor
    4833 ^?(bar); // explicit call to destructor
     4862Widget baz; $\C{// reserve space only}$
     4863Widget foo{}; $\C{// calls default constructor}$
     4864Widget bar{ 23, 2.45 }; $\C{// calls constructor with values}$
     4865baz{ 24, 0.91 }; $\C{// calls constructor with values}$
     4866?{}( baz, 24, 0.91 ); $\C{// explicit call to constructor}$
     4867^?{} (bar ); $\C{// explicit call to destructor}$
    48344868\end{cfa}
    48354869\caption{Constructors and Destructors}
Note: See TracChangeset for help on using the changeset viewer.