\hypertarget{decompress_8c}{
\section{decompress.c File Reference}
\label{decompress_8c}\index{decompress.c@{decompress.c}}
}
Routines used to manipulate the tables used to decode the compressed events.  


{\tt \#include $<$decompress\_\-p.h$>$}\par
{\tt \#include $<$LDT/APM.h$>$}\par
{\tt \#include $<$LDT/HDD.h$>$}\par
{\tt \#include $<$string.h$>$}\par
{\tt \#include $<$math.h$>$}\par
\subsection*{Functions}
\begin{CompactItemize}
\item 
static double \hyperlink{decompress_8c_c2f3d95929a6a4a529df96da5c10b240}{calc\_\-nbits} (const unsigned int $\ast$f, int cnt, int tot)
\begin{CompactList}\small\item\em Calculate the number of bits need to encode a sample with the specified frequency distribution. \item\end{CompactList}\item 
static \_\-\_\-inline const unsigned $\ast$ \hyperlink{decompress_8c_422a69b9d7a99489d328c4762c722723}{getwrd} (const unsigned $\ast$buffer, unsigned $\ast$bcnt, unsigned $\ast$word, unsigned nbits)
\begin{CompactList}\small\item\em Get bits from a buffer. \item\end{CompactList}\item 
size\_\-t \hyperlink{decompress_8c_fb51bf6fcc032ed0be71fbf548003027}{QSEC\_\-sizeofDecompression} (unsigned int nbits)
\begin{CompactList}\small\item\em Calculate the total size required to accomodate a decompression structure. \item\end{CompactList}\item 
\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$ \hyperlink{decompress_8c_6afe934b8d875845dc6009f7b8931631}{QSEC\_\-constructDecompression} (void $\ast$buffer, unsigned int nbits, const char $\ast$name)
\begin{CompactList}\small\item\em Initialise the buffer as a decompression structure. \item\end{CompactList}\item 
\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$ \hyperlink{decompress_8c_de340d0845160b2d9f724d8492de9c0a}{QSEC\_\-newDecompression} (unsigned int nbits, const char $\ast$name)
\begin{CompactList}\small\item\em Allocate and initialise a new decompression structure. \item\end{CompactList}\item 
void \hyperlink{decompress_8c_8e1340f1268535a22d719b926ea9d6bf}{QSEC\_\-deleteDecompression} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm)
\begin{CompactList}\small\item\em Free the memory associated with the decompression structure. \item\end{CompactList}\item 
void \hyperlink{decompress_8c_c62a71c256186b30de049043981640d5}{QSEC\_\-clearDecompression} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm)
\begin{CompactList}\small\item\em Clear the decompression structrure of any data from a previous cycle. \item\end{CompactList}\item 
unsigned int \hyperlink{decompress_8c_4ea59426abbf9a9d29ccff4b722264f7}{QSEC\_\-getCount} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm)
\begin{CompactList}\small\item\em Return the number of non-zero bins in the histogram. \item\end{CompactList}\item 
const unsigned int $\ast$ \hyperlink{decompress_8c_75cda4618e3e6a15275f3211527b0cab}{QSEC\_\-unpack} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm, const unsigned int $\ast$buffer)
\begin{CompactList}\small\item\em Unpack a histogram used for APE encoding. \item\end{CompactList}\item 
const unsigned int $\ast$ \hyperlink{decompress_8c_d9062d9c20327bcb3b21ac7237f68c4b}{QSEC\_\-unpackH} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm, const unsigned int $\ast$buffer)
\begin{CompactList}\small\item\em Unpack a table used for Huffman encoding. \item\end{CompactList}\item 
unsigned int \hyperlink{decompress_8c_af78c26a52c1f4889ae4a57f812cc96e}{QSEC\_\-decompress} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm, APD\_\-dtx $\ast$dtx)
\begin{CompactList}\small\item\em Decode the next APE-encoded symbol. \item\end{CompactList}\item 
int \hyperlink{decompress_8c_2c3b49bd367acba1c2d1634cb3b3839c}{QSEC\_\-decompressH} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm, const unsigned int $\ast$buff, unsigned int $\ast$posn)
\begin{CompactList}\small\item\em Decode the next Huffman-encoded symbol. \item\end{CompactList}\item 
void \hyperlink{decompress_8c_9500b01a3ec3df5a23d43cef2c2c58b2}{QSEC\_\-reportDecompression} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm, FILE $\ast$fp)
\begin{CompactList}\small\item\em Describe the contents of the decompression structure in formatted ASCII sent to the file {\em fp\/}. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Routines used to manipulate the tables used to decode the compressed events. 

