Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Tcl_ListObj(3)		    Tcl	Library	Procedures		Tcl_ListObj(3)

______________________________________________________________________________

NAME
       Tcl_ListObjAppendList,	  Tcl_ListObjAppendElement,    Tcl_NewListObj,
       Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength,  Tcl_ListOb-
       jIndex, Tcl_ListObjReplace - manipulate Tcl objects as lists

SYNOPSIS
       #include	<tcl.h>

       int
       Tcl_ListObjAppendList(interp, listPtr, elemListPtr)

       int
       Tcl_ListObjAppendElement(interp,	listPtr, objPtr)

       Tcl_Obj *
       Tcl_NewListObj(objc, objv)

       Tcl_SetListObj(objPtr, objc, objv)

       int
       Tcl_ListObjGetElements(interp, listPtr, objcPtr,	objvPtr)

       int
       Tcl_ListObjLength(interp, listPtr, intPtr)

       int
       Tcl_ListObjIndex(interp,	listPtr, index,	objPtrPtr)

       int
       Tcl_ListObjReplace(interp, listPtr, first, count, objc, objv)

ARGUMENTS
       Tcl_Interp *interp (in)			 If an error occurs while con-
						 verting an  object  to	 be  a
						 list object, an error message
						 is left in the	 interpreter's
						 result	 object	 unless	interp
						 is NULL.

       Tcl_Obj *listPtr	(in/out)		 Points	to the list object  to
						 be  manipulated.   If listPtr
						 does not already point	 to  a
						 list  object, an attempt will
						 be made to convert it to one.

       Tcl_Obj *elemListPtr (in/out)		 For	Tcl_ListObjAppendList,
						 this  points to a list	object
						 containing elements to	be ap-
						 pended	 onto  listPtr.	  Each
						 element of *elemListPtr  will
						 become	  a   new  element  of
						 listPtr.  If *elemListPtr  is
						 not NULL and does not already
						 point to a  list  object,  an
						 attempt  will be made to con-
						 vert it to one.

       Tcl_Obj *objPtr (in)			 For Tcl_ListObjAppendElement,
						 points	to the Tcl object that
						 will be appended to  listPtr.
						 For	Tcl_SetListObj,	  this
						 points	to the Tcl object that
						 will  be  converted to	a list
						 object	 containing  the  objc
						 elements  of the array	refer-
						 enced by objv.

       int *objcPtr (in)			 Points	 to   location	 where
						 Tcl_ListObjGetElements	stores
						 the number of element objects
						 in listPtr.

       Tcl_Obj ***objvPtr (out)			 A  location where Tcl_ListOb-
						 jGetElements stores a pointer
						 to  an	 array	of pointers to
						 the   element	 objects    of
						 listPtr.

       int objc	(in)				 The  number  of  Tcl  objects
						 that Tcl_NewListObj will  in-
						 sert  into a new list object,
						 and  Tcl_ListObjReplace  will
						 insert	  into	listPtr.   For
						 Tcl_SetListObj, the number of
						 Tcl  objects  to  insert into
						 objPtr.

       Tcl_Obj *const objv[] (in)		 An array of pointers  to  ob-
						 jects.	  Tcl_NewListObj  will
						 insert	these objects  into  a
						 new  list object and Tcl_Lis-
						 tObjReplace will insert  them
						 into	an  existing  listPtr.
						 Each  object  will  become  a
						 separate list element.

       int *intPtr (out)			 Points	  to   location	 where
						 Tcl_ListObjLength stores  the
						 length	of the list.

       int index (in)				 Index	of  the	 list  element
						 that Tcl_ListObjIndex	is  to
						 return.   The	first  element
						 has index 0.

       Tcl_Obj **objPtrPtr (out)		 Points	  to	place	 where
						 Tcl_ListObjIndex  is to store
						 a pointer  to	the  resulting
						 list element object.

       int first (in)				 Index	of  the	 starting list
						 element  that	Tcl_ListObjRe-
						 place	is  to	replace.   The
						 list's	first element has  in-
						 dex 0.

       int count (in)				 The  number  of elements that
						 Tcl_ListObjReplace is to  re-
						 place.
______________________________________________________________________________

