Changeset d2f09e4 for doc


Ignore:
Timestamp:
Aug 25, 2022, 11:54:42 AM (23 months ago)
Author:
Thierry Delisle <tdelisle@…>
Branches:
ADT, ast-experimental, master, pthread-emulation
Children:
f6a4917
Parents:
fc6c410 (diff), 4d3666d (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge branch 'master' of plg.uwaterloo.ca:software/cfa/cfa-cc

Location:
doc
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • doc/proposals/iterators.md

    rfc6c410 rd2f09e4  
    22=========
    33This is the proposal for adding iterators to Cforall and the standard
    4 libary. Iterators provide a common interface for sequences of values in
     4library. Iterators provide a common interface for sequences of values in
    55the language. Many inputs and outputs can be described in terms of sequences,
    66creating a common interface that can be used in many places.
    … …  
    1515The operation is "get the next value in the sequence", but this actually has
    1616several parts, in that it has to check if there are move values, return the
    17 next one if there is, and update any internal information in the iterator.
     17next one if there is one, and update any internal information in the iterator.
    1818For example: `Maybe(Item) next(Iter &);`.
    1919
    2020Now, iterators can have other operations. Notably, they are often also
    21 iterables that return themselves. They can also have a veriaty of iterator
     21iterables that return themselves. They can also have a verity of iterator
    2222transformers built in.
    2323
    … …  
    2525
    2626Anything that you can get an iterator from is called an iterable. There
    27 is an operation to get an iterator from an iterator.
     27is an operation to get an iterator from an iterable.
    2828
    2929Range For Loop
    … …  
    3131One part of the language that could be reworked to make good use of this is
    3232for loops. In short, remove most of the special rules that can be done inside
    33 the identifer and make it a generic range for loop:
     33the identifier and make it a generic range for loop:
    3434
    3535    ```
    … …  
    3939The common way to implement this is that expression produces an iterable.
    4040The for loop gets an iterator from the iterable (which is why iterators are
    41 often iterables, so they can be passed in with the same iterface) and stores
     41often iterables, so they can be passed in with the same interface) and stores
    4242it. Then, for each value in the iterator, the loop binds the value to the
    4343identifier and then executes the statement. The loop exits after every value
    44 has been used and the iterator is exausted.
     44has been used and the iterator is exhausted.
    4545
    4646For the chained for loop (`for (i; _: j; _)`) can still have its existing
    4747behaviour, advancing through each range in parallel and stopping as soon
    48 as the first one is exausted.
     48as the first one is exhausted.
    4949
    5050Ranges
    … …  
    5454logically instead of by copy.
    5555
    56 The purpose of this container is to bridge the new iterator iterfaces with
     56The purpose of this container is to bridge the new iterator interfaces with
    5757the existing range syntax. The range syntax would become an operator that
    5858returns a range object, which can be used as any other type.
    … …  
    9191pointers.
    9292
    93 Rust also has a imparative implementation of a functional style of iterators,
     93Rust also has a imperative implementation of a functional style of iterators,
    9494including a great number of standard transformers. Otherwise, it is very
    9595similar to Python.

  • doc/user/user.tex

    rfc6c410 rd2f09e4  
    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.