'\"
'\" Copyright (c) 1996-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.
'\" 
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH Tcl_Obj 3tcl 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- 操縱 Tcl 對象
.SH 總覽 SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewObj\fR()
.sp
Tcl_Obj *
\fBTcl_DuplicateObj\fR(\fIobjPtr\fR)
.sp
\fBTcl_IncrRefCount\fR(\fIobjPtr\fR)
.sp
\fBTcl_DecrRefCount\fR(\fIobjPtr\fR)
.sp
int
\fBTcl_IsShared\fR(\fIobjPtr\fR)
.sp
\fBTcl_InvalidateStringRep\fR(\fIobjPtr\fR)
.SH 參數 ARGUMENTS
.AS Tcl_Obj *objPtr in
.AP Tcl_Obj *objPtr in
指向一個對象；必須是以前調用 \fBTcl_NewObj\fR 返回的結果。
.BE

.SH 介紹 INTRODUCTION
.PP
這個手冊頁提供了對 Tcl 對象以及如何使用它們的一個概述。它還描述了管理 Tcl 對象的一些一般過程。使用這些過程來建立和複製對象，和增加和減少到對象的引用(指針)計數。這些過程與那些在特定類型的對象如 \fBTcl_GetIntFromObj\fR 和 \fBTcl_ListObjAppendElement\fR 上進行操作的過程聯合使用。單獨的過程和它們所操縱的數據結構被放在一起描述。
.PP
Tcl 的雙端口(\fIdual-ported\fR)對象爲存儲和交換 Tcl 值提供了一個通用的機制。它們在很大程度上替代了 Tcl 中字符串的使用。例如，它們被用來存儲變量值、命令參數、命令結果、和腳本。Tcl 對象外在表現很象字符串，但它還持有可以被更加有效的操縱的內部表示。例如，現在一個 Tcl 列表被表示爲持有列表的字符串表示的一個對象，如同到每個列表元素的指針的一個數組。雙端口對象避免了運行時的類型轉換。它們還提高了許多操作的速度，原因是可以立即獲得一個適當的表示。編譯器自身使用 Tcl 對象來緩存(cache)作爲編譯腳本的結果的字節碼指令。
.PP
這兩種表示互爲緩存並且被以懶惰方式計算。就是說，每個表示都只在需要時才被計算，它被從另一種表示計算出來，而一旦被計算出來了，它就被保存起來。除此之外，其中一個表示的改變將使另一個表示成爲無效 。舉個例子，一個做整數運算的 Tcl 程序可以在一個變量的內部機器整數表示上進行直接操作，而不需要經常性的在整數和字符串之間進行轉換。只有在需要這個變量的值的一個字符串表示的時候，比如打印它，程序才重新生成這個整數的字符串表示。儘管對象包含一個內部表示，但它們的語義仍是依據字符串定義的: 總是可以獲取最新的字符串，在取回對象的字符串表示的時候，對對象的任何改變都將反映到取回的那個字符串上。因爲這個表示是無效的並被重新生成了，擴展作者直接訪問 \fBTcl_Obj\fR 的字段是很危險的。最好使用 \fBTcl_GetStringFromObj\fR 和 \fBTcl_GetString\fR 這樣的過程來訪問 \fBTcl_Obj\fR 信息。
.PP
在堆上分配對象，使用到它們的 \fBTcl_Obj\fR 結構的指針引用對象。對象要儘可能的共享。這將顯著的縮減存儲需求，原因是一些對象比如長列表是非常大的。還有，多數 Tcl 值只是被讀而從不被修改。尤其是過程參數，它們可以在調用和被調用的過程之間共享。賦值和參數綁定是通過簡單的賦予到這個值的一個指針完成的。使用引用計數來確定什麼時候歸還一個對象的存儲是安全的。
.PP
Tcl 對象是有類型的(typed)。一個對象的內部表示由它自己的類型來控制。在 Tcl 核心中預定義了七種類型，其中包括：整數、雙精度浮點數、列表、和字節碼。擴展作者可是使用 \fBTcl_RegisterObjType\fR  過程來擴展類型的集合。

