## Tcl8.6.17/Tk8.6.17 Documentation > Tcl C API > SetResult

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult — Tcl 結果を操作する　 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_AppendResultVA(interp, argList)
    Tcl_ResetResult(interp)
    Tcl_TransferResult(sourceInterp, code, targetInterp)
    Tcl_AppendElement(interp, element)
    Tcl_FreeResult(interp)
  引数 ARGUMENTS
    Tcl_Interp *interp (out)
    Tcl_Obj *objPtr (入力in)
    char *result (入力in)
    const char *element (入力in)
    Tcl_FreeProc *freeProc (入力in)
    va_list argList (入力in)
    Tcl_Interp *sourceInterp (入力in)
    Tcl_Interp *targetInterp (入力in)
    int code (入力in)
  説明 DESCRIPTION
  不推奨の対話機能 DEPRECATED INTERFACES
  古い 文字列手続き函数 OLD STRING PROCEDURES
  INTERP->RESULTの直接利用 DIRECT ACCESS TO INTERP->RESULT
  THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT
  SEE ALSO
  KEYWORDS

### NAME

Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult — Tcl 結果を操作する　 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_AppendResultVA(interp, argList)
Tcl_ResetResult(interp)
Tcl_TransferResult(sourceInterp, code, targetInterp)
Tcl_AppendElement(interp, element)
Tcl_FreeResult(interp)

### 引数 ARGUMENTS

Tcl_Interp *interp (out)
  その結果が修正されたり読まれたりする解釈実行機能｡　 Interpreter whose result is to be modified or read.

Tcl_Obj *objPtr (入力in)
  解釈実行機能の為の結果になる値｡　 Tcl value to become result for interp.

char *result (入力in)
  解釈実行機能の為の結果になるか､既存の結果に追記されるべき文字列値｡　 String value to become result for interp or to be appended to the existing result.

const char *element (入力in)
  既存の解釈実行機能の結果にリスト要素として追記されるべき文字列値｡　 String value to append as a list element to the existing result of interp.

Tcl_FreeProc *freeProc (入力in)
  結果の貯蔵を解放するために呼出す手続の番地､ 若しくは TCL_STATIC か TCL_DYNAMIC か TCL_VOLATILE ｡ Address of procedure to call to release storage at result, or TCL_STATIC, TCL_DYNAMIC, or TCL_VOLATILE.

va_list argList (入力in)
  引数リストであって､ va_start を使用して初期化したものでなければならず､且つ va_end を使用して解消されねばならない｡　 An argument list which must have been initialized using va_start, and cleared using va_end.

Tcl_Interp *sourceInterp (入力in)
  結果と持ち帰り指示項目がそこから転送されるべき解釈実行機能｡　 Interpreter that the result and return options should be transferred from.

Tcl_Interp *targetInterp (入力in)
  結果と持ち帰り指示項目をそこへ転送されるべき解釈実行機能｡　 Interpreter that the result and return options should be transferred to.

int code (入力in)
  持ち帰り指示項目の転送を制御する返り符号｡ Return code value that controls transfer of return options.

### 説明 DESCRIPTION

ここで記述される手続函数は Tcl 解釈実行機能内の結果の値を操作する便益である｡解釈実行機能の値は Tcl 値か文字列のどちらかである｡譬えば､ Tcl_SetObjResult と Tcl_SetResult は解釈実行機能の結果をそれぞれ値と文字列に設定する｡同様に､ Tcl_GetObjResult と Tcl_GetStringResult は解釈実行機能の結果を値として及び､文字列として返す｡手続函数は解釈実行機能の結果の文字列と値の形式を一貫して保持している｡譬えば､もし Tcl_SetObjResult が結果を値に設定するために呼ばれると､ Tcl_GetStringResult が呼ばれ､それが値の文字列表現を返すことになる｡ The procedures described here are utilities for manipulating the result value in a Tcl interpreter. The interpreter result may be either a Tcl value or a string. For example, Tcl_SetObjResult and Tcl_SetResult set the interpreter result to, respectively, a value and a string. Similarly, Tcl_GetObjResult and Tcl_GetStringResult return the interpreter result as a value and as a string. The procedures always keep the string and value forms of the interpreter result consistent. For example, if Tcl_SetObjResult is called to set the result to a value, then Tcl_GetStringResult is called, it will return the value's string representation.

