trunk/c_cch0/c_cch0.tex

%$Header$

\chapter[\ccchzeroshorttitle{}]{\ccchzerolongtitle{}}

\label{ccch0}

\beginchapterquote{``\ldots{} Beauty is the first test:  there is no permanent
                   place in the world for ugly mathematics.''}
                   {G.H. Hardy \cite{bibref:b:mathematiciansapology:1940},
                   p.85}

\section{Introduction}
%Section Tag: INT


\section{crc32}

\begin{tclcommandname}{crc32}%
generates the CRC-32 of a file or string.  This CRC can be reliably used to obtain
digital signatures of files or data.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{crc32}{filename}
\tclcommandsynopsisline{crc32}{-string binarystringval}
\tclcommandsynopsisline{crc32}{-initialstate}
\tclcommandsynopsisline{crc32}{-advancestate state filename}
\tclcommandsynopsisline{crc32}{-advancestate -string state binarystringval}
\tclcommandsynopsisline{crc32}{-crcfromstate state}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{crc32} command forms the CRC-32 of the binary contents of a file
or of the binary contents of a string.  The CRC-32 is useful as a digital
signature, and can be used with unity probability to determine that two
files are different, or with a probability of about $1-2^{-32}$ to determine
that two files are almost certainly identical.  

In the invocations below, the CRC-32 is always returned as a 10-character ASCII string
of the form \emph{``0xDDDDDDDD''}, where \emph{``DDDDDDDD''} is the hexadecimal representation
of the 32-bit CRC-32, and \emph{``0x''} is a constant 2-character prefix which is included for
aesthetics.  It is guaranteed that:

\begin{itemize}
\item The string returned will be exclusive ASCII.
\item The string will have a length of exactly 10 characters.
\item The first two characters of the string will be \emph{``0x''}.
\item Any letters in the hexadecimal representation will be upper-case.
\end{itemize}

\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{crc32}{filename}}
Returns the CRC-32 of \emph{filename}, treated as an ordered collection of bytes (i.e.
newline characters and file termination characters are not treated---the file is 
treated as a binary file).  \emph{filename} must be specified in the form accepted by
the Tcl internals (forward slashes only).
\end{tclcommandinternaldescription}

\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{crc32}{-string binarystringval}}
Returns the CRC-32 of \emph{binarystringval}, treated as an ordered collection of bytes (i.e.
newline characters and string termination characters are not honored---the string is 
treated as a binary string).\footnote{For an ASCII string, the \emph{crc32} extension will
behave as expected, and will process all characters up to but not including the zero
terminator.  However, the \emph{crc32} extension will also correctly process non-ASCII strings.}
\end{tclcommandinternaldescription}


\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{crc32}{-initialstate}%
                                      \tclcommanddescsynopsisline{crc32}{-advancestate state filename}%
                                      \tclcommanddescsynopsisline{crc32}{-advancestate -string state filename}%
                                      \tclcommanddescsynopsisline{crc32}{-crcfromstate state}%
                                     }
The four forms above are designed to allow ``running CRCs'' to be calculated; in which
the CRC is calculated piecemeal.  These forms allow the caller to retain the internal
state vector of the CRC calculation algorithm.

The first form, \emph{crc32 -initialstate}, returns an ASCII representation of the
correct initial state vector of the CRC-32 state machine.  The client is required
to obtain this initial state before beginning a piecemeal CRC calculation.  Although the
returned string is a constant (it will always be the same), representational details
may change in future versions of the \emph{crc32} extension, and so a caller should never
make assumptions about what this invocation will return, as these assumptions may 
render a script incompatible with future versions of \emph{crc32}.

The second and third forms, \emph{crc32 -advancestate state filename}
and \emph{crc32 -advancestate -string state filename}, apply a file or a binary string
to \emph{state} to produce a new \emph{state}, which is returned.  This new \emph{state}
must be retained by the caller and used in subsequent calls.

The final form, \emph{crc32 -crcfromstate state}, maps from the state vector to the 
calculated CRC, and will return a 10-character ASCII string as described above.
\end{tclcommandinternaldescription}

\end{tclcommanddescription}


