docs.intersystems.com
InterSystems IRIS Data Platform 2019.2  /  ObjectScript Reference  /  ObjectScript Functions

ObjectScript Reference
$LISTGET
Previous section           Next section
InterSystems: The power behind what matters   
Search:  


Returns an element in a list, or a specified default value if the requested element is undefined.
Synopsis
$LISTGET(list,position,default)
$LG(list,position,default)

SET $LISTGET(var1,var2,...)=list
SET $LG(var1,var2,...)=list
Parameters
list An expression that evaluates to a valid list.
position
Optional — An integer code specifying the starting position in list. Permitted values are n (count from beginning of list), * (last element in list), and *-n (relative offset count backwards from end of list). Thus, the first element in the list is 1, the second element is 2, the last element in the list is *, and the next-to-last element is *-1. If position is a fractional number, it is truncated to its integer part. If position is omitted, it defaults to 1.
-1 may be used in older code to specify the last element in the list. This deprecated use of -1 should not be combined with * or *-n relative offset syntax.
default Optional — An expression that provides the value to return if the list element has an undefined value. If default is omitted, it defaults to the null string (““). You must specify a position parameter value to specify a default value.
var A variable, specified as a single variable or as a variable in a comma-separated list of variables. A placeholder comma can be specified for an omitted variable. A var may be a variable of any type: local, process-private, or global, unsubscripted or subscripted.
Description
$LISTGET has two syntax forms: $LISTGET and SET $LISTGET:
Parameters
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. You can use $LISTVALID to determine if list is a valid list. An invalid list causes $LISTGET to generate a <LIST> error.
position
The position (element count) of the list element to return. An element is returned as a string. List elements are counted from 1. If position is omitted, $LISTGET returns the first element.
The numeric portion of the position parameter evaluates to an integer. InterSystems IRIS truncates a fractional number to its integer portion. Specifying position as -1 (indicating last element of the list) is deprecated and should not be used in new code; a position negative number less than -1 generates a <RANGE> error.
When using a variable to specify *-n you must always specify the asterisk and a sign character in the parameter itself.
The following are valid specifications of *-n:
  SET count=2
  SET alph=$LISTBUILD("a","b","c","d")
  WRITE $LISTGET(alph,*-count,"blank")
  SET count=-2
  SET alph=$LISTBUILD("a","b","c","d")
  WRITE $LISTGET(alph,*+count,"blank")
default
An expression that evaluates to a string or numeric value. $LISTGET returns default if the element specified by position does not exist. This may occur if position is beyond the end of the list, if position specifies an element that has no value, if position is 0, or if list contains no elements. However, if a position of *-n specifies a position before the 0th element of list, InterSystems IRIS issues a <RANGE> error.
If you omit the default parameter, the null string ("") is returned as the default value.
SET $LISTGET
When used on the left side of the equal sign in a SET command, the $LISTGET function extracts multiple elements from a list as a single operation. The syntax is as follows:
SET $LISTGET(var1,var2,...)=list
The var arguments of SET $LISTGET are a comma-separated list of variables, each of which is set to the value of the list element in the corresponding position. Thus, var1 is set to the value of the first list element, var2 is set to the value of the second list element, and so forth. The var arguments do not have to be existing variables; the variable is defined when SET $LISTGET assigns it a value.
SET $LISTGET is an atomic operation. The maximum number of var arguments is 1024. Attempting to exceed this number results in a <SYNTAX> error.
If a var argument is an object property (object.property) the property must be multidimensional. Any property may be referenced as an i%property instance variable within an object method.
In the following examples, $LISTBUILD (on the right side of the equal sign) creates a list with four elements.
In the following example, SET $LISTGET extracts the first two elements from a list into two variables:
   SET colorlist=$LISTBUILD("red","blue","green","white")
   SET $LISTGET(a,b)=colorlist
   WRITE "a=",a," b=",b   /* a="red" b="blue" */