Tcl_SetObjResult は､既存のどの結果も入替えて､ objPtr が interp の結果になる様､準備する｡ 結果は objPtr によって参照される値の指示子として残される｡今そこで interp から新しい参照ができたので objPtr の参照数は増加される｡ どの古い結果に関する objPtr の参照数も減ぜられ､もしそれへの参照数が残らない場合､古い値は解放される｡ Tcl_SetObjResult arranges for objPtr to be the result for interp, replacing any existing result. The result is left pointing to the value referenced by objPtr. objPtr's reference count is incremented since there is now a new reference to it from interp. The reference count for any old result value is decremented and the old result value is freed if no references to it remain.

Tcl_GetObjResult は解釈実行機能の結果を値として返す｡値の参照回数は増加されない; もし､呼出し側が値への長期間のポインターを残したい場合､偶然的な変更により早すぎる解放にならない様その参照回数を増加する為に Tcl_IncrRefCount を呼ぶべきである｡ Tcl_GetObjResult returns the result for interp as a value. The value's reference count is not incremented; if the caller needs to retain a long-term pointer to the value they should use Tcl_IncrRefCount to increment its reference count in order to keep it from being freed too early or accidentally changed.

Tcl_SetResult は既存のどの結果も入替え result が､解釈実行機能内の現在の Tcl 命令の結果になる様にるよう整える｡ freeProc 引数は result 引数の為に如何に記憶域を管理すべきかを指定する; それは下の THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT の節内で論議する｡もし result が NULL なら freeProc は無視され､ Tcl_SetResult は interp の結果を空文字列を指す様に再初期化する｡ Tcl_SetResult arranges for result to be the result for the current Tcl command in interp, replacing any existing result. The freeProc argument specifies how to manage the storage for the result argument; it is discussed in the section THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT below. If result is NULL, then freeProc is ignored and Tcl_SetResult re-initializes interp's result to point to an empty string.

Tcl_GetStringResult は interp に関する結果を文字列として返す｡もしその結果が Tcl_SetObjResult の呼出しによって値に設定されたら､値の形式は文字列に変換され､返される｡もし値の文字列表現が零バイトを含む場合､この変換は情報を失う｡この理由で､算譜は新しい値 API 手続函数を使ってその命令譜を書き Tcl_GetObjResult を呼ぶことが推奨される｡ Tcl_GetStringResult returns the result for interp as a string. If the result was set to a value by a Tcl_SetObjResult call, the value form will be converted to a string and returned. If the value'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 value API procedures and to call Tcl_GetObjResult instead.

Tcl_ResetResult は interp の為に結果を一掃し結果を通常の初期化された空状態に留める｡もし結果が値の場合､その参照回数は減ぜられ､結果は空文字列を表す非共有の値を指して残される｡もし結果が動的に割付けられた文字列である場合､その記憶域は解放され､結果は空文字列として残される｡Tcl_ResetResult は Tcl_AddErrorInfo と Tcl_AddObjErrorInfo と Tcl_SetErrorCode により管理された不具合状態を一掃する｡ Tcl_ResetResult clears the result for interp and leaves the result in its normal empty initialized state. If the result is a value, its reference count is decremented and the result is left pointing to an unshared value 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. Tcl_ResetResult also clears the error state managed by Tcl_AddErrorInfo, Tcl_AddObjErrorInfo, and Tcl_SetErrorCode.

