\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#298: Revise Shared Value Rules for Tcl\_GetBignumAndClearObj}
\date{November 22, 2006}
\author{Don Porter}
\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 \#298}&\textbf{Revise Shared Value Rules for Tcl\_GetBignumAndClearObj}\\\hline
Author&

Don Porter \tipmail{dgp}{users.sf.net}
\\
Created&Wednesday, \(\text{22}^{\text{nd}}\) November 2006\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.6 $\\
Keywords&Tcl, Tcl\_Obj\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a revision to \textbf{Tcl\_GetBignumAndClearObj} to make it easier to use.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Background}

\textbf{Tcl\_GetBignumAndClearObj} was added by \cite{tip237}. Because \textit{mp\_int} values can be big, the interface is offered to avoid making a copy when the value already in the internal representation of an unshared \textit{Tcl\_Obj} will no longer be needed and can be moved instead of copied.

The basic intent was fine, but in practice, callers must go through these gymnastics to use it:
\begingroup\small\begin{verbatim}
 if (Tcl_IsShared(objPtr)) {
     Tcl_GetBignumFromObj(interp, objPtr, &bigValue);
 } else {
     Tcl_GetBignumAndClearObj(interp, objPtr, &bigValue);
 }
\end{verbatim}
\endgroup

It would make for a much more pleasant interface to move the test for a shared value into the routine itself.

\section{Proposed Change}

When passed a shared \textit{objPtr}, \textbf{Tcl\_GetBignumAndClearObj} will no longer panic, but will fall back to the copying behavior of \textbf{Tcl\_GetBignumFromObj}. The use of the \textbf{Tcl\_GetBignumAndClearObj} interface by a caller no longer means an assertion that \textit{objPtr} is unshared, and no longer guarantees that \textit{objPtr} will in fact be cleared, but merely indicates the caller will not be using the value anymore, and does not mind if it is cleared. That's all the caller should care about anyway.

Because of these changes in the implications and guarantees, the function is also renamed to \textbf{Tcl\_TakeBignumFromObj}.

With these changes, the code above may be simplified to:
\begingroup\small\begin{verbatim}
 Tcl_TakeBignumFromObj(interp, objPtr, &bigValue);
\end{verbatim}
\endgroup

\section{Compatibility}

This is a incompatible change only with 8.5 alpha releases.

\section{Reference Implementation}

Available from [\url{http://sourceforge.net/tracker/index.php?func=detail&aid=1601243&group_id=10894&atid=360894}].

\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 \#237]{tip237}
Kevin B. Kenny,
Don Porter,
\emph{Arbitrary-Precision Integers for Tcl},
on-line at \url{http://purl.org/tcl/tip/237.html}
\end{thebibliography}
\end{document}