\begin{Desc}
\item[Author:]James Swain \& Owen Saxton\end{Desc}
\begin{Desc}
\item[Id]\hyperlink{decompress_8c}{decompress.c},v 1.12 2011/03/28 19:32:29 saxton Exp \end{Desc}


\subsection{Function Documentation}
\hypertarget{decompress_8c_c2f3d95929a6a4a529df96da5c10b240}{
\index{decompress.c@{decompress.c}!calc\_\-nbits@{calc\_\-nbits}}
\index{calc\_\-nbits@{calc\_\-nbits}!decompress.c@{decompress.c}}
\subsubsection[{calc\_\-nbits}]{\setlength{\rightskip}{0pt plus 5cm}double calc\_\-nbits (const unsigned int $\ast$ {\em f}, \/  int {\em cnt}, \/  int {\em tot})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{decompress_8c_c2f3d95929a6a4a529df96da5c10b240}


Calculate the number of bits need to encode a sample with the specified frequency distribution. 

This is based on the following formula

nbits = - TOT $\ast$ SUM \mbox{[} f\mbox{[}i\mbox{]} / TOT $\ast$ ln (f\mbox{[}i\mbox{]} / TOT) \mbox{]} = - TOT/TOT $\ast$ SUM \mbox{[} f\mbox{[}i\mbox{]} $\ast$ (ln (f\mbox{[}i\mbox{]}) - ln (TOT)) \mbox{]} = - SUM \mbox{[} f\mbox{[}i\mbox{]} $\ast$ ln (f\mbox{[}i\mbox{]} \mbox{]} + SUM \mbox{[} f\mbox{[}i\mbox{]} $\ast$ ln (TOT) \mbox{]} = - SUM \mbox{[} f\mbox{[}i\mbox{]} $\ast$ ln (f\mbox{[}i\mbox{]} \mbox{]} + TOT $\ast$ ln (TOT) \mbox{]}

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em f}]The frequency distribution\item[{\em cnt}]The count of entries in the frequency distribution\item[{\em tot}]The total number of entries in the frequency distribution \end{description}
\end{Desc}


Referenced by QSEC\_\-reportDecompression().\hypertarget{decompress_8c_422a69b9d7a99489d328c4762c722723}{
\index{decompress.c@{decompress.c}!getwrd@{getwrd}}
\index{getwrd@{getwrd}!decompress.c@{decompress.c}}
\subsubsection[{getwrd}]{\setlength{\rightskip}{0pt plus 5cm}static \_\-\_\-inline const unsigned$\ast$ getwrd (const unsigned $\ast$ {\em buffer}, \/  unsigned $\ast$ {\em bcnt}, \/  unsigned $\ast$ {\em word}, \/  unsigned {\em nbits})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{decompress_8c_422a69b9d7a99489d328c4762c722723}


Get bits from a buffer. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em buffer}]Pointer to the current word in the buffer\item[{\em bcnt}]Number of bits remaining in the current word\item[{\em word}]Address of word to receive the extracted bits\item[{\em nbits}]Number of bits to get from the buffer\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to the next word to use in the buffer \end{Desc}


Referenced by QSEC\_\-unpack().\hypertarget{decompress_8c_c62a71c256186b30de049043981640d5}{
\index{decompress.c@{decompress.c}!QSEC\_\-clearDecompression@{QSEC\_\-clearDecompression}}
\index{QSEC\_\-clearDecompression@{QSEC\_\-clearDecompression}!decompress.c@{decompress.c}}
\subsubsection[{QSEC\_\-clearDecompression}]{\setlength{\rightskip}{0pt plus 5cm}void QSEC\_\-clearDecompression ({\bf QSEC\_\-decompression} $\ast$ {\em dcm})}}
\label{decompress_8c_c62a71c256186b30de049043981640d5}


Clear the decompression structrure of any data from a previous cycle. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to an allocated, initialised, decompression structure \end{description}
\end{Desc}


References QSEC\_\-decompression\_\-::desc, QSEC\_\-decompression\_\-::freq, QSEC\_\-decompression\_\-::nbits, QSEC\_\-decompression\_\-::rvlu, and QSEC\_\-decompression\_\-::table.

Referenced by QSEC\_\-clearExpansion().\hypertarget{decompress_8c_6afe934b8d875845dc6009f7b8931631}{
\index{decompress.c@{decompress.c}!QSEC\_\-constructDecompression@{QSEC\_\-constructDecompression}}
\index{QSEC\_\-constructDecompression@{QSEC\_\-constructDecompression}!decompress.c@{decompress.c}}
\subsubsection[{QSEC\_\-constructDecompression}]{\setlength{\rightskip}{0pt plus 5cm}{\bf QSEC\_\-decompression}$\ast$ QSEC\_\-constructDecompression (void $\ast$ {\em buffer}, \/  unsigned int {\em nbits}, \/  const char $\ast$ {\em name})}}
\label{decompress_8c_6afe934b8d875845dc6009f7b8931631}


Initialise the buffer as a decompression structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em buffer}]Pointer to the uninitialised memory to use for this decompression structure\item[{\em nbits}]Number of bits in the symbols to be handled by this decompression strcuture\item[{\em name}]String identifying this structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to an initialised decompression structure \end{Desc}


