通讯编程

开发平台：
Visual C++

ListObj.3：源码内容
							'"
'" 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.
'" 
'" RCS: @(#) $Id: ListObj.3,v 1.4 2000/01/26 03:37:30 hobbs Exp $
'" 
.so man.macros
.TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace - manipulate Tcl objects as lists
.SH SYNOPSIS
.nf
fB#include <tcl.h>fR
.sp
int
fBTcl_ListObjAppendListfR(fIinterp, listPtr, elemListPtrfR)
.sp
int
fBTcl_ListObjAppendElementfR(fIinterp, listPtr, objPtrfR)
.sp
Tcl_Obj *
fBTcl_NewListObjfR(fIobjc, objvfR)
.sp
fBTcl_SetListObjfR(fIobjPtr, objc, objvfR)
.sp
int
fBTcl_ListObjGetElementsfR(fIinterp, listPtr, objcPtr, objvPtrfR)
.sp
int
fBTcl_ListObjLengthfR(fIinterp, listPtr, intPtrfR)
.sp
int
fBTcl_ListObjIndexfR(fIinterp, listPtr, index, objPtrPtrfR)
.sp
int
fBTcl_ListObjReplacefR(fIinterp, listPtr, first, count, objc, objvfR)
.SH ARGUMENTS
.AS Tcl_Interp "*CONST objv[]" out
.AP Tcl_Interp *interp in
If an error occurs while converting an object to be a list object,
an error message is left in the interpreter's result object
unless fIinterpfR is NULL.
.AP Tcl_Obj *listPtr in/out
Points to the list object to be manipulated.
If fIlistPtrfR does not already point to a list object,
an attempt will be made to convert it to one.
.AP Tcl_Obj *elemListPtr in/out
For fBTcl_ListObjAppendListfR, this points to a list object
containing elements to be appended onto fIlistPtrfR.
Each element of *fIelemListPtrfR will
become a new element of fIlistPtrfR.
If *fIelemListPtrfR is not NULL and
does not already point to a list object,
an attempt will be made to convert it to one.
.AP Tcl_Obj *objPtr in
For fBTcl_ListObjAppendElementfR,
points to the Tcl object that will be appended to fIlistPtrfR.
For fBTcl_SetListObjfR,
this points to the Tcl object that will be converted to a list object
containing the fIobjcfR elements of the array referenced by fIobjvfR.
.AP int *objcPtr in
Points to location where fBTcl_ListObjGetElementsfR
stores the number of element objects in fIlistPtrfR.
.AP Tcl_Obj ***objvPtr out
A location where fBTcl_ListObjGetElementsfR stores a pointer to an array
of pointers to the element objects of fIlistPtrfR.  
.AP int objc in
The number of Tcl objects that fBTcl_NewListObjfR
will insert into a new list object,
and fBTcl_ListObjReplacefR will insert into fIlistPtrfR.
For fBTcl_SetListObjfR,
the number of Tcl objects to insert into fIobjPtrfR.
.VS
.AP Tcl_Obj	"*CONST objv[]" in
An array of pointers to objects.
fBTcl_NewListObjfR will insert these objects into a new list object
and fBTcl_ListObjReplacefR will insert them into an existing fIlistPtrfR.
Each object will become a separate list element.  
.VE
.AP int *intPtr out
Points to location where fBTcl_ListObjLengthfR
stores the length of the list.
.AP int index in
Index of the list element that fBTcl_ListObjIndexfR
is to return.
The first element has index 0.
.AP Tcl_Obj **objPtrPtr out
Points to place where fBTcl_ListObjIndexfR is to store
a pointer to the resulting list element object.
.AP int first in
Index of the starting list element that fBTcl_ListObjReplacefR
is to replace.
The list's first element has index 0.
.AP int count in
The number of elements that fBTcl_ListObjReplacefR
is to replace.
.BE
.SH DESCRIPTION
.PP
Tcl list objects have an internal representation that supports
the efficient indexing and appending.
The procedures described in this man page are used to
create, modify, index, and append to Tcl list objects from C code.
.PP
fBTcl_ListObjAppendListfR and fBTcl_ListObjAppendElementfR
both add one or more objects
to the end of the list object referenced by fIlistPtrfR.
fBTcl_ListObjAppendListfR appends each element of the list object
referenced by fIelemListPtrfR while
fBTcl_ListObjAppendElementfR appends the single object
referenced by fIobjPtrfR.
Both procedures will convert the object referenced by fIlistPtrfR
to a list object if necessary.
If an error occurs during conversion,
both procedures return fBTCL_ERRORfR and leave an error message
in the interpreter's result object if fIinterpfR is not NULL.
Similarly, if fIelemListPtrfR does not already refer to a list object,
fBTcl_ListObjAppendListfR will attempt to convert it to one
and if an error occurs during conversion,
will return fBTCL_ERRORfR
and leave an error message in the interpreter's result object
if interp is not NULL.
Both procedures invalidate any old string representation of fIlistPtrfR
and, if it was converted to a list object,
free any old internal representation.
Similarly, fBTcl_ListObjAppendListfR frees any old internal representation
of fIelemListPtrfR if it converts it to a list object.
After appending each element in fIelemListPtrfR,
fBTcl_ListObjAppendListfR increments the element's reference count
since fIlistPtrfR now also refers to it.
For the same reason, fBTcl_ListObjAppendElementfR
increments fIobjPtrfR's reference count.
If no error occurs,
the two procedures return fBTCL_OKfR after appending the objects.
.PP
fBTcl_NewListObjfR and fBTcl_SetListObjfR
create a new object or modify an existing object to hold 
the fIobjcfR elements of the array referenced by fIobjvfR
where each element is a pointer to a Tcl object.
If fIobjcfR is less than or equal to zero,
they return an empty object.
The new object's string representation is left invalid.
The two procedures increment the reference counts
of the elements in fIobjcfR since the list object now refers to them.
The new list object returned by fBTcl_NewListObjfR
has reference count zero.
.PP
fBTcl_ListObjGetElementsfR returns a count and a pointer to an array of
the elements in a list object.  It returns the count by storing it in the
address fIobjcPtrfR.  Similarly, it returns the array pointer by storing
it in the address fIobjvPtrfR.
The memory pointed to is managed by Tcl and should not be freed by the
caller.
If fIlistPtrfR is not already a list object, fBTcl_ListObjGetElementsfR
will attempt to convert it to one; if the conversion fails, it returns
fBTCL_ERRORfR and leaves an error message in the interpreter's result
object if fIinterpfR is not NULL.
Otherwise it returns fBTCL_OKfR after storing the count and array pointer.
.PP
fBTcl_ListObjLengthfR returns the number of elements in the list object
referenced by fIlistPtrfR.
It returns this count by storing an integer in the address fIintPtrfR.
If the object is not already a list object,
fBTcl_ListObjLengthfR will attempt to convert it to one;
if the conversion fails, it returns fBTCL_ERRORfR
and leaves an error message in the interpreter's result object
if fIinterpfR is not NULL.
Otherwise it returns fBTCL_OKfR after storing the list's length.
.PP
The procedure fBTcl_ListObjIndexfR returns a pointer to the object
at element fIindexfR in the list referenced by fIlistPtrfR.
It returns this object by storing a pointer to it
in the address fIobjPtrPtrfR.
If fIlistPtrfR does not already refer to a list object,
fBTcl_ListObjIndexfR will attempt to convert it to one;
if the conversion fails, it returns fBTCL_ERRORfR
and leaves an error message in the interpreter's result object
if fIinterpfR is not NULL.
If the index is out of range,
that is, fIindexfR is negative or
greater than or equal to the number of elements in the list,
fBTcl_ListObjIndexfR stores a NULL in fIobjPtrPtrfR
and returns fBTCL_OKfR.
Otherwise it returns fBTCL_OKfR after storing the element's
object pointer.
The reference count for the list element is not incremented;
the caller must do that if it needs to retain a pointer to the element.
.PP
fBTcl_ListObjReplacefR replaces zero or more elements
of the list referenced by fIlistPtrfR
with the fIobjcfR objects in the array referenced by fIobjvfR.
If fIlistPtrfR does not point to a list object,
fBTcl_ListObjReplacefR will attempt to convert it to one;
if the conversion fails, it returns fBTCL_ERRORfR
and leaves an error message in the interpreter's result object
if fIinterpfR is not NULL.
Otherwise, it returns fBTCL_OKfR after replacing the objects.
If fIobjvfR is NULL, no new elements are added.
If the argument fIfirstfR is zero or negative,
it refers to the first element.
If fIfirstfR is greater than or equal to the
number of elements in the list, then no elements are deleted;
the new elements are appended to the list.
fIcountfR gives the number of elements to replace.
If fIcountfR is zero or negative then no elements are deleted;
the new elements are simply inserted before the one
designated by fIfirstfR.
fBTcl_ListObjReplacefR invalidates fIlistPtrfR's
old string representation.
The reference counts of any elements inserted from fIobjvfR
are incremented since the resulting list now refers to them.
Similarly, the reference counts for any replaced objects are decremented.
.PP
Because fBTcl_ListObjReplacefR combines
both element insertion and deletion,
it can be used to implement a number of list operations.
For example, the following code inserts the fIobjcfR objects
referenced by the array of object pointers fIobjvfR
just before the element fIindexfR of the list referenced by fIlistPtrfR:
.CS
result = Tcl_ListObjReplace(interp, listPtr, index, 0, objc, objv);
.CE
Similarly, the following code appends the fIobjcfR objects
referenced by the array fIobjvfR
to the end of the list fIlistPtrfR:
.CS
result = Tcl_ListObjLength(interp, listPtr, &length);
if (result == TCL_OK) {
	result = Tcl_ListObjReplace(interp, listPtr, length, 0, objc, objv);
}
.CE
The fIcountfR list elements starting at fIfirstfR can be deleted
by simply calling fBTcl_ListObjReplacefR
with a NULL fIobjvPtrfR:
.CS
result = Tcl_ListObjReplace(interp, listPtr, first, count, 0, NULL);
.CE
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
.SH KEYWORDS
append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation

						