interpreter/preprocessor/faust-0.9.47mr3/compiler/headers/list.hh

   1 /************************************************************************
   2  ************************************************************************
   3     FAUST compiler
   4         Copyright (C) 2003-2004 GRAME, Centre National de Creation Musicale
   5     ---------------------------------------------------------------------
   6     This program is free software; you can redistribute it and/or modify
   7     it under the terms of the GNU General Public License as published by
   8     the Free Software Foundation; either version 2 of the License, or
   9     (at your option) any later version.
  10
  11     This program is distributed in the hope that it will be useful,
  12     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14     GNU General Public License for more details.
  15
  16     You should have received a copy of the GNU General Public License
  17     along with this program; if not, write to the Free Software
  18     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  19  ************************************************************************
  20  ************************************************************************/
  21
  22
  23
  24 /*****************************************************************************
  25 ******************************************************************************
  26                                                                 LIST
  27                                                 Y. Orlarey, (c) Grame 2002
  28 ------------------------------------------------------------------------------
  29 This file contains several extensions to the tree library :
  30         - lists : based on a operations like cons, hd , tl, ...
  31         - environments : list of associations (key value)
  32         - property list : used to annotate trees
  33
  34
  35  API:
  36  ----
  37
  38         List :
  39         -----
  40
  41         nil                                     = predefined empty list
  42         cons (x,l)                      = create a nex list of head x and tail l
  43         hd(cons(x,l))           = x,
  44         tl (cons(x,l))          = l
  45         nth(l,i)                        = ith element of l (or nil)
  46         replace(l,i,e)          = a copy of l where the ith element is e
  47         len(l)                          = number of elements of l
  48         isNil(nil)                      = true          (false otherwise)
  49         isList(cons(x,l))       = true          (false otherwise)
  50         list(a,b,..)            = cons(a, list(b,...))
  51
  52         lmap(f, cons(x,l))      = cons(f(x), lmap(f,l))
  53         reverse([a,b,..,z])     = [z,..,b,a]
  54         reverseall([a,b,..,z])  = [ra(z),..,ra(b),ra(a)] where ra is reverseall
  55
  56         Set :
  57         -----
  58         (Sets are implemented as ordered lists of elements without duplication)
  59
  60         isElement(e,s)                  = true if e is an element of set s, false otherwise
  61         addElement(e,s)                 = s U {e}
  62         remElement(e,s)                 = s - {e}
  63         singleton(e)                    = {e}
  64         list2set(l)                             = convert a list into a set
  65         setUnion(s1,s2)                 = s1 U s2
  66         setIntersection(s1,s2)  = s1 intersection s2
  67         setDifference(s1,s2)    = s1 - s2
  68
  69         Environment :
  70         -------------
  71
  72         An 'environment' is a stack of pairs (key x value) used to keep track of lexical bindings
  73
  74         pushEnv (key, val, env) -> env' create a new environment
  75         searchEnv (key,&v,env) -> bool  search for key in env and set v accordingly
  76
  77         search(k1,&v, push(k2,x,env))   = true and v is set to x if k1==k2
  78                                                                         = search(k1,&v,env) if k1 != k2
  79         Property list :
  80         ---------------
  81
  82         Every tree can be annotated with an 'attribut' field. This attribute field
  83         can be used to manage a property list (pl). A property list is a list of pairs
  84         key x value, with three basic operations :
  85
  86         setProperty (t, key, val) -> t          add the association (key x val) to the pl of t
  87         getProperty (t, key, &val) -> bool      search the pp of t for the value associated to key
  88         remProperty (t, key) -> t                       remove any association (key x ?) from the pl of t
  89
  90  Warning :
  91  ---------
  92  Since reference counters are used for garbage collecting, one must be careful not to
  93  create cycles in trees. The only possible source of cycles is by setting the attribut
  94  of a tree t to a tree t' that contains t as a subtree.
  95
  96  History :
  97  ---------
  98         2002-02-08 : First version
  99         2002-02-20 : New description of the API, non recursive lmap and reverse
 100         2002-03-29 : Added function remElement(e,set), corrected comment error
 101
 102 ******************************************************************************
 103 *****************************************************************************/
 104
 105 #ifndef     __LIST__
 106 #define     __LIST__
 107
 108 #include "symbol.hh"
 109 #include "tree.hh"
 110 #include <stdio.h>
 111
 112 // Basic List Operations implemented on trees
 113
 114 extern Sym                      CONS;
 115 extern Sym                      NIL;
 116 extern Tree     nil;
 117
 118 typedef Tree (*tfun)(Tree);
 119
 120 void print (Tree t, FILE* out=stdout);
 121 //bool printlist (const CTree* lc);
 122
 123 // to create new lists
 124 inline Tree     cons (Tree a, Tree b)           { return tree (CONS, a, b); }
 125
 126 inline Tree     list0 ()                                                                { return nil; }
 127 inline Tree     list1 (Tree a)                                                  { return cons (a, list0()); }
 128 inline Tree     list2 (Tree a, Tree b)                                  { return cons (a, list1(b)); }
 129 inline Tree     list3 (Tree a, Tree b, Tree c)                  { return cons (a, list2(b, c)); }
 130 inline Tree     list4 (Tree a, Tree b, Tree c, Tree d)  { return cons (a, list3(b, c, d)); }
 131
 132 // to access the head and the tail of a list
 133 inline Tree     hd (Tree l)                             { return l->branch(0); }
 134 inline Tree     tl (Tree l)                             { return l->branch(1); }
 135
 136 // predicates
 137 inline bool     isNil (Tree l)                  { return (l->node() == Node(NIL)) && (l->arity() == 0) ; }
 138 inline bool     isList (Tree l)                 { return (l->node() == Node(CONS)) && (l->arity() == 2) ; }
 139
 140 // predicates
 141 Tree                    nth(Tree l, int i);
 142 Tree                    replace(Tree l, int i, Tree e);
 143 int                             len(Tree l);
 144
 145 // reversing
 146 Tree reverse (Tree l);
 147 Tree reverseall (Tree l);
 148
 149 // operations
 150 Tree rconcat(Tree l1, Tree l2);
 151 Tree concat(Tree l1, Tree l2);
 152 Tree lrange(Tree l, int i, int j); // de i a j exclu
 153
 154 // mapping
 155 Tree lmap       (tfun f, Tree l);
 156
 157 // Sets
 158 bool isElement (Tree e, Tree l);
 159 Tree addElement (Tree e, Tree l1);
 160 Tree remElement (Tree e, Tree l1);
 161 Tree singleton (Tree l);
 162 Tree list2set (Tree l);
 163 Tree setUnion (Tree l1, Tree l2);
 164 Tree setIntersection (Tree l1, Tree l2);
 165 Tree setDifference (Tree l1, Tree l2);
 166
 167 // functions as set of pairs key x value
 168 Tree addFun(Tree k, Tree v, Tree l);
 169 bool getFun(Tree k, Tree& v, Tree l);
 170
 171 // Pairs
 172
 173 //inline Tree pair (Tree t1, Tree t2) { return cons(t1,t2);  }
 174 inline Tree left (Tree t)                       { return t->branch(0); }
 175 inline Tree right (Tree t)                      { return t->branch(1); }
 176
 177
 178 // Environment : stack of pairs key value)
 179 Tree    pushEnv (Tree key, Tree val, Tree env=nil);
 180 bool    searchEnv (Tree key, Tree& v, Tree env);
 181
 182 // Operations on the property list of a tree t
 183 void    setProperty (Tree t, Tree key, Tree val);
 184 bool    getProperty (Tree t, Tree key, Tree& val);
 185 void    remProperty (Tree t, Tree key);
 186
 187 // Mapping sur les arbres
 188 Tree tmap (Tree k, tfun f, Tree t);
 189
 190 // remplacement
 191 Tree substitute (Tree t, Tree id, Tree val);
 192
 193
 194 #endif