Unit-aware conversion of unit

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}