\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#129: New Format Codes for the [binary] Command}
\date{March 14, 2003}
\author{Arjen Markus, Torsten Reincke}
\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 \#129}&\textbf{New Format Codes for the [binary] Command}\\\hline
Author&

Arjen Markus \tipmail{arjen.markus}{wldelft.nl}
\par
Torsten Reincke \tipmail{reincke}{typoscriptics.de}
\\
Created&Friday, \(\text{14}^{\text{th}}\) March 2003\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.5 $\\
Keywords&IEEE, binary data, Tcl\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to add a set of new format codes to the \textbf{binary} command to enhance its ability to deal with especially non-native floating-point data. The assumption is that current limitations are due to the distinction between little-endian and big-endian storage of such data.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Introduction}

The current \textbf{binary} command can manipulate little-endian and big-endian \textit{integer} data, but only \textit{native} floating-point data. This means that binary data from other computer systems that use a different representation of floating-point data can not be directly handled.

The lack of format codes to handle ``native'' integer data means that one has to distinguish the current platform's byte ordering to be platform-independent, whenever the \textbf{binary} command is used.

Most current computer systems use either little-endian or big-endian byte order and the so-called IEEE representation for the exponent and mantissa. So, the main variation to deal with is the endian-ness.

Some popular file formats, like ESRI's ArcView shape files, use both types of byte order. It is difficult (though not impossible) to handle these files with the current set of format codes.

It should be noted that there \textit{is} more variety among floating-point representation than just the byte order. This TIP will not solve this more general problem.

\section{Proposed Format Codes}

Format codes should be available to catch the two main varieties of byte ordering. There should, both for reasons of symmetry and for practical purposes, also be a full set to deal with ``native'' data.

For integer types there are no codes to deal with native ordering. So:
\begin{itemize}
\item{}
\textbf{t} (tiny) for short integers, using native ordering.
\item{}
\textbf{n} (normal) for ordinary integers, using native ordering.
\item{}
\textbf{m} (mirror of ``w'') for wide integers, using native ordering.
\end{itemize}

The floating-point types will be handled via:
\begin{itemize}
\item{}
\textbf{r}/\textbf{R} (real) for single-precision reals.
\item{}
\textbf{q}/\textbf{Q} (mirror of ``d'') for double-precision reals.
\end{itemize}

where the lower-case is associated with little-endian order and the upper-case with big-endian order.

\section{Implementation Notes}

The implementation for the integer types is simple:
\begin{itemize}
\item{}
The new format codes are synonyms for the current ones, but different ones for each endian-ness.
\end{itemize}

The implementation for the floating-point types is somewhat more complicated, this involves adding byte swapping, if the ordering of the platform does not correspond to that of the format code.

\section{Copyright}

This document is placed in the public domain.

\section{Colophon}

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