References QSEC\_\-decompression\_\-::desc, QSEC\_\-decompression\_\-::freq, QSEC\_\-decompression\_\-::hdd, QSEC\_\-decompression\_\-::name, QSEC\_\-decompression\_\-::nbits, QSEC\_\-decompression\_\-::rvlu, and QSEC\_\-decompression\_\-::table.

Referenced by addDcm(), and QSEC\_\-newDecompression().\hypertarget{decompress_8c_af78c26a52c1f4889ae4a57f812cc96e}{
\index{decompress.c@{decompress.c}!QSEC\_\-decompress@{QSEC\_\-decompress}}
\index{QSEC\_\-decompress@{QSEC\_\-decompress}!decompress.c@{decompress.c}}
\subsubsection[{QSEC\_\-decompress}]{\setlength{\rightskip}{0pt plus 5cm}unsigned int QSEC\_\-decompress ({\bf QSEC\_\-decompression} $\ast$ {\em dcm}, \/  APD\_\-dtx $\ast$ {\em dtx})}}
\label{decompress_8c_af78c26a52c1f4889ae4a57f812cc96e}


Decode the next APE-encoded symbol. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to an initialsed, populated and processed decompression structure\item[{\em dtx}]Pointer to the arithmetic encoder context\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The next symbol \end{Desc}


References QSEC\_\-decompression\_\-::rvlu, and QSEC\_\-decompression\_\-::table.

Referenced by decodeCalMeans(), and decodeShorts().\hypertarget{decompress_8c_2c3b49bd367acba1c2d1634cb3b3839c}{
\index{decompress.c@{decompress.c}!QSEC\_\-decompressH@{QSEC\_\-decompressH}}
\index{QSEC\_\-decompressH@{QSEC\_\-decompressH}!decompress.c@{decompress.c}}
\subsubsection[{QSEC\_\-decompressH}]{\setlength{\rightskip}{0pt plus 5cm}int QSEC\_\-decompressH ({\bf QSEC\_\-decompression} $\ast$ {\em dcm}, \/  const unsigned int $\ast$ {\em buff}, \/  unsigned int $\ast$ {\em posn})}}
\label{decompress_8c_2c3b49bd367acba1c2d1634cb3b3839c}


