\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#224: Add New [array] Subcommands 'incr' and 'value'}
\date{September 28, 2004}
\author{Peter MacDonald, Robert Seeger}
\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 \#224}&\textbf{Add New [array] Subcommands 'incr' and 'value'}\\\hline
Author&

Peter MacDonald \tipmail{peter}{pdqi.com}
\par
Robert Seeger \tipmail{rseeger00}{aol.com}
\\
Created&Tuesday, \(\text{28}^{\text{th}}\) September 2004\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.12 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

The TIP proposes the addition to two new subcommands to the \textbf{array} command: \textbf{incr} and \textbf{value}. The \textit{'incr} subcommand would increment an element in an array. The \textbf{value} subcommand would query, reference, and/or initialize an array element.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

\cite{tip215} proposed modifying the \textbf{incr} command to auto-initialize variables which do not exist, rather than throwing an error. After some debate, it was identified that frequency counting in arrays was the primary area of interest. In particular, the excessive use of \textit{if/info exists} constructs in such code is inefficient, verbose and rather difficult to read. The addition of these two subcommands could substantially reduce the complexity of much Tcl code.

\section{Specification}

Two new subcommands will be added to \textbf{array}, being \textbf{incr} and \textbf{value}. Both commands take an array name and an elem parameter, but, no string match is performed on elem.

\subsection{array incr}

\begin{quote}
\textbf{array incr} \textit{var elem} ?\textit{value}? ?\textit{init}?
\end{quote}

The \textbf{array incr} subcommand would increment \textit{var}(\textit{elem}), if it exists, by \textit{value}, otherwise, initializes it to \textit{init}. The default for \textit{value} is 1, and the default for \textit{init} is 0. The subcommand will return the new value and will support both integer and double values (based on the rules for addition in \textbf{expr}).

\subsection{array value}

\begin{quote}
\textbf{array value} \textit{var elem} ?\textit{value}? ?\textit{init}?
\end{quote}

The \textbf{array value} would just return the current contents of \textit{var}(\textit{elem}) if it exists, or \textit{value} otherwise. If the \textit{init} parameter resolves to true (as determined by \textit{Tcl\_GetBooleanFromObj()} of course), the variable is initialized to \textit{value} if it doesn't already exist. The default for \textit{value} is the empty string, and the default for \textit{init} is false.

\section{Reference Implementation}

Following is a Tcl only implementation of the \textbf{incr}/\textbf{value} subcommands:
\begingroup\small\begin{verbatim}
proc Array {cmd var elem {amt {}} {init 0}} {
   # Implement the Array subcmds incr and value on var(elem):
   #  - incr   increment a variable by amt or initialize
   #           to init if undefined.
   #  - value  return the value if defined, else return amt
   #           initializing if init.
   upvar $var uvar
   if {[string match $cmd* incr]} {
      if {$amt == {}} { set amt 1 }
      if {[info exists uvar($elem)]} {
         return [set uvar($elem) [expr {$uvar($elem)+$amt}]]
      }
      return [set uvar($elem) $init]
   } elseif {[string match $cmd* value]} {
      if {[info exists uvar($elem)]} {
         return $uvar($elem)
      }
      if {$init} {
         return [set uvar($elem) $amt]
      }
      return $amt
   } else {
      error "usage: Array incr|value var elem ?amt? ?init?"
   }
}
\end{verbatim}
\endgroup

\section{Discussion}
\begin{itemize}
\item{}
Wangnic notes:

\textbf{array value} \textit{var elem} \textbf{"" false} can be written as \textbf{array get} \textit{var elem}

Array get returns name/value pairs. Array value returns just the value. Also if elem has a * in it, there may be multiple matches.
\item{}
Hobbs notes:

\cite{tip200} already rejected \textit{array values}

A single item is returned from \textit{array value}, not a list, as there is no string match on elem.

The problem domain is not list processing (which is expected to be relatively expensive), but rather frequency counting and set matching.
\item{}
RHSeeger notes:

It would seem more consistant to push for the \textit{incr} command to include a way to initialize a variable if it doesn't exist (as per \cite{tip215} or the discussed options contained therein), rather than add an incr subcommand to array.

Being a fan or reintroducing the \textit{array values} TIP (since the core mailing list indicates it was never fully rejected), I think \textit{array value} might be a bit confusing, being only off by the lack of plurality. (I was one of the people pushing for \cite{tip200} though, so take that aspect with a grain of salt)
\end{itemize}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#2}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#200]{tip200}
Donal K. Fellows,
Dossy Shiobara,
\emph{Listing the Values in an Array},
on-line at \url{http://purl.org/tcl/tip/200.html}
\bibitem[TIP \#215]{tip215}
Andreas Leitgeb,
Don Porter,
\emph{Make [incr] Auto-Initialize Undefined Variables},
on-line at \url{http://purl.org/tcl/tip/215.html}
\end{thebibliography}
\end{document}
