diff --git a/chapters/operatorsandexpressions.tex b/chapters/operatorsandexpressions.tex index 289806ec8..f63a75f6b 100644 --- a/chapters/operatorsandexpressions.tex +++ b/chapters/operatorsandexpressions.tex @@ -417,6 +417,7 @@ \subsection{Numeric Functions and Conversion Functions}\label{numeric-functions- {\lstinline!Integer($e$)!} & Conversion from enumeration to {\lstinline!Integer!} & \Cref{modelica:integer-of-enumeration} \\ {\lstinline!EnumTypeName($i$)!} & Conversion from {\lstinline!Integer!} to enumeration & \Cref{modelica:enumeration-of-integer} \\ {\lstinline!String($\ldots$)!} & Conversion to {\lstinline!String!} & \Cref{modelica:to-String} \\ +{\lstinline!inUnit($e$, $u$)!} & Convert to unit & \Cref{modelica:inUnit} \\ \hline \end{tabular} \end{center} @@ -540,6 +541,31 @@ \subsection{Numeric Functions and Conversion Functions}\label{numeric-functions- \end{semantics} \end{operatordefinition*} +\begin{functiondefinition}[inUnit] +\begin{synopsis}\begin{lstlisting} +inUnit($e$, $u$, absoluteValue = $a$) +\end{lstlisting}\end{synopsis} +\begin{semantics} +Convert the \lstinline!Real! expression $e$ to unit $u$. +It is required that the unit of $e$ is defined, possibly as being empty. +(Details of \emph{how} the unit is defined is a quality of implementation.) +The unit $u$ shall be a \lstinline!String! parameter expression following the unit string syntax described in \cref{the-syntax-of-unit-expressions}. +Unit symbols in $u$ shall be interpreted as belonging to an absolute quantity when $a$, and otherwise as belonging to a relative quantity. +To specify $a$, the named argument form must be used, and if omitted it is determined based on $e$ as described below. + +If $e$ has empty unit, \lstinline!absoluteValue! defaults to \lstinline!true!, and the unit $u$ gets attached to the value of $e$ without conversion. + +When $e$ has non-empty unit, \lstinline!absoluteValue! defaults to \lstinline!false! if $e$ is a relative quantity (corresponding to \lstinline!absoluteValue = false!, see \lstinline!absoluteValue!-annotation in \cref{graphical-user-interface}), and to true otherwise. +The non-empty unit of $e$ must be compatible with $u$. +\end{semantics} +\begin{nonnormative} +As described in \cref{the-syntax-of-unit-expressions}, there may be user-defined unit symbols in addition to the ones that must be recognized. +Hence, unit symbols that are recongized in one modeling environment may not be recognized in another. +Often, this results in an error since it prevents verifying unit compatibility. +It is a quality of implementation whether conversions that only involve changes of unit symbol prefixes are supported even when some unit symbols are unrecognized. +\end{nonnormative} +\end{functiondefinition} + \subsection{Event Triggering Mathematical Functions}\label{event-triggering-mathematical-functions}