Tcl_AppendResult は Tcl 結果を切れ切れに作り上げることを容易にする｡それぞれの result 引数を採り解釈実行機能に結合した現在の結果の順序で追記する｡もし結果が初期化された空状態であると(譬えば､命令手続函数が丁度起動されたばかり､又は Tcl_ResetResult が丁度呼ばれたばかり)､ Tcl_AppendResult は結果をその result 引数の連鎖にする｡ Tcl_AppendResult は 解釈実行機能の結果を管理することに関する貯蔵域管理問題の全てを大事にする､譬えば必要なら更に広大な結果領域を割当てる｡それは､解釈実行機能の結果領域からの､或はそれへの､変換を管理して､古い様式の拡張との互換性を処理する｡一度の呼出に幾らの個数の引数も渡すことができる；リストの最後の引数は NULL 指示子でなければならない｡ Tcl_AppendResult makes it easy to build up Tcl results in pieces. It takes each of its result 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 command procedure was just invoked or Tcl_ResetResult was just called), then Tcl_AppendResult sets the result to the concatenation of its result 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. It also manages conversion to and from the result field of the interp so as 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_AppendResultVA は変動個数の引数を取る代りにリスト引数をとることを除いて Tcl_AppendResult と同じである｡ Tcl_AppendResultVA is the same as Tcl_AppendResult except that instead of taking a variable number of arguments it takes an argument list.

Tcl_TransferResult は解釈実行機能の状態を sourceInterp から targetInterp に転送する｡二つの解釈実行機能は同じ時分割片の中で創生されてなければならない｡もし､ sourceInterp と targetInterp が同じである場合､何も起こらない｡そうでない場合､Tcl_TransferResult は結果を sourceInterp から targetInterp へ移し､且つ､sourceInterp 内の結果を解消する｡それは又､ Tcl_GetReturnOptions と同じ方法の返り符号値によって制御された様に､返り指示項目辞書を移す｡ Tcl_TransferResult transfers interpreter state from sourceInterp to targetInterp. The two interpreters must have been created in the same thread. If sourceInterp and targetInterp are the same, nothing is done. Otherwise, Tcl_TransferResult moves the result from sourceInterp to targetInterp, and resets the result in sourceInterp. It also moves the return options dictionary as controlled by the return code value code in the same manner as Tcl_GetReturnOptions.

### 不推奨の対話機能 DEPRECATED INTERFACES

#### 古い 文字列手続き函数 OLD STRING PROCEDURES

次の手続函数の使用は､文字列として Tcl 結果を操作する故に批判されている｡譬えば Tcl_SetObjResult の様に､結果を対象として扱う手続函数は本質的に更に効果的かもしれない｡ Use of the following procedures is deprecated since they manipulate the Tcl result as a string. Procedures such as Tcl_SetObjResult that manipulate the result as a value can be significantly more efficient.

