通讯编程

开发平台：
Visual C++

SetResult.3：源码内容
							'"
'" Copyright (c) 1989-1993 The Regents of the University of California.
'" 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.
'" 
'" RCS: @(#) $Id: SetResult.3,v 1.7 2002/01/25 20:40:55 dgp Exp $
'" 
.so man.macros
.TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
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
.sp
fBTcl_SetObjResultfR(fIinterp, objPtrfR)
.sp
Tcl_Obj *
fBTcl_GetObjResultfR(fIinterpfR)
.sp
fBTcl_SetResultfR(fIinterp, string, freeProcfR)
.sp
CONST char *
fBTcl_GetStringResultfR(fIinterpfR)
.sp
fBTcl_AppendResultfR(fIinterp, string, string, ... , fB(char *) NULLfR)
.sp
fBTcl_AppendResultVAfR(fIinterp, argListfR)
.sp
fBTcl_AppendElementfR(fIinterp, stringfR)
.sp
fBTcl_ResetResultfR(fIinterpfR)
.sp
fBTcl_FreeResultfR(fIinterpfR)
.SH ARGUMENTS
.AS Tcl_FreeProc freeProc
.AP Tcl_Interp *interp out
Interpreter whose result is to be modified or read.
.AP Tcl_Obj *objPtr in
Object value to become result for fIinterpfR.
.AP char *string in
String value to become result for fIinterpfR or to be
appended to the existing result.
.AP Tcl_FreeProc *freeProc in
Address of procedure to call to release storage at
fIstringfR, or fBTCL_STATICfR, fBTCL_DYNAMICfR, or
fBTCL_VOLATILEfR.
.AP va_list argList in
An argument list which must have been initialised using
fBTCL_VARARGS_STARTfR, and cleared using fBva_endfR.
.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 object or a string.
For example, fBTcl_SetObjResultfR and fBTcl_SetResultfR
set the interpreter result to, respectively, an object and a string.
Similarly, fBTcl_GetObjResultfR and fBTcl_GetStringResultfR
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_SetObjResultfR is called to set
the result to an object,
then fBTcl_GetStringResultfR is called,
it will return the object's string value.
.PP
fBTcl_SetObjResultfR
arranges for fIobjPtrfR to be the result for fIinterpfR,
replacing any existing result.
The result is left pointing to the object
referenced by fIobjPtrfR.
fIobjPtrfR's reference count is incremented
since there is now a new reference to it from fIinterpfR.
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_GetObjResultfR returns the result for fIinterpfR 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_IncrRefCountfR to increment its reference count
in order to keep it from being freed too early or accidently changed.
.PP
fBTcl_SetResultfR
arranges for fIstringfR to be the result for the current Tcl
command in fIinterpfR, replacing any existing result.
The fIfreeProcfR argument specifies how to manage the storage
for the fIstringfR argument;
it is discussed in the section
fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULTfR below.
If fIstringfR is fBNULLfR, then fIfreeProcfR is ignored
and fBTcl_SetResultfR
re-initializes fIinterpfR's result to point to an empty string.
.PP
fBTcl_GetStringResultfR returns the result for fIinterpfR as an string.
If the result was set to an object by a fBTcl_SetObjResultfR 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_GetObjResultfR instead.
.PP
fBTcl_ResetResultfR clears the result for fIinterpfR
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_ResetResultfR also clears the error state managed by
fBTcl_AddErrorInfofR, fBTcl_AddObjErrorInfofR,
and fBTcl_SetErrorCodefR.
.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_SetObjResultfR
that manipulate the result as an object
can be significantly more efficient.
.PP
fBTcl_AppendResultfR makes it easy to build up Tcl results in pieces.
It takes each of its fIstringfR arguments and appends them in order
to the current result associated with fIinterpfR.
If the result is in its initialized empty state (e.g. a command procedure
was just invoked or fBTcl_ResetResultfR was just called),
then fBTcl_AppendResultfR sets the result to the concatenation of
its fIstringfR arguments.
fBTcl_AppendResultfR may be called repeatedly as additional pieces
of the result are produced.
fBTcl_AppendResultfR takes care of all the
storage management issues associated with managing fIinterpfR'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 fIstringfR arguments may be passed in a single
call; the last argument in the list must be a NULL pointer.
.PP
fBTcl_AppendResultVAfR is the same as fBTcl_AppendResultfR except that
instead of taking a variable number of arguments it takes an argument list.
.PP
fBTcl_AppendElementfR is similar to fBTcl_AppendResultfR in
that it allows results to be built up in pieces.
However, fBTcl_AppendElementfR takes only a single fIstringfR
argument and it appends that argument to the current result
as a proper Tcl list element.
fBTcl_AppendElementfR adds backslashes or braces if necessary
to ensure that fIinterpfR's result can be parsed as a list and that
fIstringfR will be extracted as a single element.
Under normal conditions, fBTcl_AppendElementfR will add a space
character to fIinterpfR's result just before adding the new
list element, so that the list elements in the result are properly
separated.
However if the new list element is the first in a list or sub-list
(i.e. fIinterpfR's current result is empty, or consists of the
single character ``{'', or ends in the characters `` {'') then no
space is added.
.PP
fBTcl_FreeResultfR performs part of the work
of fBTcl_ResetResultfR.
It frees up the memory associated with fIinterpfR's result.
It also sets fIinterp->freeProcfR to zero, but doesn't
change fIinterp->resultfR or clear error state.
fBTcl_FreeResultfR 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->resultfR
to manipulate the interpreter result.
Direct access to fIinterp->resultfR 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_GetObjResultfR or fBTcl_GetStringResultfR,
and write the result using fBTcl_SetObjResultfR or fBTcl_SetResultfR.
.SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT"
.PP
fBTcl_SetResultfR's fIfreeProcfR argument specifies how 
the Tcl system is to manage the storage for the fIstringfR argument.
If fBTcl_SetResultfR or fBTcl_SetObjResultfR are called
at a time when fIinterpfR holds a string result,
they do whatever is necessary to dispose of the old string result
(see the fBTcl_InterpfR manual entry for details on this).
.PP
If fIfreeProcfR is fBTCL_STATICfR it means that fIstringfR
refers to an area of static storage that is guaranteed not to be
modified until at least the next call to fBTcl_EvalfR.
If fIfreeProcfR
is fBTCL_DYNAMICfR it means that fIstringfR was allocated with a call
to fBTcl_AllocfR and is now the property of the Tcl system.
fBTcl_SetResultfR will arrange for the string's storage to be
released by calling fBTcl_FreefR when it is no longer needed.
If fIfreeProcfR is fBTCL_VOLATILEfR it means that fIstringfR
points to an area of memory that is likely to be overwritten when
fBTcl_SetResultfR returns (e.g. it points to something in a stack frame).
In this case fBTcl_SetResultfR 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 fIfreeProcfR isn't one of the values fBTCL_STATICfR,
fBTCL_DYNAMICfR, and fBTCL_VOLATILEfR, 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 fIfreeProcfR. fIFreeProcfR should have arguments and
result that match the type fBTcl_FreeProcfR:
.CS
typedef void Tcl_FreeProc(char *fIblockPtrfR);
.CE
When fIfreeProcfR is called, its fIblockPtrfR will be set to
the value of fIstringfR passed to fBTcl_SetResultfR.
.SH "SEE ALSO"
Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp
.SH KEYWORDS
append, command, element, list, object, result, return value, interpreter

						