.SH "對象結構 THE TCL_OBJ STRUCTURE"
.PP
每個 Tcl 對象都被表示爲一個 \fBTcl_Obj\fR 結構，其定義如下。
.CS
typedef struct Tcl_Obj {
	int \fIrefCount\fR;
	char *\fIbytes\fR;
	int \fIlength\fR;
	Tcl_ObjType *\fItypePtr\fR;
	union {
		long \fIlongValue\fR;
		double \fIdoubleValue\fR;
		VOID *\fIotherValuePtr\fR;
		struct {
			VOID *\fIptr1\fR;
			VOID *\fIptr2\fR;
		} \fItwoPtrValue\fR;
	} \fIinternalRep\fR;
} Tcl_Obj;
.CE
\fIbytes\fR 和 \fIlength\fR 成員一起持有一個對象的字符串表示，這是一個已計數的 (\fIcounted\fR) 字符串或二進制串 (\fIbinary string\fR)，二進制串可能包含有嵌入的 null 字節的二進制串。\fIbytes\fR 指向這個字符串表示的第一個字節。\fIlength\fR 成員給出字節數。字節數組的在偏移量 \fIlength\fR 上，也就是最後一個字節後面必須總是有一個 null；這允許不包含 null 的字符串表示被作爲一個常規的用 null 終結的 C 語言字符串來對待。 C 程序使用 \fBTcl_GetStringFromObj\fR 和 \fBTcl_GetString\fR 來得到一個對象的字符串表示。如果 \fIbytes\fR 是 NULL，則字符串表示無效。
.PP
一個對象的類型管理它的內部表示。成員 \fItypePtr\fR 指向描述類型的 Tcl_ObjType 結構。如果 \fItypePtr\fR is 是 NULL，則內部表示無效。
.PP
\fIinternalRep\fR 聯合成員持有一個對象的內部表示。它可以是一個(長)整數，一個雙精度浮點數，或者一個指針、它指向包含這個類型的對象要表示對象所需要的補充信息的值，或者是兩個任意的指針。
.PP
使用 \fIrefCount\fR 成員來通告在什麼時候釋放一個對象的存儲是安全的。它持有到這個對象的活躍引用的計數。維護正確的引用計數是擴展作者的一個關鍵性的責任。在下面的對象的存儲管理 (\fBSTORAGE MANAGEMENT OF OBJECTS\fR) 章節中討論了引用計數。
.PP
儘管擴展的作者可以直接訪問一個 Tcl_Obj 結構的成員，但最好還是使用恰當的過程和宏。例如，擴展作者永遠不要直接讀或修改 \fIrefCount\fR；作爲替代，他們應當使用象 \fBTcl_IncrRefCount\fR  和 \fBTcl_IsShared\fR 這樣的宏。
.PP
Tcl 對象的一個關鍵屬性是它持有兩個表示。典型的，一個對象開始時只包含一個字符串表示: 它是無類型的並且\fItypePtr\fR 是一個 NULL。分別使用 \fBTcl_NewObj\fR 或 \fBTcl_NewStringObj\fR 建立包含一個空串的一個對象或一個指定字符串的一個復件。一個對象的字符串值可以使用 \fBTcl_GetStringFromObj\fR 或 \fBTcl_GetString\fR 來獲取並使用 \fBTcl_SetStringObj\fR 來改變它。如果如果這個對象以後被傳遞給象 \fBTcl_GetIntFromObj\fR 這樣的要求一個特定的內部表示的過程，則這個過程將建立一個內部表示並設置這個對象的 \fItypePtr\fR。從字符串表示來計算它的內部表示。一個對象的兩個表示是雙重的: 對一個的改變也將反映到另一個上。例如，\fBTcl_ListObjReplace\fR 將修改一個對象的內部表示，下一個到 \fBTcl_GetStringFromObj\fR 或 \fBTcl_GetString\fR 的調用將反映這個改變。
.PP
出於效率的原因以懶惰方式重計算表示。一個過程如 \fBTcl_ListObjReplace\fR 對一個表示的改變不立即反映到另一個表示上。作爲替代，把另一個表示標記爲無效，如果以後需要的話再重新生成。多數 C 程序員永遠無須關心這是如何完成的，他們只是簡單的使用象 \fBTcl_GetBooleanFromObj\fR 或 \fBTcl_ListObjIndex\fR 這樣的過程。而實現自己的對象類型的程序員必須檢查無效表示和在需要時標記一個表示爲無效。使用過程 \fBTcl_InvalidateStringRep\fR 來標記一個對象的字符串表示爲無效並釋放與這個字符串表示相關聯的存儲。
.PP
對象在它的一生當中通常保持一種類型，但是有時一個對象必須從一種類型轉換成另一種類型。例如，一個 C 程序可以通過重複調用 \fBTcl_AppendToObj\fR 來在一個對象中建造一個字符串，並接着調用 \fBTcl_ListObjIndex\fR 來從一個對象中提取一個列表元素。持有相同字符串的同樣的對象在不同的時候可能有多種不同的內部表示。擴展作者可以使用 \fBTcl_ConvertToType\fR 過程強制把一個對象從一種類型轉換成另一種類型。只有建立新對象類型的程序員才需要關心這是如何作的。作爲對象類型實現的一部分，需要定義爲一個對象建立一個新的內部表示和改變它 \fItypePtr\fR 的一個過程。如何建立一個新對象類型請參見 \fBTcl_RegisterObjType\fR 手冊頁。

