Caché ObjectScript Reference
$LISTUPDATE
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Updates a list by optionally replacing a specified list element or sequence of elements.
Synopsis
$LISTUPDATE(list,position,bool:val...)
$LU(list,position,bool:val...)
Parameters
list Any expression that evaluates to a list. A list can be created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST. The null string ("") is also treated as a valid list.
position A positive integer specifying the position in list to update, counting from 1. If position is larger than the number of elements in list, $LISTUPDATE appends the element, padding if necessary.
bool: Optional — A boolean variable specifying whether or not to update the specified list element. If omitted, bool defaults to 1, causing this element to be updated.
value The value used to update the list at the specified position. You can specify a comma-separated list of value parameters or bool:value pair parameters in any combination.
Description
$LISTUPDATE returns a copy of a list updated by replacing or adding one or more list elements by position. The position specifies the position in the list at which to begin updating elements. Elements are updated sequentially, starting from this position. The position can be larger than the number of elements in the list. If so, additional null elements are added to the list (if necessary) to insert a new element at the specified position. Note that position must be a positive integer; $LISTUPDATE cannot insert a new element at the beginning of the list. Setting position=0 performs no operation. $LISTUPDATE also cannot specify end-of-list, except by position count from the beginning of the list.
$LISTUPDATE can specify or more than one bool:value pairs. Multiple bool:value pairs are separated by commas. These bool:value pairs update sequential elements, beginning with the position element. If bool=1, Caché updates that element with value; if bool=0, Caché does not update that element and proceeds to the next element.
Sequential elements that are not to be updated in a sequence of bool:value pairs do not have to be specified; they can be represented by placeholder commas. The bool: parameter is optional for each value; if omitted, it defaults to 1. If you omit bool also omit the colon (:) separator character. Thus the following are permitted ways to specify a bool:value pair:
$LISTUPDATE is commonly used to return an updated version of an existing list. You can use $LISTUPDATE to create a list by specifying list="".
You can also use SET $LIST to update one or more elements in an existing list.
Examples
The following example replaces the list element at position 2 with the specified value:
   SET caps=1
   SET mylist = $LISTBUILD("Red","White","Blue")
   SET newlist = $LISTUPDATE(mylist,2,caps:"WHITE")
   ZWRITE newlist
 
The following example does not replace the list element at position 2 with the specified value:
   SET caps=0
   SET mylist = $LISTBUILD("Red","White","Blue")
   SET newlist = $LISTUPDATE(mylist,2,caps:"WHITE")
   ZWRITE newlist
 
The following example replaces the list element at position 2 with null:
   SET caps=1
   SET mylist = $LISTBUILD("Red","White","Blue")
   SET newlist = $LISTUPDATE(mylist,2,caps:"")
   ZWRITE newlist
 
The following example appends the list at position 7 with the specified value, padding null elements at positions 5 and 6:
   SET bool=1
   SET mylist = $LISTBUILD("Red","Orange","Yellow","Green")
   SET newlist = $LISTUPDATE(mylist,7,bool:"Purple")
   ZWRITE newlist
 
The following example does not append the list at position 7 with the specified value. The unchanged list is returned with no null element padding:
   SET bool=0
   SET mylist = $LISTBUILD("Red","Orange","Yellow","Green")
   SET newlist = $LISTUPDATE(mylist,7,bool:"Purple")
   ZWRITE newlist
 
The following three examples are all functionally identical. Each replaces the elements at positions 2 and 4, and appends a new element at position 7. It does not replace elements 3 and 5. Element 6 is created as a null element:
   SET mylist = $LISTBUILD("Red","Orange","Yellow","Green","Blue")
   SET newlist = $LISTUPDATE(mylist,2,1:"ORANGE",0:"YELLOW",
                                      1:"GREEN",0:"BLUE",
                                      0:"INDIGO",1:"VIOLET")
   ZWRITE newlist
 
Here the bool parameter is only specified when it is 0:
   SET mylist = $LISTBUILD("Red","Orange","Yellow","Green","Blue")
   SET newlist = $LISTUPDATE(mylist,2,"ORANGE",0:"YELLOW",
                                      "GREEN",0:"BLUE",
                                      0:"INDIGO","VIOLET")
   ZWRITE newlist
 
Here placeholder commas are used to skip elements that are not updated:
   SET mylist = $LISTBUILD("Red","Orange","Yellow","Green","Blue")
   SET newlist = $LISTUPDATE(mylist,2,"ORANGE",,"GREEN",,,"VIOLET")
   ZWRITE newlist
 
See Also