DESCRIPTION
       Tcl  list objects have an internal representation that supports the ef-
       ficient 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.

       Tcl_ListObjAppendList and Tcl_ListObjAppendElement both add one or more
       objects	to the end of the list object referenced by listPtr.  Tcl_Lis-
       tObjAppendList appends each element of the list	object	referenced  by
       elemListPtr  while  Tcl_ListObjAppendElement  appends the single	object
       referenced by objPtr.  Both procedures will convert the	object	refer-
       enced  by  listPtr  to  a list object if	necessary.  If an error	occurs
       during conversion, both procedures return TCL_ERROR and leave an	 error
       message in the interpreter's result object if interp is not NULL.  Sim-
       ilarly, if elemListPtr  does  not  already  refer  to  a	 list  object,
       Tcl_ListObjAppendList will attempt to convert it	to one and if an error
       occurs during conversion, will return TCL_ERROR and leave an error mes-
       sage  in	 the  interpreter's result object if interp is not NULL.  Both
       procedures invalidate any old string representation of listPtr and,  if
       it  was	converted  to a	list object, free any old internal representa-
       tion.  Similarly, Tcl_ListObjAppendList frees any old  internal	repre-
       sentation of elemListPtr	if it converts it to a list object.  After ap-
       pending each element in elemListPtr,  Tcl_ListObjAppendList  increments
       the element's reference count since listPtr now also refers to it.  For
       the same	reason,	Tcl_ListObjAppendElement increments objPtr's reference
       count.	If no error occurs, the	two procedures return TCL_OK after ap-
       pending the objects.

       Tcl_NewListObj and Tcl_SetListObj create	a new object or	modify an  ex-
       isting object to	hold the objc elements of the array referenced by objv
       where each element is a pointer to a Tcl	object.	 If objc 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  ref-
       erence  counts of the elements in objc since the	list object now	refers
       to them.	 The new list object returned by Tcl_NewListObj	has  reference
       count zero.

       Tcl_ListObjGetElements 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 objcPtr.	 Similarly, it returns the array pointer by storing it
       in the address objvPtr.	The memory pointed to is managed  by  Tcl  and
       should  not be freed or written to by the caller. If the	list is	empty,
       0 is stored at objcPtr and NULL at objvPtr.  If listPtr is not  already
       a  list	object,	 Tcl_ListObjGetElements	 will attempt to convert it to
       one; if the conversion fails, it	returns	TCL_ERROR and leaves an	 error
       message in the interpreter's result object if interp is not NULL.  Oth-
       erwise it returns TCL_OK	after storing the count	and array pointer.

       Tcl_ListObjLength returns the number of elements	 in  the  list	object
       referenced  by listPtr.	It returns this	count by storing an integer in
       the address intPtr.  If the  object  is	not  already  a	 list  object,
       Tcl_ListObjLength  will attempt to convert it to	one; if	the conversion
       fails, it returns TCL_ERROR and leaves an error message in  the	inter-
       preter's	 result	 object	 if  interp is not NULL.  Otherwise it returns
       TCL_OK after storing the	list's length.

       The procedure Tcl_ListObjIndex returns a	pointer	to the object at  ele-
       ment  index  in the list	referenced by listPtr.	It returns this	object
       by storing a pointer to it in the address objPtrPtr.  If	 listPtr  does
       not  already  refer  to a list object, Tcl_ListObjIndex will attempt to
       convert it to one; if the conversion fails, it  returns	TCL_ERROR  and
       leaves an error message in the interpreter's result object if interp is
       not NULL.  If the index is out of range,	that is, index is negative  or
       greater than or equal to	the number of elements in the list, Tcl_ListO-
       bjIndex stores a	NULL in	objPtrPtr and returns  TCL_OK.	 Otherwise  it
       returns	TCL_OK after storing the element's object pointer.  The	refer-
       ence count for the list element is not incremented; the caller must  do
       that if it needs	to retain a pointer to the element.

       Tcl_ListObjReplace  replaces  zero  or more elements of the list	refer-
       enced by	listPtr	with the objc objects in the array referenced by objv.
       If listPtr does not point to a list object, Tcl_ListObjReplace will at-
       tempt to	convert	it to one; if the conversion fails, it returns TCL_ER-
       ROR  and	 leaves	an error message in the	interpreter's result object if
       interp is not NULL.  Otherwise, it returns TCL_OK after	replacing  the
       objects.	  If objv is NULL, no new elements are added.  If the argument
       first is	zero or	negative, it refers to the first element.  If first 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.	 count
       gives  the number of elements to	replace.  If count is zero or negative
       then no elements	are deleted; the new elements are simply inserted  be-
       fore  the  one  designated  by  first.	Tcl_ListObjReplace invalidates
       listPtr's old string representation.  The reference counts of any  ele-
       ments  inserted	from objv are incremented since	the resulting list now
       refers to them.	Similarly, the reference counts	for any	 replaced  ob-
       jects are decremented.

       Because	Tcl_ListObjReplace  combines  both element insertion and dele-
       tion, it	can be used to implement a number of list operations.  For ex-
       ample,  the  following  code inserts the	objc objects referenced	by the
       array of	object pointers	objv just before the element index of the list
       referenced by listPtr:

	      result = Tcl_ListObjReplace(interp, listPtr, index, 0,
		      objc, objv);

       Similarly,  the	following  code	appends	the objc objects referenced by
       the array objv to the end of the	list listPtr:

	      result = Tcl_ListObjLength(interp, listPtr, &length);
	      if (result == TCL_OK) {
		  result = Tcl_ListObjReplace(interp, listPtr, length, 0,
			  objc,	objv);
	      }

       The count list elements starting	at first  can  be  deleted  by	simply
       calling Tcl_ListObjReplace with a NULL objvPtr:

	      result = Tcl_ListObjReplace(interp, listPtr, first, count,
		      0, NULL);

SEE ALSO
       Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult

KEYWORDS
       append,	index, insert, internal	representation,	length,	list, list ob-
       ject, list type,	object,	object type, replace, string representation

Tcl				      8.0			Tcl_ListObj(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_ListObjAppendElement.tcl85&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help