In the following example, SET $LISTGET extracts elements from a list into five variables. Because the specified list does not have a 5th element, the corresponding var variable (e) is defined, with a value of the null string (""):
   SET (a,b,c,d,e)=0
   SET colorlist=$LISTBUILD("red","blue","green","white")
   SET $LISTGET(a,b,c,d,e)=colorlist
   WRITE "a=",a," b=",b," c=",c," d=",d," e=",e
   /* a="red" b="blue" c="green" d="white" e= */
In the following example, SET $LISTGET extracts elements from a list into four variables. Because the specified list does not have a 3rd element, the corresponding var variable (c) is defined with a value of the null string (""):
   SET (a,b,c,d)=0
   SET colorlist=$LISTBUILD("red","blue",,"white")
   SET $LISTGET(a,b,c,d)=colorlist
   WRITE "a=",a," b=",b," c=",c," d=",d
   /* a="red" b="blue" c= d="white" */
In the following example, SET $LISTGET extracts elements from a list into four variables. Because the 3rd list element value is a nested list, the corresponding var variable (c) contains a list value:
   SET (a,b,c,d)=0
   SET colorlist=$LISTBUILD("red","blue",$LISTBUILD("green","yellow"),"white")
   SET $LISTGET(a,b,c,d)=colorlist
   WRITE "a=",a," b=",b," c=",c," d=",d
   /* a="red" b="blue" c=$LB("green","yellow") d="white" */
Examples
The $LISTGET functions in the following example return the value of the list element specified by position (the position default is 1):
   SET list=$LISTBUILD("A","B","C")
   WRITE !,$LISTGET(list)     ; returns "A"
   WRITE !,$LISTGET(list,1)   ; returns "A"
   WRITE !,$LISTGET(list,3)   ; returns "C"
   WRITE !,$LISTGET(list,*)   ; returns "C"
   WRITE !,$LISTGET(list,*-1) ; returns "B"
The $LISTGET functions in the following example return a value upon encountering the undefined 2nd element in the list. The first two returns a question mark (?), which the user has defined as the default value. The second two returns a null string because the user has not specified a default value:
   WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),2,"?"),!
   WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),*-1,"?"),!
   WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),2),!
   WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),*-1)
The following example returns all of the element values in the list. It also lists the positions before and after the ends of the list. Where a value is non-existent, it returns the default value:
   SET list=$LISTBUILD("a","b",,"d",,,"g")
   SET llen=$LISTLENGTH(list)
      FOR x=0:1:llen+1 { 
      WRITE "position ",x,"=",$LISTGET(list,x," no value"),!
      }
      WRITE "end of the list"
The following example returns all of the element values in the list in reverse order. Where a value is omitted, it returns the default value:
   SET list=$LISTBUILD("a","b",,"d",,,"g")
   SET llen=$LISTLENGTH(list)
      FOR x=0:1:llen { 
      WRITE "position *-",x,"=",$LISTGET(list,*-x," no value"),!
      }
      WRITE "beginning of the list"
The $LISTGET functions in the following example return the list element value of the null string; they do not return the default value:
   WRITE "returns:",$LISTGET($LB(""),1,"no value"),!
   WRITE "returns:",$LISTGET($LB(""),*,"no value"),!
   WRITE "returns:",$LISTGET($LB(""),*-0,"no value")
The $LISTGET functions in the following example all return the default value:
   WRITE $LISTGET("",1,"no value"),!
   WRITE $LISTGET($LB(),1,"no value"),!
   WRITE $LISTGET($LB(UndefinedVar),1,"no value"),!
   WRITE $LISTGET($LB(,),1,"no value"),!
   WRITE $LISTGET($LB(,),*,"no value"),!
   WRITE $LISTGET($LB(,),*-1,"no value"),!
   WRITE $LISTGET($LB(""),2,"no value"),!
   WRITE $LISTGET($LB(""),*-1,"no value")
See Also


Previous section           Next section
Send us comments on this page
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-10-18 06:48:42