List

Calling sequence

Parameters

• O1, O2, 03, ...: any nsp objects (matrix of numbers, of strings, of booleans, of cells, list, …
• L: list formed with the objects (an empty list in the first case).

Description
The List data type is useful to collect objects of different types. Internally nsp lists are implemented as doubled linked lists and operations (extraction, insertion, deletion) on head and queue are efficient. The list (or list_create) function can be used to create lists.

Operations on lists

• L.add[e,i] inserts the object e in position i of L (elements previously at positions i,i+1,…are shifted by one on the right).
• L.add_first[e] appends the object e in head of L.
• L.add_last[e] appends the object e in queue of L.
• L.compact[[dir]] compacts the list L by trying to concatenate (if possible) successive elements of compatible size and same type. The optional argument dir is a string: "row" (or "r") to concatenate by row and "col" (or "c") to concatenate by column (which is the default).
• L.concat[LL] appends the list LL to L.
• L.first[] returns the first element of L.
• L.item[i] returns the i th element of L.
• L.last[] returns the last element of L.
• L.remove[i] removes the i-th element of L (elements previously at positions following i are shifted to the left).
• L.remove_first[] removes the element in head of L.
• L.remove_last[] removes the element in queue of L.
• L.reverse[] reverses the elements positions of the list L.
• L.sublist[ind] returns a new list (L is not modified) built from the elements of L given by the vector ind (checking validity of indices).
• [found[,index]]=L.has[Obj] search if the the object Obj is in the list L and return a scalar boolean (found). Additionnaly the (first) index of Obj in L could be returned (index=0 if found is false).

• If i is a scalar L(i) returns the i-th element of L.
• If ind is a vector of indices L(ind) puts the respective elements of L on the calling stack. Thus L(ind) returns size(ind,’*’) values that can be assigned to several variables with the standard syntax [a,b,c,...]=L(ind). Another usage is for calling sequence of functions : if L=list([1,2],%f,"c") then f(L([1,3]) is equivalent to f([1,2],"c")
• L(:) puts all the elements of L on the calling stack (with the previous list f(L(:)) is be equivalent to f([1,2],%f,"c"))
• L(i)=e replaces the i-th element of L by the object e. If i > n where n = length(L) then i-n-1 undefined elements are added at the end of the list and finally e is added (and becomes the last element of L). So L(n+1)=e (or L($+1) = e) can be used to append a new element at the tail of the list and L(0)=e can be used to insert e a new element at the head of the list (note that this element is at index 1 after the head insertion).
• More generaly L(ind)=... expects size(ind,’*’) values returned by the rhs expression which are used to set the L values at ind positions with the rules explained above.
• L(i)=null() deletes the i-th element of the list.

Note that some of these features are useful for scilab compatibility but we recommend for speed efficiency to use methods when possible. In particular, L.remove[i] should be preferred to L(i)=null() (resp. L.remove_first[] and L.remove_last[] to delete head and queue elements), Use L.add_first[e] instead of L(0)=e, and L.add_last[e] instead of L($+1) = e.

is a loop with length(L) iterations, the loop variable e being equal to L(i) at the i-th iteration.

• length(L) or size(L) return the length of L
• L=list_concat(O1,..,On) is similar to list except that the given objects which are list are concatenated whith the built list. For example list_concat(5,list(4,7),’’foo’’) will return list(5,4,7,’’foo’’).
• map(L,function [,args]): builds a new list using function(L(i),args) to build the i-th argument. The optional argument must be a list itself. Note that at the present time, the function argument must be a PList object (i.e a nsp writen function).
• foldr(L,x,function [,args]). Where the header of function is z=function(x,y,args). Suppose here as an example that L is of length 3 then a foldr call will evaluates as: function(L(1),function(L(2),function(L(3),x,args),args),args).
• foldl(L,function,x [,args]). Where the header of function is z=function(x,y,args). Suppose here as an example that L is of length 2 then a foldl call will evaluates as: function(function(function(x,L(1),args),L(2),args),L(3),args).
• unique (unique (??) )

Examples

• Creation and methods:

  L = list(1,2,"c",%f, %t, rand(2,1)) 
  // or L = list_create(1,2,"c",%f, %t, rand(2,1))  
  n = length(L) 
  // adds 0 as first element of L increasing its size 
  L.add_first[0]; L 
  n = length(L) 
  // adds pi at the tail of list increasing its size 
  L.add_last[%pi]; L 
  // deletes last element 
  L.remove_last[]; L 
  // 2 ways to extract the third element 
  L.item[3] 
  L(3) 
  // extract 5-th and 6-th elements 
  [b1,b2] = L([4,5]) 
  // reverse the list 
  L.reverse[]; L 
  // compact the list 
  L.compact[]; L 
  // build a sublist with the first and third elements 
  LL = L.sublist[[1,3]] 

• map

  function y=len(x);y=length(x);endfunction; 
  L=list(4,1:10,'foo'); 
  map(L,len) 

• foldr and foldl

  // reverse a list using foldr  
  function z=rev(x,y);z=list_concat(y,x);endfunction ; 
  L=list(1,2,3,4); 
  S=foldr(L,list(),rev) // sum the elements of a list using foldr  
  function z=lplus(x,y);z=x+y;endfunction ; 
  L=list(1,2,3,4); 
  S=foldr(L,0,lplus) 

See also unique (??) setdiff (??)

Authors jpc, bp