\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#200: Listing the Values in an Array}
\date{May 20, 2004}
\author{Donal K. Fellows, Dossy Shiobara}
\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 \#200}&\textbf{Listing the Values in an Array}\\\hline
Author&

Donal K. Fellows \tipmail{donal.k.fellows}{man.ac.uk}
\par
Dossy Shiobara \tipmail{dossy}{panoptic.com}
\\
Created&Thursday, \(\text{20}^{\text{th}}\) May 2004\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Rejected\\
Vote&Done\\
Version&\tipversion$Revision: 1.4 $\\
Keywords&Tcl\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes adding another subcommand to the \textbf{array} command to list the values in an array.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Currently, the easiest ways of building a list of all values within an array involve either iterating over the names of the array elements and then reading the value at each step, or iterating over the result of \textbf{array get} and dropping the \textit{name} part of each pair, as can be seen from these code examples:
\begingroup\small\begin{verbatim}
set list {}
foreach name [array names SomeArray] {
   lappend list $SomeArray($name)
}

set list {}
foreach {name value} [array get SomeArray] {
   lappend list $value
}
\end{verbatim}
\endgroup

Neither of these is especially efficient, since the first does a very large number of array reads, and the second builds a very large intermediate list (particularly if you subsequently want to filter the values to select a subset of them.)

It would be better if the functionality was added directly to the Tcl core, especially as the conceptual overhead would be very low as there are already subcommands of \textbf{array} for returning both the names of the array and the name/value pairs.

\section{Proposed Change}

I propose to add a new subcommand to \textbf{array} called \textbf{values} with the following syntax:

\begin{quote}
\textbf{array values} \textit{arrayName} ?\textit{globPattern}?
\end{quote}

This returns a list of values that are contained in the array in the ``natural order'' of the values within the array. The optional \textit{globPattern} argument allows for returning only some of the values in the array (those values for keys that match the pattern according to the rules of \textbf{string match}). The pattern will not change the ordering of the list; it only filters the result.

The order of the values returned shall be such that the following two \textbf{foreach} iterations shall behave identically (modulo traces on the array variable):
\begingroup\small\begin{verbatim}
foreach {name value} [array get AnyArray $pattern] {
   AnyScript
}
\end{verbatim}
\endgroup
\begingroup\small\begin{verbatim}
foreach name  [array names  AnyArray $pattern] \
        value [array values AnyArray $pattern] {
   AnyScript
}
\end{verbatim}
\endgroup

Note that this implies that the resulting list from \textbf{array values} may well contain duplicates, and that none of the values actually returned will necessarily match the supplied pattern.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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