\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#270: Utility C Routines for String Formatting}
\date{June 19, 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 \#270}&\textbf{Utility C Routines for String Formatting}\\\hline
Author&

Don Porter \tipmail{dgp}{users.sf.net}
\\
Created&Monday, \(\text{19}^{\text{th}}\) June 2006\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.10 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes new public C utility routines for the convenience of C-coded extensions and embedded uses of Tcl.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Background}

During development of Tcl 8.5, several internal routines have been created that provide useful string formatting functions. These routines are most commonly used in the construction of error messages, but have a generally useful nature. The Tcl source code itself makes significant use of them.

Making some of these routines public also addresses Feature Request 1184069.

\section{Proposed Changes}

Add the following routines to Tcl's public interface:

\subsection{Tcl\_AppendObjToErrorInfo}

\begin{quote}
void \textbf{Tcl\_AppendObjToErrorInfo}(Tcl\_Interp *\textit{interp}, Tcl\_Obj *\textit{objPtr})
\end{quote}

This routine is analogous to the existing routine \textbf{Tcl\_AddErrorInfo}, but permits appending a Tcl\_Obj value rather than requiring a \textbf{(const char *)}.

\subsection{Tcl\_AppendLimitedToObj}

\begin{quote}
void \textbf{Tcl\_AppendLimitedToObj}(Tcl\_Obj *\textit{objPtr}, const char *\textit{bytes}, int \textit{length}, int \textit{limit}, const char *\textit{ellipsis})
\end{quote}

This routine is used to append a string, but to impose a limit on how many bytes are appended. This can be handy when the string to be appended might be very large, but the value being constructed should not be allowed to grow without bound. A common usage is when constructing an error message, where the end result should be kept short enough to be read. 

Bytes from \textit{bytes} are appended to \textit{objPtr}, but no more than \textit{limit} bytes total are to be appended. If the limit prevents all \textit{length} bytes that are available from being appended, then the appending is done so that the last bytes appended are from the string \textit{ellipsis}. This allows for an indication of the truncation to be left in the string.

When \textit{length} is -1, all bytes up to the first zero byte are appended, subject to the limit. When \textit{ellipsis} is NULL, the default string \textbf{...} is used. When \textit{ellipsis} is non-NULL, it must point to a zero-byte-terminated string in Tcl's internal UTF encoding. The number of bytes appended can be less than the lesser of \textit{length} and \textit{limit} when appending fewer bytes is necessary to append only whole multi-byte characters.

The \textit{objPtr} must be unshared, or the attempt to append to it will panic.

\subsection{Tcl\_Format}

\begin{quote}
Tcl\_Obj * \textbf{Tcl\_Format}(Tcl\_Interp *\textit{interp}, const char *\textit{format}, int \textit{objc}, Tcl\_Obj *const \textit{objv}[])
\end{quote}

This routine is the C-level interface to the engine of Tcl's \textbf{format} command. The actual command procedure for \textbf{format} is little more than
\begingroup\small\begin{verbatim}
 Tcl_Format(interp, Tcl_GetString(objv[1]), objc-2, objv+2);
\end{verbatim}
\endgroup

The \textit{objc} Tcl\_Obj values in \textit{objv} are formatted into a string according to the conversion specification in \textit{format} argument, following the documentation for the \textbf{format} command. The resulting formatted string is converted to a new Tcl\_Obj with refcount of zero and returned. If some error happens during production of the formatted string, NULL is returned, and an error message is recorded in \textit{interp}, if \textit{interp} is non-NULL.

\subsection{Tcl\_AppendFormatToObj}

\begin{quote}
int \textbf{Tcl\_AppendFormatToObj}(Tcl\_Interp *\textit{interp}, Tcl\_Obj *\textit{objPtr}, const char *\textit{format}, int \textit{objc}, Tcl\_Obj *const \textit{objv}[])
\end{quote}

This routine is an appending alternative form of \textbf{Tcl\_Format}. Its function is equivalent to:
\begingroup\small\begin{verbatim}
 Tcl_Obj *newPtr = Tcl_Format(interp, format, objc, objv);
 if (newPtr == NULL) return TCL_ERROR;
 Tcl_AppendObjToObj(objPtr, newPtr);
 return TCL_OK;
\end{verbatim}
\endgroup

But it is more convenient and efficient when the appending functionality is needed.

The \textit{objPtr} must be unshared, or the attempt to append to it will panic.

\subsection{Tcl\_ObjPrintf}

\begin{quote}
Tcl\_Obj * \textbf{Tcl\_ObjPrintf}(const char *\textit{format}, ...)
\end{quote}

This routine serves as a replacement for the common sequence:
\begingroup\small\begin{verbatim}
 char buf[SOME_SUITABLE_LENGTH];
 sprintf(buf, format, ...);
 Tcl_NewStringObj(buf, -1);
\end{verbatim}
\endgroup

Use of the proposed routine is shorter and doesn't require the programmer to determine \textbf{SOME\_SUITABLE\_LENGTH}. The formatting is done with the same core formatting engine used by \textbf{Tcl\_Format}. This means the set of supported conversion specifiers is that of Tcl's \textbf{format} command and not that of \textit{sprintf()} where the two sets differ. When a conversion specifier passed to \textbf{Tcl\_ObjPrintf} includes a precision, the value is taken as a number of bytes, as \textit{sprintf()} does, and not as a number of characters, as \textbf{format} does. This is done on the assumption that C code is more likely to know how many bytes it is passing around than the number of encoded characters those bytes happen to represent. The variable number of arguments passed in should be of the types that would be suitable for passing to \textit{sprintf()}. Note in this example usage, \textit{x} is of type \textbf{long}.
\begingroup\small\begin{verbatim}
  long x = 5;
  Tcl_Obj *objPtr = Tcl_ObjPrintf("Value is %d", x);
\end{verbatim}
\endgroup

If the value of \textit{format} contains internal inconsistencies or invalid specifier formats, the formatted string result produced by \textbf{Tcl\_ObjPrintf} will be an error message instead of any attempt to Do What Is Meant.

\subsection{Tcl\_AppendPrintfToObj}

\begin{quote}
void \textbf{Tcl\_AppendPrintfToObj}(Tcl\_Obj *\textit{objPtr}, const char *\textit{format}, ...)
\end{quote}

This routine is an appending alternative form of \textbf{Tcl\_ObjPrintf}. Its function is equivalent to:
\begingroup\small\begin{verbatim}
 Tcl_AppendObjToObj(objPtr, Tcl_ObjPrintf(format, ...));
\end{verbatim}
\endgroup

But it is more convenient and efficient when the appending functionality is needed.

The \textit{objPtr} must be unshared, or the attempt to append to it will panic.

\section{Compatibility}

This proposal includes only new features. It is believed that existing scripts and C code that operate without errors will continue to do so.

\section{Reference Implementation}

The actual code is already complete as internal routines corresponding to the proposed public routines. Implementation is just an exercise in renaming, placing in stub tables, documentation, etc.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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