1Tcl_SetResult(3)            Tcl Library Procedures            Tcl_SetResult(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult,
9       Tcl_AppendResult, Tcl_AppendResultVA,  Tcl_AppendElement,  Tcl_ResetRe‐
10       sult, Tcl_FreeResult - manipulate Tcl result
11

SYNOPSIS

13       #include <tcl.h>
14
15       Tcl_SetObjResult(interp, objPtr)
16
17       Tcl_Obj *
18       Tcl_GetObjResult(interp)
19
20       Tcl_SetResult(interp, result, freeProc)
21
22       const char *
23       Tcl_GetStringResult(interp)
24
25       Tcl_AppendResult(interp, result, result, ... , (char *) NULL)
26
27       Tcl_AppendResultVA(interp, argList)
28
29       Tcl_AppendElement(interp, element)
30
31       Tcl_ResetResult(interp)
32
33       Tcl_FreeResult(interp)
34

ARGUMENTS

36       Tcl_Interp *interp (out)            Interpreter  whose  result is to be
37                                           modified or read.
38
39       Tcl_Obj *objPtr (in)                Object value to become  result  for
40                                           interp.
41
42       char *result (in)                   String  value  to become result for
43                                           interp or to  be  appended  to  the
44                                           existing result.
45
46       char *element (in)                  String  value  to  append as a list
47                                           element to the existing  result  of
48                                           interp.
49
50       Tcl_FreeProc *freeProc (in)         Address  of  procedure  to  call to
51                                           release  storage  at   result,   or
52                                           TCL_STATIC,     TCL_DYNAMIC,     or
53                                           TCL_VOLATILE.
54
55       va_list argList (in)                An argument list  which  must  have
56                                           been  initialized  using  va_start,
57                                           and cleared using va_end.
58_________________________________________________________________
59

DESCRIPTION

61       The procedures described here are utilities for manipulating the result
62       value in a Tcl interpreter.  The interpreter result may be either a Tcl
63       object or a string.  For example,  Tcl_SetObjResult  and  Tcl_SetResult
64       set  the  interpreter  result to, respectively, an object and a string.
65       Similarly, Tcl_GetObjResult and Tcl_GetStringResult return  the  inter‐
66       preter result as an object and as a string.  The procedures always keep
67       the string and object forms of the interpreter result consistent.   For
68       example,  if Tcl_SetObjResult is called to set the result to an object,
69       then Tcl_GetStringResult is called, it will return the object's  string
70       value.
71
72       Tcl_SetObjResult  arranges  for  objPtr  to  be  the result for interp,
73       replacing any existing result.  The result  is  left  pointing  to  the
74       object  referenced  by objPtr.  objPtr's reference count is incremented
75       since there is now a new reference to it from  interp.   The  reference
76       count  for  any  old  result  object  is decremented and the old result
77       object is freed if no references to it remain.
78
79       Tcl_GetObjResult returns the result  for  interp  as  an  object.   The
80       object's  reference  count  is  not incremented; if the caller needs to
81       retain a long-term pointer to the object they should  use  Tcl_IncrRef‐
82       Count  to  increment its reference count in order to keep it from being
83       freed too early or accidentally changed.
84
85       Tcl_SetResult arranges for result to be the result for the current  Tcl
86       command  in  interp, replacing any existing result.  The freeProc argu‐
87       ment specifies how to manage the storage for the result argument; it is
88       discussed  in  the  section  THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT
89       below.  If result is NULL, then freeProc is ignored  and  Tcl_SetResult
90       re-initializes interp's result to point to an empty string.
91
92       Tcl_GetStringResult  returns the result for interp as a string.  If the
93       result was set to an object by a Tcl_SetObjResult call, the object form
94       will  be  converted  to  a string and returned.  If the object's string
95       representation contains null bytes, this conversion will lose  informa‐
96       tion.   For this reason, programmers are encouraged to write their code
97       to use the new object  API  procedures  and  to  call  Tcl_GetObjResult
98       instead.
99
100       Tcl_ResetResult  clears  the result for interp and leaves the result in
101       its normal empty initialized state.  If the result is  an  object,  its
102       reference  count  is  decremented and the result is left pointing to an
103       unshared object representing an empty  string.   If  the  result  is  a
104       dynamically  allocated  string,  its memory is free*d and the result is
105       left as a empty string.  Tcl_ResetResult also clears  the  error  state
106       managed by Tcl_AddErrorInfo, Tcl_AddObjErrorInfo, and Tcl_SetErrorCode.
107
108       Tcl_AppendResult  makes  it easy to build up Tcl results in pieces.  It
109       takes each of its result arguments and appends them  in  order  to  the
110       current  result  associated  with interp.  If the result is in its ini‐
111       tialized empty state (e.g. a command  procedure  was  just  invoked  or
112       Tcl_ResetResult was just called), then Tcl_AppendResult sets the result
113       to the concatenation of its result arguments.  Tcl_AppendResult may  be
114       called  repeatedly  as  additional  pieces  of the result are produced.
115       Tcl_AppendResult takes care of all the storage management issues  asso‐
116       ciated  with  managing  interp's  result,  such  as allocating a larger
117       result area if necessary.  It also manages conversion to and  from  the
118       result  field of the interp so as to handle backward-compatibility with
119       old-style extensions.  Any number of result arguments may be passed  in
120       a single call; the last argument in the list must be a NULL pointer.
121
122       Tcl_AppendResultVA  is the same as Tcl_AppendResult except that instead
123       of taking a variable number of arguments it takes an argument list.
124

OLD STRING PROCEDURES

126       Use of the following procedures (is deprecated  since  they  manipulate
127       the  Tcl  result as a string.  Procedures such as Tcl_SetObjResult that
128       manipulate the result as an object can be significantly more efficient.
129
130       Tcl_AppendElement is similar to  Tcl_AppendResult  in  that  it  allows
131       results  to  be  built  up in pieces.  However, Tcl_AppendElement takes
132       only a single element argument and it appends that argument to the cur‐
133       rent result as a proper Tcl list element.  Tcl_AppendElement adds back‐
134       slashes or braces if necessary to ensure that interp's  result  can  be
135       parsed  as  a  list and that element will be extracted as a single ele‐
136       ment.  Under normal conditions,  Tcl_AppendElement  will  add  a  space
137       character  to  interp's result just before adding the new list element,
138       so that the list elements in the result are properly  separated.   How‐
139       ever  if  the new list element is the first in a list or sub-list (i.e.
140       interp's current result is empty, or consists of the  single  character
141       “{”, or ends in the characters “ {”) then no space is added.
142
143       Tcl_FreeResult  performs part of the work of Tcl_ResetResult.  It frees
144       up  the  memory  associated  with  interp's  result.   It   also   sets
145       interp->freeProc  to  zero, but does not change interp->result or clear
146       error state.  Tcl_FreeResult is most commonly used when a procedure  is
147       about to replace one result value with another.
148

DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED

150       It   used  to  be  legal  for  programs  to  directly  read  and  write
151       interp->result to manipulate the interpreter result.  Direct access  to
152       interp->result  is  now  strongly  deprecated  because  it can make the
153       result's string and object forms inconsistent.  Programs should  always
154       read  the  result  using  the  procedures  Tcl_GetObjResult or Tcl_Get‐
155       StringResult, and write the result using Tcl_SetObjResult or Tcl_SetRe‐
156       sult.
157

THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT

159       Tcl_SetResult's  freeProc  argument  specifies how the Tcl system is to
160       manage the storage  for  the  result  argument.   If  Tcl_SetResult  or
161       Tcl_SetObjResult  are  called  at  a  time  when  interp holds a string
162       result, they do whatever is necessary to  dispose  of  the  old  string
163       result (see the Tcl_Interp manual entry for details on this).
164
165       If  freeProc  is  TCL_STATIC  it means that result refers to an area of
166       static storage that is guaranteed not to be modified until at least the
167       next call to Tcl_Eval.  If freeProc is TCL_DYNAMIC it means that result
168       was allocated with a call to Tcl_Alloc and is now the property  of  the
169       Tcl  system.  Tcl_SetResult will arrange for the string's storage to be
170       released by calling Tcl_Free when it is no longer needed.  If  freeProc
171       is  TCL_VOLATILE  it means that result points to an area of memory that
172       is likely to be overwritten when Tcl_SetResult returns (e.g. it  points
173       to something in a stack frame).  In this case Tcl_SetResult will make a
174       copy of the string in dynamically allocated storage and arrange for the
175       copy to be the result for the current Tcl command.
176
177       If  freeProc  is  not  one  of  the values TCL_STATIC, TCL_DYNAMIC, and
178       TCL_VOLATILE, then it is the address of a  procedure  that  Tcl  should
179       call  to free the string.  This allows applications to use non-standard
180       storage allocators.  When Tcl no  longer  needs  the  storage  for  the
181       string,  it  will  call  freeProc.  FreeProc  should have arguments and
182       result that match the type Tcl_FreeProc:
183              typedef void Tcl_FreeProc(char *blockPtr);
184       When freeProc is called, its blockPtr will  be  set  to  the  value  of
185       result passed to Tcl_SetResult.
186

SEE ALSO

188       Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp
189

KEYWORDS

191       append,  command,  element,  list, object, result, return value, inter‐
192       preter
193
194
195
196Tcl                                   8.0                     Tcl_SetResult(3)
Impressum