\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#275: Support Unsigned Values in binary Command}
\date{September 27, 2006}
\author{Pat Thoyts}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#275}&\textbf{Support Unsigned Values in binary Command}\\\hline
Author&

Pat Thoyts \tipmail{patthoyts}{users.sourceforge.net}
\\
Created&Wednesday, \(\text{27}^{\text{th}}\) September 2006\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.5 $\\
Keywords&Tcl, binary, unsigned\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to add support for unsigned values to the \textbf{binary} command.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

It is quite common when handling binary data to need to read unsigned values. All values read in by \textbf{binary scan} are converted to integers and sign extended, which requires code to trim the excess bits using the \textbf{expr} command if the values need to be treated as unsigned values. This makes Tcl slow when handling large quantities of binary data, for instance in crytographic or checksum functions. Simply by avoiding this \textbf{expr} operation we significantly improve the speed of processing such data.

\section{Specification}

The \textbf{binary scan} should be updated so as to add a flag identifier into the binary field format. This makes the field specification:

\begin{quote}
\tiplangle{}\textit{type code}\tiprangle{}\tiplangle{}\textit{flag}\tiprangle{}?\tiplangle{}\textit{length}\tiprangle{}?
\end{quote}

The flag character for unsigned fields (the only one defined) is ``u'', so the following are all acceptable:
\begin{description}
\item[cu*]
read all bytes as unsigned
\item[c2cu2]
two signed bytes then two unsigned bytes
\item[su2]
two unsigned little-endian shorts
\item[Su]
a single big-endian unsigned short.
\item[iu]
a single unsigned little-endian integer
\item[mu3]
three unsigned machine-endian 64-bit integers.
\end{description}

The ``u'' flag will be supported combined with all field types but will have no effect on non-integer types. Also the flag is valid but ignored for the \textbf{binary format} command.

\section{Reference Implementation}

A reference implementation is available in SourceForge Patch 156751 [\url{http://sf.net/tracker/?func=detail&aid=1565751&group_id=10894&atid=310894}].

\section{Copyright}

This document is placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