.SH "對象生命週期示例 EXAMPLE OF THE LIFETIME OF AN OBJECT"
.PP
作爲一個對象生命週期的一個例子，考慮下列命令序列:
.CS
\fBset x 123\fR
.CE
這裏把一個未知類型的對象賦值給 \fIx\fR，這個對象的 \fIbytes\fR 成員指向 \fB123\fR 而 \fIlength\fR 成員包含 3。對象的 \fItypePtr\fR 成員是 NULL。
.CS
\fBputs "x is $x"\fR
.CE
\fIx\fR 的字符表示是有效的(因爲 \fIbytes\fR 是非 NULL)並被這個命令取回。
.CS
\fBincr x\fR
.CE
\fBincr\fR 命令首先通過調用 \fBTcl_GetIntFromObj\fR 從 x (所引用的)的對象的得到一個整數。這個過程檢查這個對象是否已經是一個整數對象。由於它不是，就通過把這個對象的 \fIinternalRep.longValue\fR 成員設置爲整數 \fB123\fR，並把這個對象的 \fItypePtr\fR 設置爲指向整數的 Tcl_ObjType 結構，此過程把這個對象轉換成了整數對象。兩個表示現在都是有效的。\fBincr\fR 增加這個對象的整數內部表示，接着使它的字符串表示無效(通過調用 \fBTcl_InvalidateStringRep\fR)，原因是這個字符串表示不再與內部表示相對應了。
.CS
\fBputs "x is now $x"\fR
.CE
現在需要 \fIx\fR (所引用的)的對象的字符串表示，要重新計算它。字符串表示現在是 \fB124\fR。兩個表示又都是有效的了。

.SH "對象的存儲管理 STORAGE MANAGEMENT OF OBJECTS"
.PP
Tcl 對象在堆上分配，並且要儘可能的共享對象來縮減存儲需求。使用引用計數來確定何時一個對象不再被需要並可以被安全的釋放。剛用  \fBTcl_NewObj\fR 或 \fBTcl_NewStringObj\fR 建立的對象的  \fIrefCount\fR 是 0。當建立到這個對象的一個新引用時，使用宏 \fBTcl_IncrRefCount\fR 增加引用計數。當不再需要一個引用的時候 ，使用 \fBTcl_DecrRefCount\fR 減少引用計數，而且如果這個對象的引用計數下降到零，就釋放它的存儲。被不同的代碼或數據結構共享的一個對象的 \fIrefCount\fR 大於 1。增加一個對象的引用計數來確保它不會被過早釋放或者它的值被意外的改變。
.PP
舉個例子，字節碼解釋器在調用者和被調用的過程之間共享參數對象，以避免複製對象。它把調用者的實際參數的對象賦值給過程的形式參數變量。此時，它調用 \fBTcl_IncrRefCount\fR 來增加每個實際參數(所引用的)的對象的引用計數，原因是有了從形式參數到這個對象的一個新引用。在被調用的過程返回的時候，解釋器調用 \fBTcl_DecrRefCount\fR 來減少每個參數的引用計數。當一個對象的引用下降到小於等於零的時候， \fBTcl_DecrRefCount\fR 歸還它的存儲。多數命令過程不是必須關心引用計數的，原因是它們立即使用一個對象的值並且在它們返回之後不保留到這個對象的指針。但是，如果它們把到一個對象的指針保留到一個數據結構中，則他們必須注意要增加它的引用計數，原因是這個保留的指針是一個新引用。
.PP
象 \fBlappend\fR 和 \fBlinsert\fR 這樣的直接修改對象的命令過程必須注意要在修改一個共享的對象之前複製它。 他們必須首先調用 \fBTcl_IsShared\fR 來檢查這個對象是否是共享的。如果對象是共享的，則他們必須使用  \fBTcl_DuplicateObj\fR 複製這個對象；它返回原始對象的一個新複製品，其 \fIrefCount\fR 是 0。如果對象未被共享，則命令過程“擁有”這個對象並可以安全的直接修改它。例如，下列代碼出現在實現 \fBlinsert\fR 的命令過程當中。通過在  \fIindex\fR 的前面插入 \fIobjc-3\fR 新元素，這個過程修改在 \fIobjv[1]\fR 中傳遞給它的列表對象 。

.CS
listPtr = objv[1];
if (Tcl_IsShared(listPtr)) {
	listPtr = Tcl_DuplicateObj(listPtr);
}
result = Tcl_ListObjReplace(interp, listPtr, index, 0, (objc-3), &(objv[3]));
.CE

另一個例子，\fBincr\fR 的命令過程在增加變量(所引用的)對象內部表示中的整數之前，必須檢查這個變量(所引用的)對象是否是共享的。如果它是共享的，則需要複製這個對象，目的是避免意外的改變在其他數據結構中值。


.SH "參見 SEE ALSO"
Tcl_ConvertToType, Tcl_GetIntFromObj, Tcl_ListObjAppendElement, Tcl_ListObjIndex, Tcl_ListObjReplace, Tcl_RegisterObjType

.SH 關鍵字 KEYWORDS
internal representation, object, object creation, object type, reference counting, string representation, type conversion

.SH "[中文版維護人]"
.B 寒蟬退士
.SH "[中文版最新更新]"
.B 2001/10/30
.SH "《中國 Linux 論壇 man 手冊頁翻譯計劃》:"
.BI http://cmpp.linuxforum.net
.SH "跋"
.br
本頁面中文版由中文 man 手冊頁計劃提供。
.br
中文 man 手冊頁計劃：\fBhttps://github.com/man-pages-zh/manpages-zh\fR