summaryrefslogtreecommitdiffstats
path: root/doc/StringObj.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/StringObj.3')
-rw-r--r--doc/StringObj.314
1 files changed, 12 insertions, 2 deletions
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index 99bfdfb..5e08d8e 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: StringObj.3,v 1.28 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: StringObj.3,v 1.29 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
@@ -275,9 +275,11 @@ bytes is necessary to append only whole multi-byte characters.
\fBTcl_Format\fR is the C-level interface to the engine of the \fBformat\fR
command. The actual command procedure for \fBformat\fR is little more
than
+.PP
.CS
Tcl_Format(interp, Tcl_GetString(objv[1]), objc-2, objv+2);
.CE
+.PP
The \fIobjc\fR Tcl_Obj values in \fIobjv\fR are formatted into a string
according to the conversion specification in \fIformat\fR argument, following
the documentation for the \fBformat\fR command. The resulting formatted
@@ -287,22 +289,26 @@ returned, and an error message is recorded in \fIinterp\fR, if \fIinterp\fR
is non-NULL.
.PP
\fBTcl_AppendFormatToObj\fR is an appending alternative form
-of \fBTcl_Format\fR with functionality equivalent to
+of \fBTcl_Format\fR with functionality equivalent to:
+.PP
.CS
Tcl_Obj *newPtr = Tcl_Format(interp, format, objc, objv);
if (newPtr == NULL) return TCL_ERROR;
Tcl_AppendObjToObj(objPtr, newPtr);
return TCL_OK;
.CE
+.PP
but with greater convenience and efficiency when the appending
functionality is needed.
.PP
\fBTcl_ObjPrintf\fR serves as a replacement for the common sequence
+.PP
.CS
char buf[SOME_SUITABLE_LENGTH];
sprintf(buf, format, ...);
Tcl_NewStringObj(buf, -1);
.CE
+.PP
but with greater convenience and no need to
determine \fBSOME_SUITABLE_LENGTH\fR. The formatting is done with the same
core formatting engine used by \fBTcl_Format\fR. This means the set of
@@ -316,19 +322,23 @@ 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 \fBsprintf\fR. Note in
this example usage, \fIx\fR is of type \fBlong\fR.
+.PP
.CS
long x = 5;
Tcl_Obj *objPtr = Tcl_ObjPrintf("Value is %d", x);
.CE
+.PP
If the value of \fIformat\fR contains internal inconsistencies or invalid
specifier formats, the formatted string result produced by
\fBTcl_ObjPrintf\fR will be an error message describing the error.
.PP
\fBTcl_AppendPrintfToObj\fR is an appending alternative form
of \fBTcl_ObjPrintf\fR with functionality equivalent to
+.PP
.CS
Tcl_AppendObjToObj(objPtr, Tcl_ObjPrintf(format, ...));
.CE
+.PP
but with greater convenience and efficiency when the appending
functionality is needed.
.PP