Decode the next Huffman-encoded symbol. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to an initialsed, populated and processed decompression structure.\item[{\em buff}]Pointer to the buffer being decoded.\item[{\em posn}]Pointer to the current bit position in the buffer. Is updated by this routine.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The next symbol, which may be negative. \end{Desc}


References QSEC\_\-decompression\_\-::hdd.\hypertarget{decompress_8c_8e1340f1268535a22d719b926ea9d6bf}{
\index{decompress.c@{decompress.c}!QSEC\_\-deleteDecompression@{QSEC\_\-deleteDecompression}}
\index{QSEC\_\-deleteDecompression@{QSEC\_\-deleteDecompression}!decompress.c@{decompress.c}}
\subsubsection[{QSEC\_\-deleteDecompression}]{\setlength{\rightskip}{0pt plus 5cm}void QSEC\_\-deleteDecompression ({\bf QSEC\_\-decompression} $\ast$ {\em dcm})}}
\label{decompress_8c_8e1340f1268535a22d719b926ea9d6bf}


Free the memory associated with the decompression structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to an allocated decompression structure \end{description}
\end{Desc}
\hypertarget{decompress_8c_4ea59426abbf9a9d29ccff4b722264f7}{
\index{decompress.c@{decompress.c}!QSEC\_\-getCount@{QSEC\_\-getCount}}
\index{QSEC\_\-getCount@{QSEC\_\-getCount}!decompress.c@{decompress.c}}
\subsubsection[{QSEC\_\-getCount}]{\setlength{\rightskip}{0pt plus 5cm}unsigned int QSEC\_\-getCount ({\bf QSEC\_\-decompression} $\ast$ {\em dcm})}}
\label{decompress_8c_4ea59426abbf9a9d29ccff4b722264f7}


Return the number of non-zero bins in the histogram. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to a decompression structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Number of non-zero bins in the histogram \end{Desc}


References QSEC\_\-decompression\_\-::desc.\hypertarget{decompress_8c_de340d0845160b2d9f724d8492de9c0a}{
\index{decompress.c@{decompress.c}!QSEC\_\-newDecompression@{QSEC\_\-newDecompression}}
\index{QSEC\_\-newDecompression@{QSEC\_\-newDecompression}!decompress.c@{decompress.c}}
\subsubsection[{QSEC\_\-newDecompression}]{\setlength{\rightskip}{0pt plus 5cm}{\bf QSEC\_\-decompression}$\ast$ QSEC\_\-newDecompression (unsigned int {\em nbits}, \/  const char $\ast$ {\em name})}}
\label{decompress_8c_de340d0845160b2d9f724d8492de9c0a}


Allocate and initialise a new decompression structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em name}]String used in the reporting of error to identify a decompression structure\item[{\em nbits}]Number of symbols in the complete range of possible symbols (including excluded internal sub-ranges), hence the number of bins in the histogram and frequency tables\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to an allocated and initialised QSEC\_\-decompression structure \end{Desc}


References QSEC\_\-constructDecompression(), and QSEC\_\-sizeofDecompression().\hypertarget{decompress_8c_9500b01a3ec3df5a23d43cef2c2c58b2}{
\index{decompress.c@{decompress.c}!QSEC\_\-reportDecompression@{QSEC\_\-reportDecompression}}
\index{QSEC\_\-reportDecompression@{QSEC\_\-reportDecompression}!decompress.c@{decompress.c}}
\subsubsection[{QSEC\_\-reportDecompression}]{\setlength{\rightskip}{0pt plus 5cm}void QSEC\_\-reportDecompression ({\bf QSEC\_\-decompression} $\ast$ {\em dcm}, \/  FILE $\ast$ {\em fp})}}
\label{decompress_8c_9500b01a3ec3df5a23d43cef2c2c58b2}


