diff options
Diffstat (limited to 'doc/StringObj.3')
| -rw-r--r-- | doc/StringObj.3 | 14 |
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 |