Backup of today's work. Still awaiting a couple more editorial inputs.
[dwarf-doc.git] / dwarf5 / latexdoc / encodingdecoding.tex
index 768dcf4..131053a 100644 (file)
@@ -1,32 +1,40 @@
 
 \chapter[Encoding/Decoding (Informative)]{Variable Length Data: Encoding/Decoding (Informative)}
 \label{app:variablelengthdataencodingdecodinginformative}
-\addtoindex{LEB128 encoding!algorithms}
+\addtoindexx{LEB128 encoding!algorithms}
 
 Here are algorithms expressed in a C-like pseudo-code to
 encode and decode signed and unsigned numbers in LEB128
-\addtoindexx{LEB128!unsigned, encoding as}
 representation.
 
-\begin{figure}[here]
-\caption{Algorithm to encode an unsigned integer}
-\begin{lstlisting}
+The encode and decode algorithms given here do not take account of C/C++ rules
+that mean that in \texttt{E1}$ << $\texttt{E2} the type of \texttt{E1} should be
+a sufficiently large unsigned type to hold the correct mathematical result.
+The decode algorithms do not take account of
+or protect from possibly invalid LEB values, such as values
+that are too large to fit in the target type or that
+lack a proper terminator byte.
+Implementation languages may have additional or different rules.
+
+\vspace{2cm}
+
+\begin{figure}[hb]
+\begin{nlnlisting}
 do
 {
     byte = low order 7 bits of value;
     value >>= 7;
-    if (value != 0) /* more bytes to come */
+    if (value != 0)     /* more bytes to come */
         set high order bit of byte;
     emit byte;
 } while (value != 0);
-\end{lstlisting}
+\end{nlnlisting}
+\caption{Algorithm to encode an unsigned integer}
+\addtoindexx{LEB128!unsigned, encoding as}
 \end{figure}
 
-\addtoindexx{LEB128!signed, encoding as}
-
-\begin{figure}[here]
-\caption{Algorithm to encode a signed integer}
-\begin{lstlisting}
+\begin{figure}[ht]
+\begin{nlnlisting}
 more = 1;
 negative = (value < 0);
 size = no. of bits in signed integer;
@@ -35,9 +43,9 @@ while(more)
     byte = low order 7 bits of value;
     value >>= 7;
     /* the following is unnecessary if the
-      * implementation of >>= uses an arithmetic rather
-      * than logical shift for a signed left operand
-      */
+     * implementation of >>= uses an arithmetic rather
+     * than logical shift for a signed left operand
+     */
     if (negative)
         /* sign extend */
         value |= - (1 <<(size - 7));
@@ -49,16 +57,13 @@ while(more)
         set high order bit of byte;
     emit byte;
 }
-\end{lstlisting}
+\end{nlnlisting}
+\caption{Algorithm to encode a signed integer}
+\addtoindexx{LEB128!signed, encoding as}
 \end{figure}
 
-
-
-\addtoindexx{LEB128!unsigned, decoding of}
-
-\begin{figure}[here]
-\caption{Algorithm to decode an unsigned LEB128 integer}
-\begin{lstlisting}
+\begin{figure}[ht]
+\begin{nlnlisting}
 result = 0;
 shift = 0;
 while(true)
@@ -69,14 +74,13 @@ while(true)
         break;
     shift += 7;
 }
-\end{lstlisting}
+\end{nlnlisting}
+\caption{Algorithm to decode an unsigned LEB128 integer}
+\addtoindexx{LEB128!unsigned, decoding of}
 \end{figure}
 
-\addtoindexx{LEB128!signed, decoding of}
-
-\begin{figure}[here]
-\caption{Algorithm to decode a signed LEB128 integer}
-\begin{lstlisting}
+\begin{figure}[ht]
+\begin{nlnlisting}
 result = 0;
 shift = 0;
 size = number of bits in signed integer;
@@ -89,8 +93,10 @@ while(true)
     if (high order bit of byte == 0)
         break;
 }
-if ((shift <size) \&\& (sign bit of byte is set))
+if ((shift <size) && (sign bit of byte is set))
     /* sign extend */
     result |= - (1 << shift);
-\end{lstlisting}
+\end{nlnlisting}
+\caption{Algorithm to decode a signed LEB128 integer}
+\addtoindexx{LEB128!signed, decoding of}
 \end{figure}