\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#126: Rich Strings for Representation Persistence}
\date{January 30, 2003}
\author{Donal K. Fellows}
\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 \#126}&\textbf{Rich Strings for Representation Persistence}\\\hline
Author&

Donal K. Fellows \tipmail{donal.k.fellows}{man.ac.uk}
\\
Created&Thursday, \(\text{30}^{\text{th}}\) January 2003\\
Type&Project\\
Tcl Version&\(9.0\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.1 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP enriches the standard UTF-8 string representation of every \textit{Tcl\_Obj} to allow for improved persistence of non-string representations. This, combined with rules for substring and substitution handling, allows the lifetime of an object to correspond far more closely with the more-broadly understood concept of ``object lifetime''.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

At the moment in Tcl, whenever someone wants to create a stateful entity of limited lifespan (i.e. an object) and pass it through a Tcl script, they have to do one of two things:
\begin{enumerate}
\item{}
Tie the lifespan of the object to the lifespan of the \textit{Tcl\_Obj} value that represents it, so that when the internal representation of the value is deleted, so to is the object.
\setcounter{enumi}{1}
\item{}
Create a table (typically a hash table) of objects and have the value passed through the Tcl script be a handle that is really an index into this table. Deletion happens precisely when some kind of delete ``method'' is called on the object.
\end{enumerate}

Each of these techniques has problems. With the first, difficulties arise because it is a fundamental assumption of Tcl that it is always possible to recreate the internal-representation part of a value from the string-representation part of the value. While this is a good assumption for lists, numbers, etc. it is not true for anything where the deletion of the internal-rep results in the deletion of the underlying data structure. Thus, there is a tendency for the object to get deleted far too early. (In practise, the problem occurs in locations like scripts passed to Tk's [bind] command and in some invocations of the [eval] command.) Nevertheless, this technique can be used subject to some caveats, and this is done in a number of extensions (e.g. TclBlend/Jacl, where Java objects are passed through Tcl this way.)

However, the second technique has a different set of troubles. Although the process of explicit deletion works around all the faults with over-early deletion as described above, it instead has a strong tendency to not delete objects at all; it is far too easy to have a resource leak that is fairly difficult to track down. Most Tcl extensions that deal with objects (and all the ones that predate Tcl8.0, like [incr Tcl]) use this technique.

What we really need is a way to allow non-string object representations to persist substantially longer, so making the first of the two techniques outlined above much more robust. In particular, I have identified the string concatenation, string substitution and substring operations as being in need of attention, though obviously the required work will extend further as well (the script parser is an obvious target.) This is the focus of this TIP.

\section{Alterations to the Tcl\_Obj}

So, what is the best way of maintaining these valuable representations within a supposedly pure-string Tcl\_Obj value? Well, since we do not want to alter the internal representation (after all, it is that which we would really like to preserve) we will have to add an extra field (or potentially more) to the Tcl\_Obj structure itself. This is technically feasible in a backward-compatible way, as allocation of instances of this structure have always been performed by the Tcl library, but there is a significant downside to this in that the structure is far and away the most common structure allocated in the entire Tcl core. Any field added will have a significant impact on the overall memory consumption of any Tcl-enabled binary.

What information do we actually need to store for these representations to be preserved in a string while allowing extraction of the underlying values? The simplest possible option is for a list of string-subrange/object-reference pairs to be associated with the object, probably as an array of simple structures pointed to by a new field of the Tcl\_Obj (with a NULL indicating that no range of the string has an object associated with it.) The easiest way of representing those string ranges is as pairs of byte-indexes relative to the start of the string, though character-indexes have much to commend them (especially when working with strings with a UCS-16 internal representation) as do direct pointers into the string (easy to compute, but much more problematic when another string is appended.) The end of the list would be marked in some obvious way, probably by using a NULL in the object-reference part.

This mechanism has the advantage that it keeps the increase in size of the Tcl\_Obj itself fairly small (i.e. an extra 4 bytes for another pointer on 32-bit platforms) which is an advantage when you consider the fact that it is likely that most strings in an average Tcl program will not have objects contained within them. This will act to minimise the overall memory overhead.

\section{Concatenation, Substitution and Substring Semantics}

When two strings with these object annotations are concatenated, it is clear that the resulting string should also have the annotations (and the actual human-readable part will use the string-representation of the objects), and this is trivially extended to arbitrary concatenations of strings. Similarly for the taking of substrings with the following restrictions:
\begin{enumerate}
\item{}
Where the portion of substring taken corresponds exactly to the part of a string associated with an object, the operation shall instead return the object in question (which shall be assumed to have a compatible string representation.)
\setcounter{enumi}{1}
\item{}
Where a substring wholly contains a range associated with some object, then the resulting substring object will also contain the object associated with the ``same'' characters.
\setcounter{enumi}{2}
\item{}
Where a substring only partially overlaps a range associated with an object, that object will not be associated with the corresponding characters in the resultant substring (unless the object is separately part of the substring due to the other rules, of course.) The object is associated with the string segment as a whole, and not any one part of it.
\end{enumerate}

Substitution, whether of variable contents, script execution results or anything else, is semantically a concatenation operation where some strings are (as it were) immediate operands and others are derived from reading variables, executing scripts, etc.

Thus, if we start variable \textit{a} containing an object \textit{Ob1} and variable \textit{b} containing an object \textit{Ob2}, the following shall be true:
\begingroup\small\begin{verbatim}
set var x${a}y${b}z        => xOb1yOb2z
#  where characters 1-3 are assocaited with Ob1
#    and characters 5-7 are associated with Ob2
set c [string range $var 1 3]
#  precisely equivalent to [set c $a]
set d [string range $var 5 7]
#  precisely equivalent to [set d $b]
\end{verbatim}
\endgroup

\section{Consequences}

It is an obvious consequence of this that script evaluation should take into account of these object annotations when attached to the scripts themselves, particularly as the process of parsing can really be regarded as being mostly the taking of (suitable) substrings. Only slightly less obviously, it is also the responsibility of all code that stores strings (and especially scripts) for future use to store them as \textit{Tcl\_Obj} instances and not as just plain character strings, and to perform any substitutions it needs to perform in a way that preserves these object annotations on the parts that it is not interested in. This in turn will probably require changes on the part of many extensions to actually turn into reality.

On the other hand, there are quite a few objects (numbers and boolean values are probably very good examples here) for which this representation preservation is probably not a very good option as the objects in question are perfectly preservable. It makes sense to add some kind of signalling mechanism (e.g. a bit in a newly added \textit{flags} field) to allow the type of a \textit{Tcl\_Obj} instance to declare that it need not be preserved. As a general note, such a flag would only be useful in ``leaf'' objects; structural objects (i.e. those that are intended to contain others, like lists) would be expected to do without this.

Strings (now a structural as opposed to a leaf type) probably need even more special handling, but that can really be regarded as a type-specific special case.

The flags field mentioned a few paragraphs above would probably have other potential uses (e.g. for marking an object as being impossible to change into any other type) though these lie outside the scope of this TIP.

Because these changes at the C API level are far reaching and fairly subtle in some cases, this TIP explicitly seeks to introduce this behaviour with a major version number change. Although the alteration at the script level should be small --- existing code should continue working without alteration --- it is a huge philosophical leap as it will no longer be the case that everything in Tcl will be a string, or at least not a string that you (or anyone else) can type. Again, that implies introduction at a new major version number.

\section{Notes}
\begin{itemize}
\item{}
The existing API function \textit{Tcl\_InvalidateStringRep} will gain additional significance with the introduction of this TIP: its invocation may well trigger the deletion of many objects.
\item{}
It is probably a very good idea indeed for code that creates objects whose lifespan is meant to persist, to create those objects with string representations composed entirely of alphanumeric characters. An ideal choice might be to use a prefix derived from the type/class of the object, and a suffix that is the address of the object or the next value from some counter variable.
\end{itemize}

\section{Copyright}

This document is placed in the public domain.

\section{Colophon}

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