tcl7.6 C API - SetResult






NAME

     Tcl_SetResult,     Tcl_AppendResult,      Tcl_AppendElement,
     Tcl_ResetResult - manipulate Tcl result string


SYNOPSIS

     #include <tcl.h>

     Tcl_SetResult(interp, string, freeProc)

     Tcl_AppendResult(interp, string, string, ... , (char *) NULL)

     Tcl_AppendElement(interp, string)

     Tcl_ResetResult(interp)

     Tcl_FreeResult(interp)


ARGUMENTS

     Tcl_Interp     *interp    (out)     Interpreter whose result
                                         is to be modified.

     char           *string    (in)      String value  to  become
                                         result  for interp or to
                                         be appended to  existing
                                         result.

     Tcl_FreeProc   *freeProc  (in)      Address of procedure  to
                                         call  to release storage
                                         at      string,       or
                                         TCL_STATIC, TCL_DYNAMIC,
                                         or TCL_VOLATILE.





DESCRIPTION

     The procedures described here are utilities for setting  the
     result/error string in a Tcl interpreter.

     Tcl_SetResult arranges for string to be  the  return  string
     for  the current Tcl command in interp, replacing any exist-
     ing result.  If freeProc is TCL_STATIC it means that  string
     refers  to  an area of static storage that is guaranteed not
     to be modified until at least the next call to Tcl_Eval.  If  |
     freeProc  is  TCL_DYNAMIC it means that string was allocated  |
     with a call to Tcl_Alloc and is now the property of the  Tcl  |
     system.  Tcl_SetResult will arrange for the string's storage  |
     to be released by calling Tcl_Free  when  it  is  no  longer  |
     needed.   If  freeProc  is TCL_VOLATILE it means that string
     points to an area of memory that is likely to be overwritten
     when Tcl_SetResult returns (e.g. it points to something in a
     stack frame).  In this case Tcl_SetResult 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.

     If freeProc isn't one of the values TCL_STATIC, TCL_DYNAMIC,
     and TCL_VOLATILE, then it is the address of a procedure that
     Tcl should call to free the string.   This  allows  applica-
     tions  to  use non-standard storage allocators.  When Tcl no
     longer needs the  storage  for  the  string,  it  will  call
     freeProc.   FreeProc  should  have arguments and result that
     match the type Tcl_FreeProc:
          typedef void Tcl_FreeProc(char *blockPtr);
     When freeProc is called, its blockPtr will  be  set  to  the
     value of string passed to Tcl_SetResult.

     If  string  is  NULL,   then   freeProc   is   ignored   and
     Tcl_SetResult re-initializes interp's result to point to the
     pre-allocated result area,  with  an  empty  string  in  the
     result area.

     If Tcl_SetResult is called at a time  when  interp  holds  a
     result,  Tcl_SetResult does whatever is necessary to dispose
     of the old result  (see  the  Tcl_Interp  manual  entry  for
     details on this).

     Tcl_AppendResult makes it easy to build up  Tcl  results  in
     pieces.   It  takes each of its string arguments and appends
     them in order to the current result associated with  interp.
     If the result is in its initialized empty state (e.g. a com-
     mand procedure was just invoked or Tcl_ResetResult was  just
     called),  then  Tcl_AppendResult sets the result to the con-
     catenation of its string arguments.  Tcl_AppendResult may be
     called  repeatedly  as  additional  pieces of the result are
     produced.  Tcl_AppendResult takes care of  all  the  storage
     management  issues associated with managing interp's result,
     such as allocating a larger result area if  necessary.   Any
     number  of  string arguments may be passed in a single call;
     the last argument in the list must be a NULL pointer.

     Tcl_AppendElement is similar to Tcl_AppendResult in that  it
     allows   results   to  be  built  up  in  pieces.   However,
     Tcl_AppendElement takes only a single string argument and it
     appends  that argument to the current result as a proper Tcl
     list element.  Tcl_AppendElement adds backslashes or  braces
     if necessary to ensure that interp's result can be parsed as
     a list and that string will be extracted as  a  single  ele-
     ment.  Under normal conditions, Tcl_AppendElement will add a
     space character to interp'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. interp's current
     result is empty, or consists of the single character  ``{'',
     or ends in the characters `` {'') then no space is added.

     Tcl_ResetResult clears the result for  interp,  freeing  the
     memory  associated with it if the current result was dynami-
     cally allocated.  It leaves the result in  its  normal  ini-
     tialized  state  with  interp->result  pointing  to a static
     buffer containing TCL_RESULT_SIZE characters, of  which  the
     first  character  is  zero.  Tcl_ResetResult also clears the
     error    state    managed    by     Tcl_AddErrorInfo     and
     Tcl_SetErrorCode.

     Tcl_FreeResult is a macro that performs part of the work  of
     Tcl_ResetResult.   It  frees  up  the memory associated with
     interp's result and sets interp->freeProc to  zero,  but  it
     doesn't   change   interp->result   or  clear  error  state.
     Tcl_FreeResult is most commonly used  when  a  procedure  is
     about to replace one result value with another.



SEE ALSO

     Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp



KEYWORDS

     append, command, element, list, result, return value, inter-
     preter