Tcl_AppendElement はTcl_AppendResult と似ている処は､きれぎれに結果を作り上げることを許容することである｡但し､ Tcl_AppendElement は唯一つの element 引数のみを取り､その引数を適切な Tcl リスト要素として現在の結果に追記する｡ Tcl_AppendElement は､ interp の結果がリストとして解析でき､且つ､ element が一つの要素として確実に抽出されることが確実に必要な場合､逆斜線や波括弧を追加する｡通常の条件では､Tcl_AppendElement は新しいリスト要素を追加する直前の解釈実行機能の結果に空白を追加するので､結果内のリスト要素は適切に分離される｡しかし､もし新しいリスト要素がリストや副リスト(即ち､解釈実行機能の現在の結果が空であるか､一つの文字 “{” で構成されるか ､末尾が “ {” である)の初めの場合､空白は加えられない｡ 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 element 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 element will be extracted as a single element. 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_FreeResult は Tcl_ResetResult.の働きの一部を遂行する｡それは解釈実行機能と結合した記憶域を解除する｡それは interp->freeProc を零に設定するが､ interp->result を変更したり不都合状態を一掃したりしない｡ Tcl_FreeResult は手続函数が一つの結果の値を他で置換えようとする時に一番普通に使われる｡ Tcl_FreeResult performs part of the work of Tcl_ResetResult. It frees up the memory associated with interp's result. It also sets interp->freeProc to zero, but does not 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.

#### INTERP->RESULTの直接利用 DIRECT ACCESS TO INTERP->RESULT

算譜が解釈実行機能の結果を操作するために interp->result を直接読み出し及び書込みすることは合法的であった｡ Tcl 冒頭部は無為設定では､もはやこの利用法は許容していない､又 C 命令符号は､継続して之を行うには､使う為に運営している機能の Tcl_GetObjResult, Tcl_GetStringResult, Tcl_SetObjResult, and Tcl_SetResult.を更新しなければならない｡移転の補助のために､利用は機械語翻訳の指示により復元できる｡ It used to be legal for programs to directly read and write interp->result to manipulate the interpreter result. The Tcl headers no longer permit this access by default, and C code still doing this must be updated to use supported routines Tcl_GetObjResult, Tcl_GetStringResult, Tcl_SetObjResult, and Tcl_SetResult. As a migration aid, access can be restored with the compiler directive

    #define USE_INTERP_RESULT

しかし､之は延命の提供であり､そうしなければ不要な命令符号になる｡ but this is meant only to offer life support to otherwise dead code.

### THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT

Tcl_SetResult の freeProc 引数は､ Tcl 体系が result 引数用の記憶域を如何に管理するかを指定する｡もし interp が文字列結果を保有している時に Tcl_SetResult か Tcl_SetObjResult が呼ばれた場合､それらは、何であれ､古い文字列結果を処分するのに必要なことすべてを行う(之に関する詳細は取扱説明書の Tcl_Interp の項を参照されたい)｡ Tcl_SetResult's freeProc argument specifies how the Tcl system is to manage the storage for the result argument. If Tcl_SetResult or Tcl_SetObjResult are called at a time when interp holds a string result, they do whatever is necessary to dispose of the old string result (see the Tcl_Interp manual entry for details on this).

もし freeProc が TCL_STATIC の場合､結果が少なくとも Tcl_Eval への次の呼び出しまで修正されないことを保証される静的記憶域の領域を指すことを意味する｡もし freeProc が TCL_DYNAMIC の場合､結果は Tcl_Alloc の呼出しによりに割付けられ､今 Tcl 体系の資産であることを意味する｡ Tcl_SetResult は文字列の記憶装置がもはや必要でない場合に､ Tcl_Free を呼出すことにより解放されるよう準備する｡ freeProc が TCL_VOLATILE の場合､ Tcl_SetResult が戻る時､ result は Tcl_SetResult が帰る時に上書きされる可能性がある記憶域を指す(譬えば､棚枠内の何かを指す)ことを意味する｡この場合､ Tcl_SetResult は動的に割付られた記憶域の中に文字列の複写を作り､その複写が現在の Tcl 命令の結果であるように手配する｡ If freeProc is TCL_STATIC it means that result 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 result 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 result 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 result for the current Tcl command.

freeProc が TCL_STATIC と TCL_DYNAMIC と TCL_VOLATILE の内の一つではない場合､それは Tcl が文字列を解放する為に呼ぶべき手続函数の番地である｡これは､応用譜が非標準の記憶割付機能を使用することを可能にする｡ Tcl がもはや文字列用の記憶域を必要としない場合､ freeProc.を呼ぶことになる｡ freeProc は､ Tcl_FreeProc 型と合致する引数と結果を有するべきである: If freeProc is not 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 applications 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);

freeProc が呼ばれる時､その blockPtr は Tcl_SetResult.に渡された result の値を設定することになる｡ When freeProc is called, its blockPtr will be set to the value of result 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
Copyright © 1989-1993 The Regents of the University of California.
Copyright © 1994-1997 Sun Microsystems, Inc.