Support splitting up struct method parameters into multiple input ports

doc/libraries_ref_guide/LibDoc/Prelude.tex

@@ -3531,15 +3531,115 @@ \subsubsection{Tuples}
 \end{tabular}
 \end{center}
 
+\te{TupleSize} provides a way to determine the number of elements in a tuple
+at the type level. The size is represented as a numeric type parameter.
+
+\index{TupleSize@\te{TupleSize} (type class)}
+\index[typeclass]{TupleSize}
+
+\begin{libverbatim}
+   typeclass TupleSize #(type a, numeric type n)
+      dependencies (a determines n);
+   endtypeclass
+\end{libverbatim}
+
+The type class has instances for unit type \te{void} with size 0, and for all
+tuple types with their respective sizes. The numeric type \te{n} represents
+the number of elements in the tuple.
+
+\begin{center}
+\begin{tabular}{|p{1.5 in}|p{3.8 in}|}
+\hline
+\multicolumn{2}{|c|}{\te{TupleSize} Instances}\\
+\hline
+\hline
+\te{TupleSize \#(void, 0)}&The unit type has size 0.\\
+\hline
+\te{TupleSize \#(a, 1)}&A single element (non-tuple) has size 1.\\
+\hline
+\te{TupleSize \#((a, b), 2)}&A 2-tuple has size 2.\\
+\hline
+\te{TupleSize \#((a,b,c), 3)}&A 3-tuple has size 3.\\
+\hline
+\te{...}&Instances exist for all tuple sizes.\\
+\hline
+\end{tabular}
+\end{center}
+
+\te{AppendTuple} provides a way to join two tuples of arbitrary size into a single larger
+tuple, and to split a tuple back into two parts.
+
+\index{AppendTuple@\te{AppendTuple} (type class)}
+\index{appendTuple@\texttt{appendTuple} (\texttt{AppendTuple} type class function)}
+\index{splitTuple@\texttt{splitTuple} (\texttt{AppendTuple} type class function)}
+\index[function]{Prelude!appendTuple}
+\index[function]{Prelude!splitTuple}
+\index[typeclass]{AppendTuple}
+
+\begin{libverbatim}
+   typeclass AppendTuple #(type a, type b, type c)
+      dependencies ((a, b) determines c);
+      function c appendTuple(a x, b y);
+      function Tuple2#(a, b) splitTuple(c x);
+   endtypeclass
+\end{libverbatim}
+
+The type class has instances for various tuple combinations, including special
+handling for unit type \te{void}.
+
+\begin{center}
+\begin{tabular}{|p{1.5 in}|p{3.8 in}|}
+\hline
+\multicolumn{2}{|c|}{\te{AppendTuple} Functions}\\
+\hline
+\hline
+\te{appendTuple}&Concatenates two tuples \te{x} and \te{y} into a single
+larger tuple. The elements from \te{x} appear first, followed by the elements
+from \te{y}.\\
+\cline{2-2}
+&\\
+& \te{function c appendTuple(a x, b y);}\\
+&\\
+\hline
+\te{splitTuple}&Splits a tuple \te{x} into two parts. Returns a 2-tuple
+containing the first part of type \te{a} and the second part of type \te{b}.\\
+\cline{2-2}
+&\\
+& \te{function Tuple2\#(a, b) splitTuple(c x);}\\
+&\\
+\hline
+\end{tabular}
+\end{center}
+
 {\bf Examples}
 
 \begin{verbatim}
    Tuple2#( Bool, int ) foo = tuple2( True, 25 );
    Bool field1 = tpl_1( foo ); // this is value 1 in the list
    int  field2 = tpl_2( foo ); // this is value 2 in the list
    foo = tuple2( !field1, field2 );
+
+   // Appending a 2-tuple and a 3-tuple to create a 5-tuple
+   Tuple2#(Bool, Int#(8)) t1 = tuple2(True, 42);
+   Tuple3#(String, Bit#(4), UInt#(16)) t2 = tuple3("test", 4'hA, 100);
+
+   Tuple5#(Bool, Int#(8), String, Bit#(4), UInt#(16)) t3 =
+      appendTuple(t1, t2);
+
+   // Splitting a 4-tuple into a 2-tuple and a 2-tuple
+   Tuple4#(Bool, Int#(8), String, Bit#(4)) t4 =
+      tuple4(True, 42, "test", 4'hA);
+
+   Tuple2#(Tuple2#(Bool, Int#(8)), Tuple2#(String, Bit#(4))) parts =
+      splitTuple(t4);
+
+   // Appending with unit type (void)
+   Tuple2#(Bool, Int#(8)) t5 = tuple2(False, 0);
+   Tuple2#(Bool, Int#(8)) t6 = appendTuple(t5, ?);  // same as t5
+   Tuple2#(Bool, Int#(8)) t7 = appendTuple(?, t5);  // same as t5
 \end{verbatim}
 
+
 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \com{Array}
 \subsubsection{Array}
@@ -6211,16 +6311,62 @@ \subsubsection{Operations on Functions}
 \end{tabular}
 \end{center}
 
+\index{Curry@\te{Curry} (type class)}
+\index[typeclass]{Curry}
+\index{curryN@\te{curryN} (function)}
+\index[function]{Prelude!curryN}
+\index{uncurryN@\te{uncurryN} (function)}
+\index[function]{Prelude!uncurryN}
+
+The \te{Curry} typeclass generalizes the \te{curry} and \te{uncurry} functions
+to work with tuples of any size (not just Tuple2).
+
+\begin{libverbatim}
+typeclass Curry#(type f, type g)
+   dependencies (f determines g);
+      function g curryN(f x);
+      function f uncurryN(g x);
+endtypeclass
+\end{libverbatim}
+
+\begin{center}
+\begin{tabular}{|p{1 in}|p{4 in}|}
+\hline
+\te{curryN}&Converts an uncurried function (taking an N-tuple argument) into a curried
+function (taking N arguments one at a time). For example, \te{curryN} can convert a
+function taking \te{Tuple3\#(a,b,c)} into a function \te{a -> b -> c -> result}.\\
+\hline
+\te{uncurryN}&The inverse of \te{curryN}. Converts a curried function (taking N arguments
+one at a time) into an uncurried function (taking an N-tuple argument).\\
+\hline
+\end{tabular}
+\end{center}
+
 
 {\bf Examples}
 
 \begin{libverbatim}
- //using constFn to set the initial values of the registers in a list
+ // Using constFn to set the initial values of the registers in a list
    List#(Reg#(Resource)) items <- mapM( constFn(mkReg(initRes)),upto(1,numAdd) );
 
+ // Using compose when mapping over a list
    return(pack(map(compose(head0,toList),state)));
 
-   xs <- mapM(constFn(mkReg(False)),genList);
+ // Using curryN with a 3-tuple
+   function Int#(32) add3Tuple(Tuple3#(Int#(32), Int#(32), Int#(32)) t);
+      return tpl_1(t) + tpl_2(t) + tpl_3(t);
+   endfunction
+
+   let add3Curried = curryN(add3Tuple);
+   Int#(32) result = add3Curried(1)(2)(3);  // result = 6
+
+ // Using uncurryN
+   function Int#(32) add3(Int#(32) a, Int#(32) b, Int#(32) c);
+      return a + b + c;
+   endfunction
+
+   let add3Uncurried = uncurryN(add3);
+   Int#(32) result2 = add3Uncurried(tuple3(1, 2, 3));  // result2 = 6
 \end{libverbatim}
 
 

doc/libraries_ref_guide/LibDoc/Vector.tex

@@ -2289,15 +2289,124 @@ \subsubsection{Converting to and from Vectors}
 \hline
 \end{tabular}
 
+The \te{ConcatTuple} type class provides functions to convert between a Vector
+of tuples and a single flattened tuple. When you have a Vector where each
+element is a tuple (or can be viewed as a tuple), \te{concatTuple} flattens
+all the elements into one large tuple by concatenating them together. The
+reverse operation, \te{unconcatTuple}, splits a large tuple back into a Vector
+of smaller tuples.
+
+\index{ConcatTuple@\te{ConcatTuple} (type class)}
+\index{concatTuple@\texttt{concatTuple} (\texttt{ConcatTuple} type class function)}
+\index{unconcatTuple@\texttt{unconcatTuple} (\texttt{ConcatTuple} type class function)}
+\index[function]{Vector!concatTuple}
+\index[function]{Vector!unconcatTuple}
+\index[typeclass]{ConcatTuple}
 
-{\bf Example - Converting to and from Vectors}
+\begin{libverbatim}
+   typeclass ConcatTuple #(numeric type n, type a, type b)
+      dependencies ((n, a) determines b);
+      function b concatTuple(Vector#(n, a) v);
+      function Vector#(n, a) unconcatTuple(b x);
+   endtypeclass
+\end{libverbatim}
+
+The type class has instances for various vector sizes:
+\begin{itemize}
+\item A vector of size 0 converts to/from the unit type \te{void}
+\item A vector of size 1 converts to/from a single element
+\item Larger vectors convert by appending each element tuple to
+form a larger tuple
+\end{itemize}
+
+\begin{tabular}{|p{1.2 in}|p{4.4 in}|}
+\hline
+\multicolumn{2}{|c|}{\te{ConcatTuple} Functions}\\
+\hline
+\hline
+&\\ \te{concatTuple} & Flattens a Vector of tuples into a single large tuple
+by concatenating all the tuple elements together. Each element of the vector
+is appended sequentially to form the result tuple.\\
+& \\ \cline{2-2}
+&\begin{libverbatim}
+function b concatTuple(Vector#(n, a) v);
+\end{libverbatim}
+\\
+\hline
+&\\ \te{unconcatTuple}&Splits a large tuple into a Vector of smaller tuples.
+This is the inverse of \te{concatTuple}, distributing the tuple elements across
+a Vector of the specified size.\\
+& \\ \cline{2-2}
+&\begin{libverbatim}
+function Vector#(n, a) unconcatTuple(b x);
+\end{libverbatim}
+\\
+\hline
+\end{tabular}
+
+{\bf Examples - Lists}
 
 Convert the vector \te{my\_vector} to a list named \te{my\_list}.
 \begin{libverbatim}
      Vector#(5,Int#(13)) my_vector;
      List#(Int#(13)) my_list = toList(my_vector);
 \end{libverbatim}
 
+{\bf Examples - Tuples}
+
+Flatten a vector of 3 pairs (2-tuples) into a single 6-tuple:
+\begin{libverbatim}
+   // Create a vector of three 2-tuples
+   Vector#(3, Tuple2#(Bool, Int#(8))) vec_of_pairs = vec(
+       tuple2(True, 1),
+       tuple2(False, 2),
+       tuple2(True, 3)
+   );
+
+   // Flatten into a single 6-tuple
+   Tuple6#(Bool, Int#(8), Bool, Int#(8), Bool, Int#(8)) flat =
+       concatTuple(vec_of_pairs);
+   // Result: (True, 1, False, 2, True, 3)
+
+   // Convert back to vector of pairs
+   Vector#(3, Tuple2#(Bool, Int#(8))) restored = unconcatTuple(flat);
+\end{libverbatim}
+
+Flatten a vector of 4 single elements (which can be viewed as 1-tuples) into a 4-tuple:
+\begin{libverbatim}
+   Vector#(4, Int#(8)) vec_ints = vec(10, 20, 30, 40);
+
+   // Each Int#(8) is treated as a single element
+   Tuple4#(Int#(8), Int#(8), Int#(8), Int#(8)) tuple_ints =
+       concatTuple(vec_ints);
+   // Result: (10, 20, 30, 40)
+\end{libverbatim}
+
+Flatten a vector of 2 triples (3-tuples) into a single 6-tuple:
+\begin{libverbatim}
+   Vector#(2, Tuple3#(Bool, UInt#(4), String)) vec_triples = vec(
+       tuple3(True, 5, "hello"),
+       tuple3(False, 10, "world")
+   );
+
+   Tuple6#(Bool, UInt#(4), String, Bool, UInt#(4), String) result =
+       concatTuple(vec_triples);
+   // Result: (True, 5, "hello", False, 10, "world")
+\end{libverbatim}
+
+Special cases:
+\begin{libverbatim}
+   // Empty vector converts to unit type
+   Vector#(0, Tuple2#(Bool, Int#(8))) empty = nil;
+   void unit = concatTuple(empty);
+
+   // Single element vector returns just that element
+   Vector#(1, Tuple2#(Bool, Int#(8))) single =
+       vec(tuple2(True, 42));
+   Tuple2#(Bool, Int#(8)) pair = concatTuple(single);
+   // Result: (True, 42)
+\end{libverbatim}
+
 
 \subsubsection{ListN}