diff options
Diffstat (limited to 'doc/StringObj.3')
| -rw-r--r-- | doc/StringObj.3 | 120 |
1 files changed, 113 insertions, 7 deletions
diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 8b80b2a..9c22037 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -4,13 +4,13 @@ '\" 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.22 2007/10/29 17:17:54 dgp Exp $ +'\" RCS: @(#) $Id: StringObj.3,v 1.23 2007/12/07 19:15:59 dgp Exp $ '\" .so man.macros .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings +Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendObjToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl objects as strings .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -62,6 +62,23 @@ void .sp void \fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR) +.VS 8.5 +.sp +void +\fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR) +.sp +Tcl_Obj * +\fBTcl_Format\fR(\fIinterp, format, objc, objv\fR) +.sp +int +\fBTcl_AppendFormatToObj\fR(\fIinterp, objPtr, format, objc, objv\fR) +.sp +Tcl_Obj * +\fBTcl_ObjPrintf\fR(\fIformat, ...\fR) +.sp +int +\fBTcl_AppendPrintfToObj\fR(\fIobjPtr, format, ...) +.VE 8.5 .sp void \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR) @@ -114,13 +131,20 @@ Null-terminated string value to append to \fIobjPtr\fR. .AP va_list argList in An argument list which must have been initialised using \fBva_start\fR, and cleared using \fBva_end\fR. +.AP int limit in +Maximum number of bytes to be appended. +.AP "const char" *ellipsis in +Suffix to append when the limit leads to string truncation. +If NULL is passed then the suffix "..." is used. +.AP "const char" *format in +Format control string including % conversion specifiers. +.AP int objc in +The number of elements to format or concatenate. +.AP Tcl_Obj *objv[] in +The array of objects to format or concatenate. .AP int newLength in New length for the string value of \fIobjPtr\fR, not including the final null character. -.AP int objc in -The number of elements to concatenate. -.AP Tcl_Obj *objv[] in -The array of objects to concatenate. .BE .SH DESCRIPTION @@ -229,6 +253,88 @@ must be a NULL pointer to indicate the end of the list. except that instead of taking a variable number of arguments it takes an argument list. .PP +.VS 8.5 +\fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR +except that it imposes 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 \fIbytes\fR are appended to \fIobjPtr\fR, but no more +than \fIlimit\fR bytes total are to be appended. If the limit prevents +all \fIlength\fR bytes that are available from being appended, then the +appending is done so that the last bytes appended are from the +string \fIellipsis\fR. This allows for an indication of the truncation +to be left in the string. +When \fIlength\fR is \fB-1\fR, all bytes up to the first zero byte are appended, +subject to the limit. When \fIellipsis\fR is NULL, the default +string \fB...\fR is used. When \fIellipsis\fR 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 \fIlength\fR and \fIlimit\fR when appending fewer +bytes is necessary to append only whole multi-byte characters. +.PP +\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 +.CS +Tcl_Format(interp, Tcl_GetString(objv[1]), objc-2, objv+2); +.CE +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 +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 \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 +.CS +Tcl_Obj *newPtr = Tcl_Format(interp, format, objc, objv); +if (newPtr == NULL) return TCL_ERROR; +Tcl_AppendObjToObj(objPtr, newPtr); +return TCL_OK; +.CE +but with greater convenience and efficiency when the appending +functionality is needed. +.PP +\fBTcl_ObjPrintf\fR serves as a replacement for the common sequence +.CS +char buf[SOME_SUITABLE_LENGTH]; +sprintf(buf, format, ...); +Tcl_NewStringObj(buf, -1); +.CE +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 +supported conversion specifiers is that of the \fBformat\fR command and +not that of the \fBsprintf\fR routine where the two sets differ. When a +conversion specifier passed to \fBTcl_ObjPrintf\fR includes a precision, +the value is taken as a number of bytes, as \fBsprintf\fR does, and not +as a number of characters, as \fBformat\fR 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 \fBsprintf\fR. Note in +this example usage, \fIx\fR is of type \fBlong\fR. +.CS +long x = 5; +Tcl_Obj *objPtr = Tcl_ObjPrintf("Value is %d", x); +.CE +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 +.CS +Tcl_AppendObjToObj(objPtr, Tcl_ObjPrintf(format, ...)); +.CE +but with greater convenience and efficiency when the appending +functionality is needed. +.VE 8.5 +.PP The \fBTcl_SetObjLength\fR procedure changes the length of the string value of its \fIobjPtr\fR argument. If the \fInewLength\fR argument is greater than the space allocated for the object's @@ -265,7 +371,7 @@ cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a newly-created object whose ref count is zero. .SH "SEE ALSO" -Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount +Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount, format, sprintf .SH KEYWORDS append, internal representation, object, object type, string object, |