diff options
Diffstat (limited to 'contrib/tcl/doc/SetResult.3')
-rw-r--r-- | contrib/tcl/doc/SetResult.3 | 200 |
1 files changed, 135 insertions, 65 deletions
diff --git a/contrib/tcl/doc/SetResult.3 b/contrib/tcl/doc/SetResult.3 index b70977d..5616de8 100644 --- a/contrib/tcl/doc/SetResult.3 +++ b/contrib/tcl/doc/SetResult.3 @@ -1,28 +1,34 @@ '\" '\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" SCCS: @(#) SetResult.3 1.19 96/06/05 18:00:15 +'\" SCCS: @(#) SetResult.3 1.23 97/06/26 14:05:57 '\" .so man.macros .TH Tcl_SetResult 3 7.5 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result string +Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result .SH SYNOPSIS .nf \fB#include <tcl.h>\fR .sp +\fBTcl_SetObjResult\fR(\fIinterp, objPtr\fR) +.sp +Tcl_Obj * +\fBTcl_GetObjResult\fR(\fIinterp\fR) +.sp \fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR) .sp -\fBTcl_AppendResult(\fIinterp, string, string, ... , \fB(char *) NULL\fR) +char * +\fBTcl_GetStringResult\fR(\fIinterp\fR) +.sp +\fBTcl_AppendResult\fR(\fIinterp, string, string, ... , \fB(char *) NULL\fR) .sp -.VS \fBTcl_AppendElement\fR(\fIinterp, string\fR) -.VE .sp \fBTcl_ResetResult\fR(\fIinterp\fR) .sp @@ -30,10 +36,12 @@ Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulat .SH ARGUMENTS .AS Tcl_FreeProc freeProc .AP Tcl_Interp *interp out -Interpreter whose result is to be modified. +Interpreter whose result is to be modified or read. +.AP Tcl_Obj *objPtr in +Object value to become result for \fIinterp\fR. .AP char *string in String value to become result for \fIinterp\fR or to be -appended to existing result. +appended to the existing result. .AP Tcl_FreeProc *freeProc in Address of procedure to call to release storage at \fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or @@ -42,51 +50,75 @@ Address of procedure to call to release storage at .SH DESCRIPTION .PP -The procedures described here are utilities for setting the -result/error string in a Tcl interpreter. +The procedures described here are utilities for manipulating the +result value in a Tcl interpreter. +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, an object and a string. +Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR +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 an object, +then \fBTcl_GetStringResult\fR is called, +it will return the object's string value. .PP -\fBTcl_SetResult\fR -arranges for \fIstring\fR to be the return string for the current Tcl -command in \fIinterp\fR, replacing any existing result. -If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR -refers to an area of static storage that is guaranteed not to be -modified until at least the next call to \fBTcl_Eval\fR. -.VS -If \fIfreeProc\fR -is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call -to \fBTcl_Alloc\fR and is now the property of the Tcl system. -\fBTcl_SetResult\fR will arrange for the string's storage to be -released by calling \fBTcl_Free\fR when it is no longer needed. -.VE -If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR -points to an area of memory that is likely to be overwritten when -\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame). -In this case \fBTcl_SetResult\fR will make a copy of the string in -dynamically allocated storage and arrange for the copy to be the -return string for the current Tcl command. +\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 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 object +is decremented and the old result object is freed if no +references to it remain. .PP -If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR, -\fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address -of a procedure that Tcl should call to free the string. -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: -.CS -typedef void Tcl_FreeProc(char *\fIblockPtr\fR); -.CE -When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to -the value of \fIstring\fR passed to \fBTcl_SetResult\fR. +\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 accidently changed. .PP +\fBTcl_SetResult\fR +arranges for \fIstring\fR to be the result for the current Tcl +command in \fIinterp\fR, replacing any existing result. +The \fIfreeProc\fR argument specifies how to manage the storage +for the \fIstring\fR argument; +it is discussed in the section +\fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below. If \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored and \fBTcl_SetResult\fR -re-initializes \fIinterp\fR's result to point to the pre-allocated result -area, with an empty string in the result area. +re-initializes \fIinterp\fR's result to point to an empty string. +.PP +\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as an string. +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 object API procedures +and to call \fBTcl_GetObjResult\fR instead. .PP -If \fBTcl_SetResult\fR is called at a time when \fIinterp\fR holds a -result, \fBTcl_SetResult\fR does whatever is necessary to dispose -of the old result (see the \fBTcl_Interp\fR manual entry for details -on this). +\fBTcl_ResetResult\fR clears the result for \fIinterp\fR +and leaves the result in its normal empty initialized state. +If the result is an object, +its reference count is decremented and the result is left +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 +\fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR, +and \fBTcl_SetErrorCode\fR. + +.SH OLD STRING PROCEDURES +.PP +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 an object +can be significantly more efficient. .PP \fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces. It takes each of its \fIstring\fR arguments and appends them in order @@ -100,8 +132,10 @@ of the result are produced. \fBTcl_AppendResult\fR takes care of all the storage management issues associated with managing \fIinterp\fR's result, such as allocating a larger result area if necessary. +It also converts the current interpreter result from an object +to a string, if necessary, before appending the argument strings. Any number of \fIstring\fR arguments may be passed in a single -call; the last argument in the list must be a NULL pointer. +call; the last argument in the list must be a NULL pointer. .PP \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in that it allows results to be built up in pieces. @@ -115,33 +149,69 @@ Under normal conditions, \fBTcl_AppendElement\fR will add a space character to \fIinterp\fR's result just before adding the new list element, so that the list elements in the result are properly separated. -.VS However if the new list element is the first in a list or sub-list (i.e. \fIinterp\fR's current result is empty, or consists of the single character ``{'', or ends in the characters `` {'') then no space is added. -.VE -.PP -\fBTcl_ResetResult\fR clears the result for \fIinterp\fR, -freeing the memory associated with it if the current result was -dynamically allocated. -It leaves the result in its normal initialized state with -\fIinterp->result\fR pointing to a static buffer containing -\fBTCL_RESULT_SIZE\fR characters, of which the first character -is zero. -\fBTcl_ResetResult\fR also clears the error state managed by -\fBTcl_AddErrorInfo\fR and \fBTcl_SetErrorCode\fR. .PP -\fBTcl_FreeResult\fR is a macro that performs part of the work +\fBTcl_FreeResult\fR performs part of the work of \fBTcl_ResetResult\fR. -It frees up the memory associated with \fIinterp\fR's result -and sets \fIinterp->freeProc\fR to zero, but it doesn't +It frees up the memory associated with \fIinterp\fR's result. +It also sets \fIinterp->freeProc\fR to zero, but doesn't 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. +.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. +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 +the Tcl system is to manage the storage for the \fIstring\fR argument. +If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called +at a time when \fIinterp\fR holds a string result, +they do whatever is necessary to dispose of the old string result +(see the \fBTcl_Interp\fR manual entry for details on this). +.PP +If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR +refers to an area of static storage that is guaranteed not to be +modified until at least the next call to \fBTcl_Eval\fR. +If \fIfreeProc\fR +is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call +to \fBTcl_Alloc\fR and is now the property of the Tcl system. +\fBTcl_SetResult\fR will arrange for the string's storage to be +released by calling \fBTcl_Free\fR when it is no longer needed. +If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR +points to an area of memory that is likely to be overwritten when +\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame). +In this case \fBTcl_SetResult\fR will make a copy of the string in +dynamically allocated storage and arrange for the copy to be the +result for the current Tcl command. +.PP +If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR, +\fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address +of a procedure that Tcl should call to free the string. +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: +.CS +typedef void Tcl_FreeProc(char *\fIblockPtr\fR); +.CE +When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to +the value of \fIstring\fR passed to \fBTcl_SetResult\fR. + .SH "SEE ALSO" -Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp +Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp .SH KEYWORDS -append, command, element, list, result, return value, interpreter +append, command, element, list, object, result, return value, interpreter |