\begin{tclcommandusagenotes}
The ``piecemeal'' forms are as efficient as the file and string forms---there is no difference
in the internal algorithms.  The primary cost of the piecemeal forms is in importing and 
exporting the algorithm state vector to/from an ASCII string.  
Thus, the piecemeal forms become less efficient when
small files or strings are processed, as there are more exports and imports
of the state vector.  When using the piecemeal forms, processing the data in 
larger chunks will give better performance.
\end{tclcommandusagenotes}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\noindent\begin{figure}[!b]
\noindent\rule[-0.25in]{\textwidth}{1pt}
\begin{tiny}
\begin{verbatim}
$HeadURL$
$Revision$
$Date$
$Author$
\end{verbatim}
\end{tiny}
\noindent\rule[0.25in]{\textwidth}{1pt}
\end{figure}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%End of file C_CCH0.TEX
1	dashley	140	%$Header$
2
3			\chapter[\ccchzeroshorttitle{}]{\ccchzerolongtitle{}}
4
5			\label{ccch0}
6
7			\beginchapterquote{``\ldots{} Beauty is the first test: there is no permanent
8			place in the world for ugly mathematics.''}
9			{G.H. Hardy \cite{bibref:b:mathematiciansapology:1940},
10			p.85}
11
12			\section{Introduction}
13			%Section Tag: INT
14
15
16			\section{crc32}
17
18			\begin{tclcommandname}{crc32}%
19			generates the CRC-32 of a file or string. This CRC can be reliably used to obtain
20			digital signatures of files or data.
21			\end{tclcommandname}
22
23			\begin{tclcommandsynopsis}
24			\tclcommandsynopsisline{crc32}{filename}
25			\tclcommandsynopsisline{crc32}{-string binarystringval}
26			\tclcommandsynopsisline{crc32}{-initialstate}
27			\tclcommandsynopsisline{crc32}{-advancestate state filename}
28			\tclcommandsynopsisline{crc32}{-advancestate -string state binarystringval}
29			\tclcommandsynopsisline{crc32}{-crcfromstate state}
30			\end{tclcommandsynopsis}
31
32			\begin{tclcommanddescription}
33			The \emph{crc32} command forms the CRC-32 of the binary contents of a file
34			or of the binary contents of a string. The CRC-32 is useful as a digital
35			signature, and can be used with unity probability to determine that two
36			files are different, or with a probability of about $1-2^{-32}$ to determine
37			that two files are almost certainly identical.
38
39			In the invocations below, the CRC-32 is always returned as a 10-character ASCII string
40			of the form \emph{``0xDDDDDDDD''}, where \emph{``DDDDDDDD''} is the hexadecimal representation
41			of the 32-bit CRC-32, and \emph{``0x''} is a constant 2-character prefix which is included for
42			aesthetics. It is guaranteed that:
43
44			\begin{itemize}
45			\item The string returned will be exclusive ASCII.
46			\item The string will have a length of exactly 10 characters.
47			\item The first two characters of the string will be \emph{``0x''}.
48			\item Any letters in the hexadecimal representation will be upper-case.
49			\end{itemize}
50
51			\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{crc32}{filename}}
52			Returns the CRC-32 of \emph{filename}, treated as an ordered collection of bytes (i.e.
53			newline characters and file termination characters are not treated---the file is
54			treated as a binary file). \emph{filename} must be specified in the form accepted by
55			the Tcl internals (forward slashes only).
56			\end{tclcommandinternaldescription}
57
58			\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{crc32}{-string binarystringval}}
59			Returns the CRC-32 of \emph{binarystringval}, treated as an ordered collection of bytes (i.e.
60			newline characters and string termination characters are not honored---the string is
61			treated as a binary string).\footnote{For an ASCII string, the \emph{crc32} extension will
62			behave as expected, and will process all characters up to but not including the zero
63			terminator. However, the \emph{crc32} extension will also correctly process non-ASCII strings.}
64			\end{tclcommandinternaldescription}
65
66
67
68
69
70			\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{crc32}{-initialstate}%
71			\tclcommanddescsynopsisline{crc32}{-advancestate state filename}%
72			\tclcommanddescsynopsisline{crc32}{-advancestate -string state filename}%
73			\tclcommanddescsynopsisline{crc32}{-crcfromstate state}%
74			}
75			The four forms above are designed to allow ``running CRCs'' to be calculated; in which
76			the CRC is calculated piecemeal. These forms allow the caller to retain the internal
77			state vector of the CRC calculation algorithm.
78
79			The first form, \emph{crc32 -initialstate}, returns an ASCII representation of the
80			correct initial state vector of the CRC-32 state machine. The client is required
81			to obtain this initial state before beginning a piecemeal CRC calculation. Although the
82			returned string is a constant (it will always be the same), representational details
83			may change in future versions of the \emph{crc32} extension, and so a caller should never
84			make assumptions about what this invocation will return, as these assumptions may
85			render a script incompatible with future versions of \emph{crc32}.
86
87			The second and third forms, \emph{crc32 -advancestate state filename}
88			and \emph{crc32 -advancestate -string state filename}, apply a file or a binary string
89			to \emph{state} to produce a new \emph{state}, which is returned. This new \emph{state}
90			must be retained by the caller and used in subsequent calls.
91
92			The final form, \emph{crc32 -crcfromstate state}, maps from the state vector to the
93			calculated CRC, and will return a 10-character ASCII string as described above.
94			\end{tclcommandinternaldescription}
95
96			\end{tclcommanddescription}
97
98
99			\begin{tclcommandusagenotes}
100			The ``piecemeal'' forms are as efficient as the file and string forms---there is no difference
101			in the internal algorithms. The primary cost of the piecemeal forms is in importing and
102			exporting the algorithm state vector to/from an ASCII string.
103			Thus, the piecemeal forms become less efficient when
104			small files or strings are processed, as there are more exports and imports
105			of the state vector. When using the piecemeal forms, processing the data in
106			larger chunks will give better performance.
107			\end{tclcommandusagenotes}
108
109			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
110			\noindent\begin{figure}[!b]
111			\noindent\rule[-0.25in]{\textwidth}{1pt}
112			\begin{tiny}
113			\begin{verbatim}
114	dashley	275	$HeadURL$
115			$Revision$
116			$Date$
117			$Author$
118	dashley	140	\end{verbatim}
119			\end{tiny}
120			\noindent\rule[0.25in]{\textwidth}{1pt}
121			\end{figure}
122	dashley	275	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
123	dashley	140	%
124			%End of file C_CCH0.TEX
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision URL Header