Function: listput
Section: programming/specific
C-Name: listput0
Prototype: WGD0,L,
Help: listput(list,x,{n}): sets n-th element of list equal to x. If n is
 omitted or greater than the current list length, appends x.
Description:
 (list, gen, small):gen        listput($1, $2, $3)
Doc:
 sets the $n$-th element of the list
 \var{list} (which must be of type \typ{LIST}) equal to $x$. If $n$ is omitted,
 or greater than the list length, appends $x$. The function returns the
 inserted element.
 \bprog
 ? L = List();
 ? listput(L, 1)
 %2 = 1
 ? listput(L, 2)
 %3 = 2
 ? L
 %4 = List([1, 2])
 @eprog

 You may put an element into an occupied cell (not changing the
 list length), but it is easier to use the standard \kbd{list[n] = x}
 construct.
 \bprog
 ? listput(L, 3, 1) \\ insert at position 1
 %5 = 3
 ? L
 %6 = List([3, 2])
 ? L[2] = 4 \\ simpler
 %7 = List([3, 4])
 ? L[10] = 1  \\ can't insert beyond the end of the list
  ***   at top-level: L[10]=1
  ***                  ^------
  ***   non-existent component: index > 2
 ? listput(L, 1, 10) \\ but listput can
 %8 = 1
 ? L
 %9 = List([3, 2, 1])
 @eprog

 This function runs in time $O(\#L)$ in the worst case (when the list must
 be reallocated), but in time $O(1)$ on average: any number of successive
 \kbd{listput}s run in time $O(\#L)$, where $\#L$ denotes the list
 \emph{final} length.