\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#201: Add 'in' Operator to [expr]}
\date{May 21, 2004}
\author{Jeff Hobbs}
\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 \#201}&\textbf{Add 'in' Operator to [expr]}\\\hline
Author&

Jeff Hobbs \tipmail{jeffh}{activestate.com}
\\
Created&Friday, \(\text{21}^{\text{st}}\) May 2004\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.5 $\\
Keywords&Tk, list membership, sets\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes new \textbf{expr} operators ``\textbf{in}'' and ``\textbf{ni}'' that simplifies the standard ``does this item exist in list'' \textbf{lsearch} case in expressions, with ``\textbf{ni}'' being ``not in''.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The addition of \textbf{in} and \textbf{ni} operators is syntactic sugar for the verbose \textbf{lsearch} operation that checks for a single items existence (or non-existence) in a list. It serves to simplify the reading and writing of code that requires this comparatively-common operation. The operators will do \textbf{lsearch -exact} searching as well, which would correct an inadvertant bug that many users introduce into their code when they write:
\begingroup\small\begin{verbatim}
 if {[lsearch $list $item] != -1} { ... }
\end{verbatim}
\endgroup

as \textbf{lsearch} does \textbf{-glob} matching by default. I have found this error repeated often in user code.

Note that \cite{tip133} uses an \textbf{in} operator as a motivating case, but is actually proposing a much more general alteration.

\section{Specification}

A new infix \textbf{expr} operators \textbf{in} and \textbf{ni} will be added, making the following pairs of commands equivalent (assuming nobody has redefined \textbf{lsearch} of course):
\begin{itemize}
\item{}
Searching for an arbitrary item in an arbitrary list.
\begingroup\small\begin{verbatim}
 if {[lsearch -exact $list $item] != -1} { ... }
 if {$item in $list} { ... }
\end{verbatim}
\endgroup
\item{}
Checking for the absence of an arbitrary item from an arbitrary list.
\begingroup\small\begin{verbatim}
 if {[lsearch -exact $list $item] == -1} { ... }
 if {$item ni $list} { ... }
\end{verbatim}
\endgroup
\end{itemize}

\section{Comments}

There was a proposal to add a separate operator ``\textbf{!in}'' to do negated membership testing, but that significantly complicates the expression parser and is likely to be harder to teach to newcomers to Tcl, since it looks like the application of an operator to another operator.

\textbf{notin} and \textbf{ni} were also suggested, and \textbf{ni} was accepted as a reasonable pair for ``not in'', similar to \textbf{ne} being ``not equal''. There was some concern about \textbf{ni} in that TeX has a different interpretation, but that is unlikely to confuse the majority of Tcl users.

\section{Reference Implementation}

\textit{[To Follow]}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#133]{tip133}
Richard Suchenwirth,
\emph{Extending [expr] Operators},
on-line at \url{http://purl.org/tcl/tip/133.html}
\end{thebibliography}
\end{document}
