From 912485924a1c2c24fe83131bef0da8d5776c2342 Mon Sep 17 00:00:00 2001 From: Julie Schwartz Date: Sat, 25 Jan 2025 13:55:31 +1300 Subject: [PATCH 1/2] Libraries Doc: Improve the Makefile dependencies to include .tex source and .png figures in the subdirectories --- doc/libraries_ref_guide/Makefile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/libraries_ref_guide/Makefile b/doc/libraries_ref_guide/Makefile index f3df0e8f3..84e3a44bb 100644 --- a/doc/libraries_ref_guide/Makefile +++ b/doc/libraries_ref_guide/Makefile @@ -26,9 +26,11 @@ DOC=libraries_ref_guide # should be named '?dx' and '?nd' (using a new unique letter) IDX_LIST= f t -## Included .tex Files +## Included files INCLUDES = \ version.tex \ + LibDoc/*.tex \ + LibFig/*.png \ # ------------------------- From 009699d055266222201bb66106c6a97ae54cae59 Mon Sep 17 00:00:00 2001 From: Julie Schwartz Date: Sat, 25 Jan 2025 14:30:29 +1300 Subject: [PATCH 2/2] Libraries Doc: Fix section on numeric and string type operators Fix typos in the index entries, standardize headings, correctly identify type functions from pseudo-functions, and separately document the SizeOf type function from the sizeOf pseudo-function. --- doc/libraries_ref_guide/LibDoc/Prelude.tex | 149 ++++++++++++++------- 1 file changed, 97 insertions(+), 52 deletions(-) diff --git a/doc/libraries_ref_guide/LibDoc/Prelude.tex b/doc/libraries_ref_guide/LibDoc/Prelude.tex index 8e69ad802..ddfcfbcd0 100644 --- a/doc/libraries_ref_guide/LibDoc/Prelude.tex +++ b/doc/libraries_ref_guide/LibDoc/Prelude.tex @@ -1455,7 +1455,7 @@ \subsubsection{SaturatingArith} \end{verbatim} -\subsubsection{Alias and NumAlias} +\subsubsection{Alias, NumAlias, and StrAlias} \label{sec-alias} \index{Alias} \index{NumAlias} @@ -4169,15 +4169,14 @@ \subsubsection{Rules} %================================================================ \subsection{Operations on Numeric and String Types} -\subsubsection{Size Relationship/Provisos} +\subsubsection{Size Relationship Provisos} -\index{provisos} -\index{Add@\te{Add} (type provisos)} -\index{Max@\te{Max} (type provisos)} -\index{Min@\te{Min} (type provisos)} -\index{Log@\te{Log} (type provisos)} -\index{Mul@\te{Mul} (type provisos)} -\index{Div@\te{Div} (type provisos)} +\index{Add@\te{Add} (type class)} +\index{Mul@\te{Mul} (type class)} +\index{Div@\te{Div} (type class)} +\index{Max@\te{Max} (type class)} +\index{Min@\te{Min} (type class)} +\index{Log@\te{Log} (type class)} @@ -4223,22 +4222,22 @@ \subsubsection{Size Relationship/Provisos} \subsubsection{Size Relationship Type Functions} -\index{TAdd@\te{TAdd} (type functions)} -\index{TSub@\te{TSub} (type functions)} -\index{TLog@\te{TLog} (type functions)} -\index{TExp@\te{TExp} (type functions)} -\index{TMul@\te{TMul} (type functions)} -\index{TDiv@\te{TDiv} (type functions)} -\index{TMax@\te{TMax} (type functions)} -\index{TMin@\te{TMin} (type functions)} +\index{TAdd@\te{TAdd} (type function)} +\index{TSub@\te{TSub} (type function)} +\index{TMul@\te{TMul} (type function)} +\index{TDiv@\te{TDiv} (type function)} +\index{TLog@\te{TLog} (type function)} +\index{TExp@\te{TExp} (type function)} +\index{TMax@\te{TMax} (type function)} +\index{TMin@\te{TMin} (type function)} \index[function]{Prelude!TAdd} \index[function]{Prelude!TSub} +\index[function]{Prelude!TMul} +\index[function]{Prelude!TDiv} \index[function]{Prelude!TLog} \index[function]{Prelude!TExp} -\index[function]{Prelude!TMul} \index[function]{Prelude!TMax} \index[function]{Prelude!TMin} -\index[function]{Prelude!TDiv} These type functions are used when ``defining'' size relationships between data types, where the defined value need not (or cannot) be named in a proviso. They may be used in datatype definition statements when the @@ -4247,7 +4246,7 @@ \subsubsection{Size Relationship Type Functions} \begin{center} \begin{tabular}{|p {1 in}|p{1.5 in}| p{2.0 in}|} \hline -Type Function& Size Relationship& Description\\ +Type Function& Application& Description\\ \hline \hline \te{TAdd}&\verb'TAdd#(n1,n2)'&Calculate $n1 + n2$\\ @@ -4289,19 +4288,50 @@ \subsubsection{Size Relationship Type Functions} % ================================================================ -\subsubsection{valueOf and SizeOf pseudo-functions} +\subsubsection{SizeOf Type Function} +\index{SizeOf@\te{SizeOf} (type function)} +\index[function]{Prelude!SizeOf} + +The \te{Bits} type class expresses the relationship between a type +and the size of its bit-vector representation. +The \te{SizeOf} type function is used to access that size, where +the value need not (or cannot) be named in a \te{Bits} proviso. +It may be used in datatype definition statements to compute a size +from another parameter or from an explicit type. + +\begin{center} +\begin{tabular}{|p {1 in}|p{1.5 in}| p{2.0 in}|} +\hline +Type Function& Application& Description\\ +\hline +\hline +\te{SizeOf}&\verb'SizeOf#(t)'&The \te{Bits} size of \te{t} as a numeric type\\ +\hline +\end{tabular} +\end{center} + +{\bf Examples} +\begin{libverbatim} + any_type x = ... ; + Bit#(SizeOf#(any_type)) b = pack(x); +\end{libverbatim} + + +\subsubsection{valueOf, sizeOf, and stringOf Pseudo-functions} \index{valueof@\texttt{valueof} (pseudo-function of size types)} \index{valueOf@\texttt{valueOf} (pseudo-function of size types)} -\index{SizeOf@\texttt{SizeOf} (pseudo-function on types)} +\index{sizeOf@\texttt{sizeOf} (pseudo-function of value types)} +\index{stringOf@\texttt{stringOf} (pseudo-function of string types)} \index[function]{Prelude!valueOf} -\index[function]{Prelude!SizeOf} +\index[function]{Prelude!sizeOf} +\index[function]{Prelude!stringOf} + +Prelude provides three pseudo-functions to convert from types to values. +Unlike ordinary functions from values to values, the arguments of these +pseudo-functions are parsed as types. -Prelude provides these pseudo-functions to convert between -types and numeric values. The pseudo-function \te{valueof} (or -\te{valueOf}) is used to convert a numeric type into the corresponding -Integer value. -The pseudo-function \te{SizeOf} is used to convert a type {t} into -the numeric type representing its bit size. +The pseudo-function \te{valueOf} (or \te{valueof}) is used to convert +a numeric type into the corresponding Integer value. \begin{center} \begin{tabular}{|p{1 in}|p{4.6 in}|} @@ -4311,7 +4341,7 @@ \subsubsection{valueOf and SizeOf pseudo-functions} \te{valueOf}& \\ \cline{2-2} &\begin{libverbatim} -function Integer valueOf (t) ; +function Integer valueOf (numeric type t) ; \end{libverbatim} \\ \hline @@ -4321,24 +4351,28 @@ \subsubsection{valueOf and SizeOf pseudo-functions} {\bf Examples} \begin{libverbatim} module mkFoo (Foo#(n)); - UInt#(n) x; Integer y = valueOf(n); endmodule \end{libverbatim} - +The pseudo-function \te{sizeOf} is used to convert a type \te{t} into +the numeric type representing its bit size. It is equivalent to +applying \te{valueOf} to the \te{SizeOf} type constructor, but +is provided for convenience. This pseudo-function carries a +\te{Bits} proviso and can therefore only be used for types that +are members of the \te{Bits} type class. \begin{center} \begin{tabular}{|p{1 in}|p{4.6 in}|} \hline & \\ -\te{SizeOf} & Converts a type into a numeric type representing its +\te{sizeOf} & Converts a type into a numeric type representing its bit size.\\ & \\ \cline{2-2} &\begin{libverbatim} -function t SizeOf#(any_type) - provisos (Bits#(any_type, sa)) ; +function Integer sizeOf (type t) + provisos (Bits#(t, tsz)) ; \end{libverbatim} \\ \hline @@ -4347,23 +4381,16 @@ \subsubsection{valueOf and SizeOf pseudo-functions} {\bf Examples} \begin{libverbatim} - any_type x = structIn; - Bit#(SizeOf#(any_type)) = pack(structIn); + module mkFoo (Ifc#(t)) provisos (Bits#(t,szt)); + Integer num_bits_of_t = sizeOf(t); + // The above is equivalent to each of the following + //Integer num_bits_of_t = valueOf(SizeOf#(t)); + //Integer num_bits_of_t = valueOf(szt); + endmodule \end{libverbatim} -% ================================================================ -\subsubsection{String type pseudo-functions} -\index{stringOf@\texttt{valueOf} (pseudo-function of types)} -\index{TStrCat@\texttt{TStrCat} (pseudo-function on types)} -\index{TNumToStr@\texttt{TNumToStr} (pseudo-function on types)} -\index[function]{Prelude!stringOf} -\index[function]{Prelude!TStrCat} -\index[function]{Prelude!TNumToStr} - -Prelude also provides similar pseudo-functions for string types. -The pseudo-function \te{stringOf} is used to convert a string type into a \te{String} value. -The type-level pseudo-function \te{TStrCat} is used to concatenate two string types, -and \te{TNumToStr} is used to convert a numeric type into a string type. +The pseudo-function \te{stringOf} is used to convert a string type +into a \te{String} value. \begin{center} \begin{tabular}{|p{1 in}|p{4.6 in}|} @@ -4372,17 +4399,35 @@ \subsubsection{String type pseudo-functions} \te{stringOf}&Converts a string type into its String value.\\ \cline{2-2} &\begin{libverbatim} -function String stringOf (t) ; +function String stringOf (string type t) ; \end{libverbatim} \\ \hline \end{tabular} \end{center} +{\bf Examples} +\begin{libverbatim} + module mkFoo (IfcWithStr#(s_type)); + String s_value = stringOf(s_type); + endmodule +\end{libverbatim} + +% ================================================================ +\subsubsection{String Type Functions} +\index{TStrCat@\texttt{TStrCat} (type function)} +\index{TNumToStr@\texttt{TNumToStr} (type function)} +\index[function]{Prelude!TStrCat} +\index[function]{Prelude!TNumToStr} + +Prelude defines two type functions for creating or manipulating string types. +The type function \te{TStrCat} is used to concatenate two string types, +and \te{TNumToStr} is used to convert a numeric type into a string type. + \begin{center} \begin{tabular}{|p {1 in}|p{1.5 in}| p{2.0 in}|} \hline -Type Function& Type Relationship& Description\\ +Type Function& Application& Description\\ \hline \hline \te{TStrCat}&\verb'TStrCat#(s1,s2)'&Concatenate $s1$ and $s2$\\