NAME¶

Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult - manipulate Tcl result

SYNOPSIS¶

#include <tcl.h>

Tcl_SetObjResult(interp, objPtr)

Tcl_Obj *
Tcl_GetObjResult(interp)

Tcl_SetResult(interp, result, freeProc)

const char *
Tcl_GetStringResult(interp)

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

Tcl_ResetResult(interp)

Tcl_TransferResult(sourceInterp, code, targetInterp)

Tcl_AppendElement(interp, element)

ARGUMENTS¶

Tcl_Interp *interp (out)

The interpreter get or set the result for.

Tcl_Obj *objPtr (in)

A value to set the result to.

char *result (in)

The string value set the result to, or to append to the existing result.

const char *element (in)

The string value to append as a list element to the existing result of interp.

Tcl_FreeProc *freeProc (in)

Pointer to a procedure to call to release storage at result.

Tcl_Interp *sourceInterp (in)

The interpreter to transfer the result and return options from.

Tcl_Interp *targetInterp (in)

The interpreter to transfer the result and return options to.

int code (in)

Return code value that controls transfer of return options.

DESCRIPTION¶

These procedures manipulate the result of an interpreter. Some procedures provide a Tcl_Obj interface while others provide a string interface. For example, Tcl_SetObjResult accepts a Tcl_Obj and Tcl_SetResult accepts a char *. Similarly, Tcl_GetObjResult produces a Tcl_Obj * and Tcl_GetStringResult produces a char *. The procedures can be mixed and matched. For example, if Tcl_SetObjResult is called to set the result to a Tcl_Obj value, and then Tcl_GetStringResult is called, it returns a char * (but see caveats below).

Tcl_SetObjResult sets objPtr as the result for interp, replacing any existing result.

Tcl_GetObjResult returns the result for interp, without incrementing its reference count.

Tcl_SetResult sets result as the result for interp, replacing any existing result, and calls freeProc to free result. See THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT below. If result is NULL, ignores freeProc and sets the result for interp to point to the empty string.

Tcl_GetStringResult returns the result for interp as a string, i.e. the bytes of the Tcl_Obj for the result, which can be decoded using Tcl_UtfToExternal. This value is freed when its corresponding Tcl_Obj is freed.Programmers are encouraged to use the newer Tcl_Obj API procedures, e.g. to call Tcl_GetObjResult instead.

Tcl_ResetResult sets the empty string as the result for interp and clears the error state managed by Tcl_AddErrorInfo, Tcl_AddObjErrorInfo, and Tcl_SetErrorCode.

Tcl_AppendResult builds up a result from smaller pieces, appending each result in order to the current result for interp. It may be called repeatedly as additional pieces of the result are produced, and manages the storage for the interp's result, allocating a larger result area if necessary. It also manages conversion to and from the result field of the interp to handle backward-compatibility with old-style extensions. Any number of result arguments may be passed in a single call; the last argument in the list must be a NULL pointer.

Tcl_TransferResult transfers interpreter state from sourceInterp to targetInterp, both of which must have been created in the same thread, resets the result in sourceInterp, and moves the return options dictionary as controlled by the return code value code in the same manner as Tcl_GetReturnOptions.

If sourceInterp and targetInterp are the same, nothing is done.

DEPRECATED INTERFACES¶

THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT¶

FreeProc has the following type:

typedef void Tcl_FreeProc(


        char *blockPtr);

When freeProc is called, blockPtr is the result value passed to Tcl_SetResult.

SEE ALSO¶

Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp, Tcl_GetReturnOptions

KEYWORDS¶

append, command, element, list, value, result, return value, interpreter