help/list

   1 NAME
   2     list - create list of specified values
   3
   4 SYNOPSIS
   5     list([x, [x, ... ]])
   6
   7 TYPES
   8     x           any, &any
   9
  10     return      list
  11
  12 DESCRIPTION
  13     This function returns a list that is composed of the arguments x.
  14     If no args are given, an empty list is returned.
  15
  16     Lists are a sequence of values which are doubly linked so that
  17     elements can be removed or inserted anywhere within the list.
  18     The function 'list' creates a list with possible initial elements.
  19     For example,
  20
  21             x = list(4, 6, 7);
  22
  23     creates a list in the variable x of three elements, in the order
  24     4, 6, and 7.
  25
  26     The 'push' and 'pop' functions insert or remove an element from
  27     the beginning of the list.  The 'append' and 'remove' functions
  28     insert or remove an element from the end of the list.  The 'insert'
  29     and 'delete' functions insert or delete an element from the middle
  30     (or ends) of a list.  The functions which insert elements return
  31     the null value, but the functions which remove an element return
  32     the element as their value.  The 'size' function returns the number
  33     of elements in the list.
  34
  35     Note that these functions manipulate the actual list argument,
  36     instead of returning a new list.  Thus in the example:
  37
  38             push(x, 9);
  39
  40     x becomes a list of four elements, in the order 9, 4, 6, and 7.
  41     Lists can be copied by assigning them to another variable.
  42
  43     An arbitrary element of a linked list can be accessed by using the
  44     double-bracket operator.  The beginning of the list has index 0.
  45     Thus in the new list x above, the expression x[[0]] returns the
  46     value of the first element of the list, which is 9.  Note that this
  47     indexing does not remove elements from the list.
  48
  49     Since lists are doubly linked in memory, random access to arbitrary
  50     elements can be slow if the list is large.  However, for each list
  51     a pointer is kept to the latest indexed element, thus relatively
  52     sequential accesses to the elements in a list will not be slow.
  53
  54     Lists can be searched for particular values by using the 'search'
  55     and 'rsearch' functions.  They return the element number of the
  56     found value (zero based), or null if the value does not exist in
  57     the list.
  58
  59 EXAMPLE
  60     > list(2,"three",4i)
  61
  62     list (3 elements, 3 nonzero):
  63       [[0]] = 2
  64       [[1]] = "three"
  65       [[2]] = 4i
  66
  67     > list()
  68             list (0 elements, 0 nonzero)
  69
  70 LIMITS
  71     none
  72
  73 LINK LIBRARY
  74     none
  75
  76 SEE ALSO
  77     append, delete, insert, islist, pop, push, remove, rsearch, search, size
  78