\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#176: Add String Index Values}
\date{March 16, 2004}
\author{Damon Courtney, Don Porter, Damon Courtney}
\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 \#176}&\textbf{Add String Index Values}\\\hline
Author&

Damon Courtney \tipmail{damon}{unreality.com}
\par
Don Porter \tipmail{dgp}{users.sf.net}
\par
Damon Courtney \tipmail{damon-tcl}{tclhome.com}
\\
Created&Tuesday, \(\text{16}^{\text{th}}\) March 2004\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.8 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes extended index formats to be recognized by \textbf{TclGetIntForIndex}, supporting simple index arithmetic for string and list indices.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Most of Tcl's commands that accept an integer index of some kind also accept a string index in the format of \textit{end-N}. This is an extremely useful feature which I hope to extend just slightly by allowing simple addition to the standard index forms to be done during index processing. The change is mostly just syntactic sugar, but it extends a functionality that is already there and does not change any other syntax.

The aim of the proposal is to allow shorthand list and string operations like so:
\begingroup\small\begin{verbatim}
set x [lsearch $list $elem]
set new [lrange $list $x-1 $x+1]

set x [string first $string "foo"]
set new [string range $string $x $x+5]
\end{verbatim}
\endgroup

\section{Proposal}

The description of the supported index formats documented for the \textbf{string index} command will be updated to read:
\begin{itemize}
\item{}
\textit{integer}
\begin{itemize}
\item{}
For any index value that passes \textbf{string is integer -strict}, the char specified at this integral index (e.g. \textbf{2} would refer to the \textbf{c} in \textbf{abcd}).
\end{itemize}
\item{}
end
\begin{itemize}
\item{}
The last char of the string (e.g. \textbf{end} would refer to the \textbf{d} in \textbf{abcd}).
\end{itemize}
\item{}
end-\textit{N}
\begin{itemize}
\item{}
The last char of the string minus the specified integer offset \textit{N} (e.g. \textbf{end-1} would refer to the \textbf{c} in \textbf{abcd}).
\end{itemize}
\item{}
end+\textit{N}
\begin{itemize}
\item{}
The last char of the string plus the specified integer offset \textit{N} (e.g. \textbf{end+-1} would refer to the \textbf{c} in \textbf{abcd}).
\end{itemize}
\item{}
\textit{M}+\textit{N}
\begin{itemize}
\item{}
The char specified at the integral index that is the sum of integer values \textit{M} and \textit{N} (e.g. \textbf{1+1} would refer to the \textbf{c} in \textbf{abcd}).
\end{itemize}
\item{}
\textit{M}-\textit{N}
\begin{itemize}
\item{}
The char specified at the integral index that is the difference of integer values \textit{M} and \textit{N} (e.g. \textbf{2-1} would refer to the \textbf{b} in \textbf{abcd}).
\end{itemize}
\item{}
In the specifications above, the integer value \textit{M} contains no trailing whitespace and the integer value \textit{N} contains no leading whitespace.
\end{itemize}

The internal routine \textbf{TclGetIntForIndex} will be updated to implement the parsing specified by the documentation above.

The documentation of all Tcl commands that call \textbf{TclGetIntForIndex} to parse index values will be updated to refer to the documentation for \textbf{string index} for a description of the index format. These commands include \textbf{lindex}, \textbf{linsert}, \textbf{lrange}, \textbf{lreplace}, \textbf{lsearch}, \textbf{lset}, \textbf{lsort}, and \textbf{string}. This documentation update will remove any mention that the index values \textbf{e} and \textbf{en} are supported (as prefixes of \textbf{end}). Their support will be continued for compatibility, but that support will now be undocumented and deprecated.

The implementation of the commands \textbf{regexp -start} and \textbf{regsub -start} will be updated to call \textbf{TclGetIntForIndex} so that the full set of index formats will be supported. (Currently only integer values are accepted).

The error message produced by \textbf{TclGetIntForIndex} when parsing an invalid index will be updated to give the advice \textbf{must be integer?[+-]integer? or end?[+-]integer?}, in agreement with the extended set of index formats.

\section{Implementation}

Tcl Patch 1165695 is a draft implementation. It accomplishes everything proposed above except the update to the error message. If this proposal is accepted, that change, plus the large number of test suite updates it would require, will be added. Tests of the new functionality are also still to come.

\section{Compatibility}

Support for the index format end-\textit{N} where \textit{N} is an integer with leading whitespace is removed by this proposal. For example the string \textbf{end- 1} will no longer be recognized as a valid index. Most programmers are surprised to learn that this format is supported currently, so this incompatibility is not expected to cause much of a problem.

\section{Discussion Summary}

This feature is added as a quick, simple convenience to having to always use a full-blown expression for a minor task.

It was briefly discussed that since indexes already allowed a space between the --- and the N we should continue to support this, but it makes the implementation harder, and no one seemed to care that much. The fact that it breaks backwards compatibility is a small issue since no one seems to use indexes in this manner anyway.

The idea of making indexes extend a list beyond its length by doing something like [linsert \$list end+10 \$elem] was discussed but tabled since it is much harder to implement and is really outside the scope of this TIP. This may be something to discuss for a future TIP though.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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