Unitful literals

chapters/functions.tex

@@ -1093,13 +1093,13 @@ \section{Derivatives and Inverses of Functions}\label{derivatives-and-inverses-o
 
 \begin{annotationdefinition}[smoothOrder]
 \begin{synopsis}[grammar]\begin{lstlisting}
-"smoothOrder" "=" UNSIGNED-NUMBER
+"smoothOrder" "=" UNSIGNED-INTEGER
 "smoothOrder"
    "("
       "normallyConstant" "=" IDENT
       { "," "normallyConstant" "=" IDENT }
    ")"
-   "=" UNSIGNED-NUMBER
+   "=" UNSIGNED-INTEGER
 \end{lstlisting}\end{synopsis}
 \begin{semantics}
 This annotation has only an effect within a function declaration.
@@ -1137,7 +1137,7 @@ \section{Derivatives and Inverses of Functions}\label{derivatives-and-inverses-o
    "(" derivative-constraint { "," derivative-constraint } ")"
 
 derivative-constraint :
-   "order" = UNSIGNED-NUMBER
+   "order" = UNSIGNED-INTEGER
    | "noDerivative" = IDENT
    | "zeroDerivative" = IDENT
 \end{lstlisting}\end{synopsis}

chapters/syntax.tex

@@ -394,7 +394,7 @@ \subsection{Expressions}\label{expressions1}
    primary [ ( "^" | ".^" ) primary ]
 
 primary :
-   UNSIGNED-NUMBER
+   numeric
    | STRING
    | false
    | true
@@ -405,8 +405,11 @@ \subsection{Expressions}\label{expressions1}
    | "{" array-arguments "}"
    | end
 
-UNSIGNED-NUMBER :
-   UNSIGNED-INTEGER | UNSIGNED-REAL
+numeric :
+   ( UNSIGNED-INTEGER | UNSIGNED-REAL ) [ unit-of-measurement ]
+
+unit-of-measurement :
+  Q-IDENT
 
 type-specifier :
    ["."] name

chapters/unitexpressions.tex

@@ -104,3 +104,68 @@ \section{The Syntax of Unit Expressions}\label{the-syntax-of-unit-expressions}
 
 The unit expression \lstinline!"T"! means tesla, but note that the letter \lstinline!T! is also the symbol for the prefix tera which has a multiplier value of 10\textsuperscript{12}.
 \end{example}
+
+
+\section{Unitful Literals}
+
+The \lstinline[language=grammar]!numeric! in the grammar allows a unit to be attached to a numeric value.
+In this case, the unit is given as a \lstinline[language=grammar]!Q-IDENT! rather than a string, since the use of a string could be ambiguously interpreted as \lstinline[language=grammar]!description-string! in some contexts.
+
+\begin{example}
+An acceleration of 9.8~meters per square second can be expressed as \lstinline!9.8'm/s2'!.
+\end{example}
+
+A unitful literal may only be used where unit consistency can be verified.
+
+\begin{example}
+A tool which is only able to check unit consistency of declaration equations may allow basic uses of unitful literals:
+\begin{lstlisting}[language=modelica]
+// Very easy to verify unit consistency:
+parameter Real x(unit = "m") = 5'm';
+// Very easy to infer consistent unit of variable:
+parameter Real y = 5'm';
+// Requires unit arithmetic to verify consistency:
+parameter Real z(unit = "m") = 2'm/s' * 2's';
+\end{lstlisting}
+
+That is, if a tool is unable to perform unit arithmetic, it should reject the use of unitful literals in the declaration equation for \lstinline!z!, as it wouldn't be able to detect the following:
+\begin{lstlisting}[language=modelica]
+// Unit inconsistency:
+parameter Real w(unit = "m") = 2'cm/s' * 2's';
+\end{lstlisting}
+\end{example}
+
+A unitful literal with a temperature unit can represent either an absolute or a relative value of temperature, depending on context.
+
+\begin{example}
+The two different meanings of the unitful literal \lstinline!20'degC'!:
+\begin{lstlisting}[language=modelica]
+// Will display as 293.15 K:
+Real tAbs(unit = "degC", displayUnit = "K") = 20'degC'
+  annotation(absoluteValue = true);
+// Will display as 20 K:
+Real tRel(unit = "degC", displayUnit = "K") = 20'degC'
+  annotation(absoluteValue = false);
+\end{lstlisting}
+\end{example}
+
+\begin{example}
+Adding 2~centimeters to a length.
+A user has set \lstinline!x! to 10~centimeters with the use of \lstinline!displayUnit!, and intends to make \lstinline!y! 2~centimeters bigger than \lstinline!x!:
+\begin{lstlisting}[language=modelica]
+  parameter Real x(unit = "m", displayUnit = "cm") = 0.1;
+equation
+  y = x + 2; /* Intention: Add 2 centimeters to x. */
+\end{lstlisting}
+The result is that 2~meters instead of 2~centimeters is being added to \lstinline!x!.
+
+Using a unitful literal makes the intention clear:
+\begin{lstlisting}[language=modelica]
+  y = x + 2'cm';
+\end{lstlisting}
+It is currently not expected that tools will perform an implicit unit conversion to make the addition possible, in which case the addition should be rejected as a unit inconsistency.
+The unit inconsistency can then be resolved by using a unit compatible with the unit of \lstinline!x!:
+\begin{lstlisting}[language=modelica]
+  y = x + 0.02'm';
+\end{lstlisting}
+\end{example}