\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#347: Align 'string is ...' to Type-Conversion Functions in 'expr'}
\date{February 09, 2009}
\author{Jos Decoster}
\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 \#347}&\textbf{Align 'string is ...' to Type-Conversion Functions in 'expr'}\\\hline
Author&

Jos Decoster \tipmail{jos.decoster}{gmail.com}
\\
Created&Monday, \(\text{9}^{\text{th}}\) February 2009\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Withdrawn\\
Vote&Pending\\
Version&\tipversion$Revision: 1.8 $\\
Keywords&Tcl\\
Obsoleted By&395\\
Post History&\\
Discussions To&news:comp.lang.tcl\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

The \textbf{string} command supports tests for a number of Tcl's basic types, for example, integers, doubles, and booleans. The \textbf{tcl::mathfunc} mathematical functions provides sevaral functions to limit the number of bits used in integer numbers. This TIP proposes to align both groups of functions for \textbf{int}, \textbf{long}, \textbf{wide} and \textbf{entier}.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The \textbf{string} command includes tests for the common Tcl types: \textbf{string is boolean}, \textbf{string is double} and \textbf{string is integer}. Some of the integer ranges used in Tcl internals are missing from the list, making it difficult for an input validation procedure to determine whether, in fact, a string contains a valid integer number to be used for that specific Tcl command. 

Ranges already present are:
\begin{itemize}
\item{}
\textbf{integer}
\item{}
\textbf{wideinteger}
\end{itemize}

Missing ranges are:
\begin{itemize}
\item{}
\textbf{long}
\item{}
\textbf{entier}
\end{itemize}

The \textbf{::tcl::mathfunc} mathematical functions provides sevaral functions to limit the number of bits used in integer numbers. Some of the integer ranges used in Tcl internals are missing from the list, and other check an unexpected range. 

Functions already present are:
\begin{itemize}
\item{}
\textbf{wide}
\item{}
\textbf{entier}
\end{itemize}

Functions already present but with unexpected behavior are:
\begin{itemize}
\item{}
\textbf{int} actually does a \textbf{long} conversion
\end{itemize}

Missing functions are:
\begin{itemize}
\item{}
\textbf{long}
\end{itemize}

Providing a \textbf{string is} function for every integer range used in Tcl internals will make it possible to check every argument in input validation procedures before calling a Tcl command. Providing \textbf{::tcl::mathfunc} for every integer range used in Tcl internals will make it possible to create values in a valid range before calling a Tcl command.

Having the same integer range names in the \textbf{string is} functions and in the \textbf{::tcl::mathfunc} when they act on the same integer ranges would make the commands easier to recognise.

\section{Specification}

This document proposes:
\begin{itemize}
\item{}
augmenting the \textbf{string is} command with a \textbf{string is long} that functions the same as \textbf{string is integer} in every respect except for the fact that it accepts any string containing a substring that is valid as a long integer (that is, acceptable to \textit{Tcl\_GetLongFromObj}) possibly surrounded by whitespace.
\item{}
augmenting the \textbf{string is} command with a \textbf{string is entier} that functions the same as \textbf{string is integer} in every respect except for the fact that it accepts any string containing a substring that is valid as a bignum integer (that is, acceptable to \textit{Tcl\_GetBignumFromObj}) possibly surrounded by whitespace.
\item{}
modifying the \textbf{::tcl::mathfunc::int} to convert to an integer (that is, acceptable to \textit{Tcl\_GetIntFromObj}).
\item{}
adding the \textbf{::tcl::mathfunc::long} to convert to a long integer (that is, acceptable to \textit{Tcl\_GetLongFromObj}).
\item{}
keeping the \textbf{string is integer} command as it can be abbreviated to \textbf{string is int} to align with \textbf{::tcl::mathfunc::int}.
\item{}
keeping the \textbf{string is wideinteger} command as it can be abbreviated to \textbf{string is wide} to align with \textbf{::tcl::mathfunc::wide}.
\end{itemize}

\section{Compatibility}

On platforms where a \textit{'long} variable has a different range than an \textbf{int} variable, renaming the \textbf{::tcl::mathfunc::int} to \textbf{::tcl::mathfunc::long} will let code like:

 \tipbar{} set a [expr \{int(\$b)\}]

behave differently for \textbf{long} values outside the \textbf{int} range.

\section{Alternatives}

The \textbf{bignum} was rejected in favor of \textbf{entier} because \textbf{entier} is already used in \textbf{::tcl::mathfunc::entier}.

\section{Reference Implementation}

Patches that implement the above, provide test cases for it, and update documentation to include it are available at SourceForge as Tcl Patch \#2581150[\url{http://sourceforge.net/tracker2/?func=detail&aid=2581150&group_id=10894&atid=310894}].

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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