diff options
Diffstat (limited to 'doc/SetResult.3')
| -rw-r--r-- | doc/SetResult.3 | 131 |
1 files changed, 41 insertions, 90 deletions
diff --git a/doc/SetResult.3 b/doc/SetResult.3 index c9ff84c..4bb9101 100644 --- a/doc/SetResult.3 +++ b/doc/SetResult.3 @@ -4,12 +4,12 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tcl_SetResult 3 8.7 Tcl "Tcl Library Procedures" +'\" +.TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME -Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult \- manipulate Tcl result +Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_FreeResult \- manipulate Tcl result .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -24,27 +24,25 @@ Tcl_Obj * const char * \fBTcl_GetStringResult\fR(\fIinterp\fR) .sp -\fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fB(char *)NULL\fR) +\fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fB(char *) NULL\fR) .sp \fBTcl_AppendResultVA\fR(\fIinterp, argList\fR) .sp -\fBTcl_ResetResult\fR(\fIinterp\fR) -.sp -\fBTcl_TransferResult\fR(\fIsourceInterp, code, targetInterp\fR) -.sp \fBTcl_AppendElement\fR(\fIinterp, element\fR) .sp +\fBTcl_ResetResult\fR(\fIinterp\fR) +.sp \fBTcl_FreeResult\fR(\fIinterp\fR) .SH ARGUMENTS -.AS Tcl_FreeProc sourceInterp out +.AS Tcl_FreeProc freeProc out .AP Tcl_Interp *interp out Interpreter whose result is to be modified or read. .AP Tcl_Obj *objPtr in -Tcl value to become result for \fIinterp\fR. +Object value to become result for \fIinterp\fR. .AP char *result in String value to become result for \fIinterp\fR or to be appended to the existing result. -.AP "const char" *element in +.AP char *element in String value to append as a list element to the existing result of \fIinterp\fR. .AP Tcl_FreeProc *freeProc in @@ -54,43 +52,37 @@ Address of procedure to call to release storage at .AP va_list argList in An argument list which must have been initialized using \fBva_start\fR, and cleared using \fBva_end\fR. -.AP Tcl_Interp *sourceInterp in -Interpreter that the result and return options should be transferred from. -.AP Tcl_Interp *targetInterp in -Interpreter that the result and return options should be transferred to. -.AP int code in -Return code value that controls transfer of return options. .BE .SH DESCRIPTION .PP The procedures described here are utilities for manipulating the result value in a Tcl interpreter. -The interpreter result may be either a Tcl value or a string. +The interpreter result may be either a Tcl object or a string. For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR -set the interpreter result to, respectively, a value and a string. +set the interpreter result to, respectively, an object and a string. Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR -return the interpreter result as a value and as a string. -The procedures always keep the string and value forms +return the interpreter result as an object and as a string. +The procedures always keep the string and object forms of the interpreter result consistent. For example, if \fBTcl_SetObjResult\fR is called to set -the result to a value, +the result to an object, then \fBTcl_GetStringResult\fR is called, -it will return the value's string representation. +it will return the object's string value. .PP \fBTcl_SetObjResult\fR arranges for \fIobjPtr\fR to be the result for \fIinterp\fR, replacing any existing result. -The result is left pointing to the value +The result is left pointing to the object referenced by \fIobjPtr\fR. \fIobjPtr\fR's reference count is incremented since there is now a new reference to it from \fIinterp\fR. -The reference count for any old result value -is decremented and the old result value is freed if no +The reference count for any old result object +is decremented and the old result object is freed if no references to it remain. .PP -\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as a value. -The value's reference count is not incremented; -if the caller needs to retain a long-term pointer to the value +\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as an object. +The object's reference count is not incremented; +if the caller needs to retain a long-term pointer to the object they should use \fBTcl_IncrRefCount\fR to increment its reference count in order to keep it from being freed too early or accidentally changed. .PP @@ -106,19 +98,19 @@ and \fBTcl_SetResult\fR re-initializes \fIinterp\fR's result to point to an empty string. .PP \fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string. -If the result was set to a value by a \fBTcl_SetObjResult\fR call, -the value form will be converted to a string and returned. -If the value's string representation contains null bytes, +If the result was set to an object by a \fBTcl_SetObjResult\fR call, +the object form will be converted to a string and returned. +If the object's string representation contains null bytes, this conversion will lose information. For this reason, programmers are encouraged to -write their code to use the new value API procedures +write their code to use the new object API procedures and to call \fBTcl_GetObjResult\fR instead. .PP \fBTcl_ResetResult\fR clears the result for \fIinterp\fR and leaves the result in its normal empty initialized state. -If the result is a value, +If the result is an object, its reference count is decremented and the result is left -pointing to an unshared value representing an empty string. +pointing to an unshared object representing an empty string. If the result is a dynamically allocated string, its memory is free*d and the result is left as a empty string. \fBTcl_ResetResult\fR also clears the error state managed by @@ -145,24 +137,12 @@ call; the last argument in the list must be a NULL pointer. .PP \fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that instead of taking a variable number of arguments it takes an argument list. -Interfaces using argument lists have been found to be nonportable in practice. -This function is deprecated and will be removed in Tcl 9.0. -.PP -\fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR -to \fItargetInterp\fR. The two interpreters must have been created in the -same thread. If \fIsourceInterp\fR and \fItargetInterp\fR are the same, -nothing is done. Otherwise, \fBTcl_TransferResult\fR moves the result -from \fIsourceInterp\fR to \fItargetInterp\fR, and resets the result -in \fIsourceInterp\fR. It also moves the return options dictionary as -controlled by the return code value \fIcode\fR in the same manner -as \fBTcl_GetReturnOptions\fR. -.SH "DEPRECATED INTERFACES" -.SS "OLD STRING PROCEDURES" +.SH "OLD STRING PROCEDURES" .PP -Use of the following procedures is deprecated +Use of the following procedures (is deprecated since they manipulate the Tcl result as a string. Procedures such as \fBTcl_SetObjResult\fR -that manipulate the result as a value +that manipulate the result as an object can be significantly more efficient. .PP \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in @@ -192,17 +172,19 @@ It also sets \fIinterp->freeProc\fR to zero, but does not change \fIinterp->result\fR or clear error state. \fBTcl_FreeResult\fR is most commonly used when a procedure is about to replace one result value with another. -.SS "DIRECT ACCESS TO INTERP->RESULT" +.SH "DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED" .PP It used to be legal for programs to directly read and write \fIinterp->result\fR -to manipulate the interpreter result. The Tcl headers no longer -permit this access. C code still doing this must -be updated to use supported routines \fBTcl_GetObjResult\fR, -\fBTcl_GetStringResult\fR, \fBTcl_SetObjResult\fR, and \fBTcl_SetResult\fR. +to manipulate the interpreter result. +Direct access to \fIinterp->result\fR is now strongly deprecated +because it can make the result's string and object forms inconsistent. +Programs should always read the result +using the procedures \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR, +and write the result using \fBTcl_SetObjResult\fR or \fBTcl_SetResult\fR. .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT" .PP -\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how +\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how the Tcl system is to manage the storage for the \fIresult\fR argument. If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called at a time when \fIinterp\fR holds a string result, @@ -231,43 +213,12 @@ This allows applications to use non-standard storage allocators. When Tcl no longer needs the storage for the string, it will call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and result that match the type \fBTcl_FreeProc\fR: -.PP .CS -typedef void \fBTcl_FreeProc\fR( - char *\fIblockPtr\fR); +typedef void Tcl_FreeProc(char *\fIblockPtr\fR); .CE -.PP When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to the value of \fIresult\fR passed to \fBTcl_SetResult\fR. - -.SH "REFERENCE COUNT MANAGEMENT" -.PP -The interpreter result is one of the main places that owns references to -values, along with the bytecode execution stack, argument lists, variables, -and the list and dictionary collection values. -.PP -\fBTcl_SetObjResult\fR takes a value with an arbitrary reference count -\fI(specifically including zero)\fR and guarantees to increment the reference -count. If code wishes to continue using the value after setting it as the -result, it should add its own reference to it with \fBTcl_IncrRefCount\fR. -.PP -\fBTcl_GetObjResult\fR returns the current interpreter result value. This will -have a reference count of at least 1. If the caller wishes to keep the -interpreter result value, it should increment its reference count. -.PP -\fBTcl_GetStringResult\fR does not manipulate reference counts, but the string -it returns is owned by (and has a lifetime controlled by) the current -interpreter result value; it should be copied instead of being relied upon to -persist after the next Tcl API call, as most Tcl operations can modify the -interpreter result. -.PP -\fBTcl_SetResult\fR, \fBTcl_AppendResult\fR, \fBTcl_AppendResultVA\fR, -\fBTcl_AppendElement\fR, and \fBTcl_ResetResult\fR all modify the interpreter -result. They may cause the old interpreter result to have its reference count -decremented and a new interpreter result to be allocated. After they have been -called, the reference count of the interpreter result is guaranteed to be 1. .SH "SEE ALSO" -Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp, -Tcl_GetReturnOptions +Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp .SH KEYWORDS -append, command, element, list, value, result, return value, interpreter +append, command, element, list, object, result, return value, interpreter |