Describe the contents of the decompression structure in formatted ASCII sent to the file {\em fp\/}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to the decompression structure\item[{\em fp}]Pointer to the file used as the destination \end{description}
\end{Desc}


References calc\_\-nbits(), QSEC\_\-decompression\_\-::desc, QSEC\_\-decompression\_\-::freq, QSEC\_\-decompression\_\-::name, QSEC\_\-decompression\_\-::nbits, QSEC\_\-decompression\_\-::rvlu, and QSEC\_\-decompression\_\-::table.

Referenced by QSEC\_\-reportExpansion().\hypertarget{decompress_8c_fb51bf6fcc032ed0be71fbf548003027}{
\index{decompress.c@{decompress.c}!QSEC\_\-sizeofDecompression@{QSEC\_\-sizeofDecompression}}
\index{QSEC\_\-sizeofDecompression@{QSEC\_\-sizeofDecompression}!decompress.c@{decompress.c}}
\subsubsection[{QSEC\_\-sizeofDecompression}]{\setlength{\rightskip}{0pt plus 5cm}size\_\-t QSEC\_\-sizeofDecompression (unsigned int {\em nbits})}}
\label{decompress_8c_fb51bf6fcc032ed0be71fbf548003027}


Calculate the total size required to accomodate a decompression structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em nbits}]Number of symbols in the complete range of possible symbols (including excluded internal sub-ranges), hence the number of bins in the histogram and frequency tables\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Size of memory block required to accomodate a decompression structure \end{Desc}


Referenced by addDcm(), QSEC\_\-newDecompression(), and QSEC\_\-sizeofExpansion().\hypertarget{decompress_8c_75cda4618e3e6a15275f3211527b0cab}{
\index{decompress.c@{decompress.c}!QSEC\_\-unpack@{QSEC\_\-unpack}}
\index{QSEC\_\-unpack@{QSEC\_\-unpack}!decompress.c@{decompress.c}}
\subsubsection[{QSEC\_\-unpack}]{\setlength{\rightskip}{0pt plus 5cm}const unsigned int$\ast$ QSEC\_\-unpack ({\bf QSEC\_\-decompression} $\ast$ {\em dcm}, \/  const unsigned int $\ast$ {\em buffer})}}
\label{decompress_8c_75cda4618e3e6a15275f3211527b0cab}


Unpack a histogram used for APE encoding. 

This routine build the necessary lookup and freqency tables by unpacking data from the consignment.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to an initialsed decompression structure\item[{\em buffer}]Pointer to the start of the buffer holding the packed structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to the next input location or NULL if there is an error in the unpacking \end{Desc}


References QSEC\_\-decompression\_\-::desc, QSEC\_\-decompression\_\-::freq, getwrd(), QSEC\_\-decompression\_\-::nbits, QSEC\_\-decompression\_\-::rvlu, and QSEC\_\-decompression\_\-::table.

Referenced by recoverUserAcd(), recoverUserCal(), recoverUserGem(), and recoverUserTkr().\hypertarget{decompress_8c_d9062d9c20327bcb3b21ac7237f68c4b}{
\index{decompress.c@{decompress.c}!QSEC\_\-unpackH@{QSEC\_\-unpackH}}
\index{QSEC\_\-unpackH@{QSEC\_\-unpackH}!decompress.c@{decompress.c}}
\subsubsection[{QSEC\_\-unpackH}]{\setlength{\rightskip}{0pt plus 5cm}const unsigned int$\ast$ QSEC\_\-unpackH ({\bf QSEC\_\-decompression} $\ast$ {\em dcm}, \/  const unsigned int $\ast$ {\em buffer})}}
\label{decompress_8c_d9062d9c20327bcb3b21ac7237f68c4b}


Unpack a table used for Huffman encoding. 

This routine build the necessary tables by unpacking data from the consignment.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to an initialsed decompression structure\item[{\em buffer}]Pointer to the start of the buffer holding the packed structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to the next input location or NULL if there is an error in the unpacking \end{Desc}


References QSEC\_\-decompression\_\-::hdd.

Referenced by recoverUserCal().