Similar when (modelica#2718)

* Make restrictions of when-equations and when-statements more similar in text.
Closes modelica#2635
* Add restrictions not discovered before: when inside if/for in equations.
Co-authored-by: Henrik Tidefelt <henrikt@wolfram.com>

chapters/equations.tex

@@ -244,13 +244,15 @@ \subsubsection{Defining When-Equations by If-Expressions in Equality Equations}\
 The start-values of the introduced \lstinline!Boolean! variables are defined by the taking the start-value of the when-condition, as above where \lstinline!b! is a parameter
 variable.  The start-value of the special functions \lstinline!initial!, \lstinline!terminal!, and \lstinline!sample! is \lstinline!false!.
 
-\subsubsection{Restrictions on Equations within When-Equations}\label{restrictions-on-equations-within-when-equations}
-
+\subsubsection{Restrictions on Where a When-Equation may Occur}\label{restrictions-on-where-a-when-equation-may-occur}
 \begin{itemize}
 \item
   When-equations shall not occur inside initial equations.
 \item
   When-equations cannot be nested.
+\item
+  When-equations can only occur within if-equations and for-equations if
+  the controlling expressions are exclusively parameter expressions.
 \end{itemize}
 
 \begin{example}
@@ -264,6 +266,7 @@ \subsubsection{Restrictions on Equations within When-Equations}\label{restrictio
 \end{lstlisting}
 \end{example}
 
+\subsubsection{Restrictions on Equations within When-Equations}\label{restrictions-on-equations-within-when-equations}
 The equations within the when-equation must have one of the following forms:
 \begin{itemize}
 \item
@@ -284,8 +287,7 @@ \subsubsection{Restrictions on Equations within When-Equations}\label{restrictio
 be a component reference, and any indices must be parameter expressions.
 
 \begin{nonnormative}
-The needed restrictions on equations within a when-equation
-becomes apparent with the following example:
+The needed restrictions on equations within a when-equation becomes apparent with the following example:
 \begin{lstlisting}[language=modelica]
   Real x, y;
 equation
@@ -295,8 +297,7 @@ \subsubsection{Restrictions on Equations within When-Equations}\label{restrictio
   end when;
 \end{lstlisting}
 
-When the equations of the when-equation are not activated it is
-not clear which variable to hold constant, either \lstinline!x! or \lstinline!y!.
+When the equations of the when-equation are not activated it is not clear which variable to hold constant, either \lstinline!x! or \lstinline!y!.
 A corrected version of this example is:
 \begin{lstlisting}[language=modelica]
   Real x,y;
@@ -311,6 +312,45 @@ \subsubsection{Restrictions on Equations within When-Equations}\label{restrictio
 value of \lstinline!y! from the previous event instant.
 \end{nonnormative}
 
+\begin{example}
+The restrictions for if-equations mean that both of the following variants are illegal:
+\begin{lstlisting}[language=modelica]
+  Real x, y;
+equation
+  if time < 1 then
+    when sample(1, 2) then
+      x = time;
+    end when;
+  else
+    when sample(1, 3) then
+      y = time;
+    end when;
+  end if;
+
+  when sample(1, 2) then
+    if time < 1 then
+      y = time;
+    else
+      x = time;
+    end if;
+  end when;
+\end{lstlisting}
+whereas the restriction to parameter-expression is intended to allow:
+\begin{lstlisting}[language=modelica]
+  parameter Boolean b = true;
+  parameter Integer n = 3;
+  Real x[n];
+equation
+  if b then
+    for i in 1 : n loop
+      when sample(i, i) then
+        x[i] = time;
+      end when;
+    end for;
+  end if;
+\end{lstlisting}
+\end{example}
+
 \subsubsection{Application of the Single-assignment Rule to When-Equations}\label{application-of-the-single-assignment-rule-to-when-equations}
 
 The Modelica single-assignment rule (\cref{synchronous-data-flow-principle-and-single-assignment-rule}) has implications for

chapters/revisions.tex

@@ -538,7 +538,7 @@ \subsection{Main changes in Modelica 3.3 Revision 1}\label{main-changes-in-model
 \item
   Forbid when-statements in initial equation/algorithm (they would in
   most cases not be active; leading to confusion), \cref{restrictions-on-equations-within-when-equations} and
-  \cref{restrictions-on-when-statements}. Ticket
+  \cref{restrictions-on-where-a-when-statement-may-occur}. Ticket
   \href{https://github.com/modelica/ModelicaSpecification/issues/1288}{\#1288}.
 \item
   Clarified \lstinline!reinit! during initialization, \cref{reinit} \cref{initialization-initial-equation-and-initial-algorithm}.

chapters/statements.tex

@@ -405,8 +405,7 @@ \subsection{When-Statements}\label{when-statements}
 assignment to \lstinline!y1! and \lstinline!y3! in the algorithm.
 \end{example}
 
-\subsubsection{Restrictions on When-Statements}\label{restrictions-on-when-statements}
-
+\subsubsection{Restrictions on Where a When-statement may occur}\label{restrictions-on-where-a-when-statement-may-occur}
 \begin{itemize}
 \item
   A when-statement shall not be used within a function.
@@ -430,6 +429,25 @@ \subsubsection{Restrictions on When-Statements}\label{restrictions-on-when-state
 \end{lstlisting}
 \end{example}
 
+\subsubsection{Restrictions on Statements within When-Statements}\label{restrictions-on-statements-within-when-statements}
+
+\begin{nonnormative}
+In contrast to when-equations, \cref{restrictions-on-equations-within-when-equations},
+there are no additional restrictions within when-statements:
+\begin{itemize}
+\item
+  In algorithms, all assignment statements are already restricted to left-hand-side variables.
+\item
+  If at least one element of an array appears on the left-hand-side of the assignment operator inside
+  a when-statement, it is as if the entire array appears in the left-hand-side
+  according to \cref{execution-of-an-algorithm-in-a-model}.
+  Thus, there is no need to restrict the indices to parameter expressions.
+\item
+  For-clauses and if-clauses are not problematic inside when-statements in algorithms, since
+  all left-hand-side variables inside when-statements are assigned to their pre-values
+  before the start of the algorithm, according to \cref{execution-of-an-algorithm-in-a-model}.
+\end{itemize}
+\end{nonnormative}
 \subsubsection{Defining When-Statements by If-Statements}\label{defining-when-statements-by-if-statements}
 
 A when-statement: