\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#450: Add [binary] subcommand "set" for in-place modification}
\date{July 18, 2016}
\author{Arjen Markus}
\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 \#450}&\textbf{Add [binary] subcommand "set" for in-place modification}\\\hline
Author&

Arjen Markus \tipmail{arjen.markus895}{gmail.com}
\\
Created&Monday, \(\text{18}^{\text{th}}\) July 2016\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.1 $\\
Keywords&Tcl, binary data\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a simpler extension of the [binary] command than the related \cite{tip418}, namely just a subcommand \textbf{set} that updates an existing byte array in a variable instead of creating a new one like \textbf{binary format}. It does not propose an extension of the various formatting codes.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

As already argued in \cite{tip418}, the \textbf{binary} command is efficient in creating new objects of binary data or in parsing existing objects with such data. It is not currently efficient in \textit{updating} existing objects. However, such data objects are commonly used by compiled extensions.

As a consequence, if you want to manipulate such data objects from Tcl directly, it is easier to parse the object into, say, a list of numbers, use list commands like \textbf{lset} to replace individual values and pack it into a new binary array before passing it to a compiled extension.

\section{Specification}

This TIP proposes to add a subcommand \textbf{set} to the \textbf{binary} command with the following signature:

\begin{quote}
\textbf{binary set} \textit{varName formatString arg1 arg2 arg3 ...}
\end{quote}

The effect of this subcommand is that the byte array data contained in the variable ``varName'' is updated in a manner analogous to \textbf{lset}, but using a format string like \textbf{binary format}. It could be implemented in Tcl as:

\begin{quote}
set varName [binary format ``a*\$formatString'' \$varName \$arg1 \$arg2 \$arg3 ...]
\end{quote}

except that this allocates a new block of memory, sets that to null, copies the contents of \textit{varName} into that new block and then does the update.

The new command will have the effect that the first few steps are not necessary anymore.

\section{Implementation Notes}

Besides the nominal case of a variable that contains a binary array that is to be updated within the bounds of that array, three other cases exist and need to be prepared for:
\begin{itemize}
\item{}
The variable varName does not exist yet
\item{}
The variable varName does not contain a binary array
\item{}
The updating would go past the memory allocated for the binary array
\end{itemize}

Each of these cases and perhaps others will have to be taken care of. The first case might be treated as if \textbf{binary format} was meant. For the second case the implementation can convert the current value.

The third case might either cause an error (we are updating an existing block of memory after all) or silently extend the memory, effectively performing what the Tcl implementation shown above would do. If an error is thrown, then the first case should probably throw an error as well.

\section{Reference Implementation}

To be committed to a fossil branch.

A few remarks:
\begin{itemize}
\item{}
The third case is not completely treated yet (see ``TODO'' in the code)
\item{}
The \textbf{binary set} command does not properly invalidate the string representation. The binary array is, however, updated properly --- at least according to the very limited tests that were performed.
\item{}
There are no proper test cases yet.
\item{}
There is no proper performance measurement yet; this could be based on Wiki page \url{http://wiki.tcl.tk/44363.}
\item{}
It does not deal with the possibility that the binary array is shared.
\end{itemize}

\section{Copyright}

This document is placed in public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#418]{tip418}
Jeff Rogers,
\emph{Add [binary] Subcommands for In-Place Modification},
on-line at \url{http://purl.org/tcl/tip/418.html}
\end{thebibliography}
\end{document}
