diff options
Diffstat (limited to 'doc/StringObj.3')
| -rw-r--r-- | doc/StringObj.3 | 142 |
1 files changed, 123 insertions, 19 deletions
diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 6a624db..e451c61 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -8,7 +8,7 @@ .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_AppendStringsToObjVA, 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 @@ -60,6 +60,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, ...\fR) +.VE 8.5 .sp void \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR) @@ -70,22 +87,20 @@ int Tcl_Obj * \fBTcl_ConcatObj\fR(\fIobjc, objv\fR) .SH ARGUMENTS -.AS "CONST Tcl_UniChar" *appendObjPtr in/out -.AP "CONST char" *bytes in -.VS 8.1 +.AS "const Tcl_UniChar" *appendObjPtr in/out +.AP "const char" *bytes in Points to the first byte of an array of UTF-8-encoded bytes used to set or append to a string object. -This byte array should not contain embedded null bytes -unless \fIlength\fR is negative. (Applications needing null bytes -should represent them as the two-byte sequence \fI\\700\\600\fR, use +This byte array may contain embedded null characters +unless \fInumChars\fR is negative. (Applications needing null bytes +should represent them as the two-byte sequence \fI\e700\e600\fR, use \fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if the string is a collection of uninterpreted bytes.) -.VE 8.1 .AP int length in The number of bytes to copy from \fIbytes\fR when initializing, setting, or appending to a string object. If negative, all bytes up to the first null are used. -.AP "CONST Tcl_UniChar" *unicode in +.AP "const Tcl_UniChar" *unicode in Points to the first byte of an array of Unicode characters used to set or append to a string object. This byte array may contain embedded null characters @@ -108,19 +123,26 @@ Points to an object to manipulate. The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. .AP int *lengthPtr out If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store -the the length of an object's string representation. -.AP "CONST char" *string in +the length of an object's string representation. +.AP "const char" *string in Null-terminated string value to append to \fIobjPtr\fR. .AP va_list argList in An argument list which must have been initialised using -\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR. +\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 @@ -130,7 +152,7 @@ be manipulated as string values. They use the internal representation of the object to store additional information to make the string manipulations more efficient. In particular, they make a series of append operations efficient by allocating extra storage space for the -string so that it doesn't have to be copied for each append. +string so that it does not have to be copied for each append. Also, indexing and length computations are optimized because the Unicode string representation is calculated and cached as needed. When using the \fBTcl_Append*\fR family of functions where the @@ -163,7 +185,7 @@ will be able to modify the string representation within the \fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR. Except for that limited purpose, the pointer returned by \fBTcl_GetStringFromObj\fR or \fBTcl_GetString\fR should be treated as read-only. It is -recommended that this pointer be assigned to a (CONST char *) variable. +recommended that this pointer be assigned to a (const char *) variable. Even in the limited situations where writing to this pointer is acceptable, one should take care to respect the copy-on-write semantics required by \fBTcl_Obj\fR's, with appropriate calls @@ -229,6 +251,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 +369,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, |