Tcl_ListObjGetElements man page on OpenMandriva

Man page or keyword search:  
man Server   8135 pages
apropos Keyword Search (all sections)
Output format
OpenMandriva logo
[printable version]

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 values 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 a value to be a  list
						 value,	 an  error  message is
						 left  in  the	 interpreter's
						 result value unless interp is
						 NULL.

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

       Tcl_Obj *elemListPtr (in/out)		 For	Tcl_ListObjAppendList,
						 this  points  to a list value
						 containing  elements  to   be
						 appended  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  value,  an
						 attempt  will be made to con‐
						 vert it to one.

       Tcl_Obj *objPtr (in)			 For Tcl_ListObjAppendElement,
						 points	 to the Tcl value that
						 will be appended to  listPtr.
						 For	Tcl_SetListObj,	  this
						 points to the Tcl value  that
						 will  be  converted to a list
						 value	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	values
						 in listPtr.

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

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

       Tcl_Obj *const objv[] (in)		 An array of pointers to  val‐
						 ues.	 Tcl_NewListObj	  will
						 insert these  values  into  a
						 new list value and Tcl_ListO‐
						 bjReplace  will  insert  them
						 into	an  existing  listPtr.
						 Each value will become a sep‐
						 arate 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 value.

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

       int count (in)				 The  number  of elements that
						 Tcl_ListObjReplace   is    to
						 replace.
_________________________________________________________________

DESCRIPTION
       Tcl list values have an internal representation that supports the effi‐
       cient indexing and appending.  The procedures  described	 in  this  man
       page  are  used to create, modify, index, and append to Tcl list values
       from C code.

       Tcl_ListObjAppendList and Tcl_ListObjAppendElement both add one or more
       values to the end of the list value referenced by listPtr.  Tcl_ListOb‐
       jAppendList appends each element of the list value referenced by	 elem‐
       ListPtr	while Tcl_ListObjAppendElement appends the single value refer‐
       enced by objPtr.	 Both procedures will convert the value referenced  by
       listPtr	to  a list value if necessary.	If an error occurs during con‐
       version, both procedures return TCL_ERROR and leave an error message in
       the  interpreter's  result  value if interp is not NULL.	 Similarly, if
       elemListPtr does not already refer  to  a  list	value,	Tcl_ListObjAp‐
       pendList	 will attempt to convert it to one and if an error occurs dur‐
       ing conversion, will return TCL_ERROR and leave an error message in the
       interpreter's  result  value  if	 interp	 is not NULL.  Both procedures
       invalidate any old string representation of listPtr and, if it was con‐
       verted  to  a  list value, free any old internal representation.	 Simi‐
       larly, Tcl_ListObjAppendList frees any old internal  representation  of
       elemListPtr  if	it  converts it to a list value.  After appending each
       element in elemListPtr, Tcl_ListObjAppendList increments the  element's
       reference count since listPtr now also refers to it.  For the same rea‐
       son, Tcl_ListObjAppendElement increments objPtr's reference count.   If
       no  error  occurs, the two procedures return TCL_OK after appending the
       values.

       Tcl_NewListObj and Tcl_SetListObj create	 a  new	 value	or  modify  an
       existing	 value	to  hold  the objc elements of the array referenced by
       objv where each element is a pointer to a Tcl value.  If objc  is  less
       than  or	 equal	to  zero, they return an empty value.  The new value's
       string representation is left invalid.  The  two	 procedures  increment
       the  reference  counts of the elements in objc since the list value now
       refers to them.	The new list value returned by Tcl_NewListObj has ref‐
       erence count zero.

       Tcl_ListObjGetElements returns a count and a pointer to an array of the
       elements in a list value.  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 value, Tcl_ListObjGetElements will attempt to convert it to one;
       if the conversion fails, it returns TCL_ERROR and leaves an error  mes‐
       sage  in	 the interpreter's result value if interp is not NULL.	Other‐
       wise it returns TCL_OK after storing the count and array pointer.

       Tcl_ListObjLength returns the number of elements in the list value ref‐
       erenced by listPtr.  It returns this count by storing an integer in the
       address intPtr.	If the value is not already a list value,  Tcl_ListOb‐
       jLength	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  value 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 value  at  ele‐
       ment index in the list referenced by listPtr.  It returns this value by
       storing a pointer to it in the address objPtrPtr.  If listPtr does  not
       already refer to a list value, 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 value 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_ListObjIndex
       stores a NULL in objPtrPtr and returns TCL_OK.	Otherwise  it  returns
       TCL_OK  after storing the element's value 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.

       Tcl_ListObjReplace  replaces  zero  or more elements of the list refer‐
       enced by listPtr with the objc values in the array referenced by	 objv.
       If  listPtr  does  not  point  to a list value, Tcl_ListObjReplace 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 value
       if interp is not NULL.  Otherwise, it returns  TCL_OK  after  replacing
       the  values.  If objv is NULL, no new elements are added.  If the argu‐
       ment 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 before the one designated by first.  Tcl_ListObjReplace inval‐
       idates listPtr's old string representation.  The	 reference  counts  of
       any  elements  inserted	from  objv are incremented since the resulting
       list now refers to them.	  Similarly,  the  reference  counts  for  any
       replaced values are decremented.

       Because	Tcl_ListObjReplace  combines  both element insertion and dele‐
       tion, it can be used to implement a number  of  list  operations.   For
       example,	 the  following code inserts the objc values referenced by the
       array of value 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 values 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(3),  Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_GetObjRe‐
       sult(3)

KEYWORDS
       append, index, insert,  internal	 representation,  length,  list,  list
       value, list type, value, value type, replace, string representation

Tcl				      8.0			Tcl_ListObj(3)
[top]

List of man pages available for OpenMandriva

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net