DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_ListObjAppendList(3tcl)




Tcl_ListObj(3)       Tcl Library Procedures        Tcl_ListObj(3)

_________________________________________________________________


NAME

     Tcl_ListObjAppendList,             Tcl_ListObjAppendElement,
     Tcl_NewListObj,    Tcl_SetListObj,   Tcl_ListObjGetElements,
     Tcl_ListObjLength,  Tcl_ListObjIndex,  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   converting
                                               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 mani-
                                               pulated.        If
                                               listPtr  does  not
                                               already point to a
                                               list   object,  an

Tcl                     Last change: 8.0                        1

Tcl_ListObj(3)       Tcl Library Procedures        Tcl_ListObj(3)

                                               attempt  will   be
                                               made to convert it
                                               to one.

     Tcl_Obj *elemListPtr (in/out)             For
                                               Tcl_ListObjAppendList,
                                               this points  to  a
                                               list  object  con-
                                               taining   elements
                                               to   be   appended
                                               onto      listPtr.
                                               Each   element  of
                                               *elemListPtr  will
                                               become  a new ele-
                                               ment  of  listPtr.
                                               If *elemListPtr is
                                               not NULL and  does
                                               not  already point
                                               to a list  object,
                                               an attempt will be
                                               made to convert 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_ListObjGetElements
                                               stores  a  pointer
                                               to   an  array  of
                                               pointers  to   the
                                               element objects of

Tcl                     Last change: 8.0                        2

Tcl_ListObj(3)       Tcl Library Procedures        Tcl_ListObj(3)

                                               listPtr.

     int objc (in)                             The number of  Tcl
                                               objects       that
                                               Tcl_NewListObj
                                               will insert 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
                                               objects.
                                               Tcl_NewListObj
                                               will insert  these
                                               objects into a new
                                               list  object   and
                                               Tcl_ListObjReplace
                                               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.

Tcl                     Last change: 8.0                        3

Tcl_ListObj(3)       Tcl Library Procedures        Tcl_ListObj(3)

     int first (in)                            Index    of    the
                                               starting list ele-
                                               ment          that
                                               Tcl_ListObjReplace
                                               is   to   replace.
                                               The  list's  first
                                               element has  index
                                               0.

     int count (in)                            The number of ele-
                                               ments         that
                                               Tcl_ListObjReplace
                                               is to replace.
_________________________________________________________________


DESCRIPTION

     Tcl list objects have an internal representation  that  sup-
     ports  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.

     Tcl_ListObjAppendList and Tcl_ListObjAppendElement both  add
     one or more objects to the end of the list object referenced
     by listPtr.  Tcl_ListObjAppendList appends each  element  of
     the    list   object   referenced   by   elemListPtr   while
     Tcl_ListObjAppendElement appends the  single  object  refer-
     enced  by  objPtr.   Both procedures will convert the object
     referenced 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.  Similarly, if elem-
     ListPtr  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  message  in  the interpreter's result
     object if interp is not NULL.   Both  procedures  invalidate
     any old string representation of listPtr and, if it was con-
     verted to a list object, free any old  internal  representa-
     tion.  Similarly, Tcl_ListObjAppendList frees any old inter-
     nal representation of elemListPtr if it  converts  it  to  a
     list  object.   After appending 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  refer-
     ence  count.   If no error occurs, the two procedures return
     TCL_OK after appending the objects.

     Tcl_NewListObj and Tcl_SetListObj create  a  new  object  or
     modify  an  existing 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

Tcl                     Last change: 8.0                        4

Tcl_ListObj(3)       Tcl Library Procedures        Tcl_ListObj(3)

     return an empty object.  The new object's string representa-
     tion  is  left  invalid.   The  two procedures increment the
     reference 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.   Other-
     wise  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 interpreter'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  element 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_ListObjIndex stores a NULL in
     objPtrPtr and returns TCL_OK.  Otherwise it  returns  TCL_OK
     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.

     Tcl_ListObjReplace replaces zero or  more  elements  of  the
     list  referenced  by  listPtr  with  the objc objects in the
     array referenced by objv.  If listPtr does not  point  to  a
     list  object,  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 object
     if interp is not NULL.  Otherwise, it returns  TCL_OK  after
     replacing the objects.  If objv is NULL, no new elements are

Tcl                     Last change: 8.0                        5

Tcl_ListObj(3)       Tcl Library Procedures        Tcl_ListObj(3)

     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 before  the  one  designated  by  first.
     Tcl_ListObjReplace    invalidates   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 objects are decremented.

     Because Tcl_ListObjReplace combines both  element  insertion
     and  deletion,  it can be used to implement a number of list
     operations.  For example, 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 object, list type, object, object type, replace,
     string representation

Tcl                     Last change: 8.0                        6


Man(1) output converted with man2html