/[ascend]/trunk/base/generic/compiler/parentchild.h
ViewVC logotype

Diff of /trunk/base/generic/compiler/parentchild.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 53 by ben.allan, Sun Dec 26 20:06:01 2004 UTC revision 54 by jds, Tue Aug 2 11:20:09 2005 UTC
# Line 1  Line 1 
1  /**<  /*
2   *  Ascend Instance Tree Link Implementation   *  Ascend Instance Tree Link Implementation
3   *  by Tom Epperly & Ben Allan   *  by Tom Epperly & Ben Allan
4   *  8/16/89   *  8/16/89
# Line 29  Line 29 
29   *  COPYING.   *  COPYING.
30   */   */
31    
32  #ifndef __PARENTCHILD_H_SEEN__  /** @file
33  #define __PARENTCHILD_H_SEEN__   *  Ascend Instance Tree Link Implementation.
34     *  <pre>
   
 /**<  
35   *  When #including parentchild.h, make sure these files are #included first:   *  When #including parentchild.h, make sure these files are #included first:
36     *         #include "utilities/ascConfig.h"
37   *         #include "instance_enum.h"   *         #include "instance_enum.h"
38   *         #include "compiler.h"   *         #include "compiler.h"
39   */   *  </pre>
   
   
 /**<  
  *  Parent routines  
  *  
40   *  General comments on parents:   *  General comments on parents:
41   *   *
42   *  - Parents are numbered from 1 up, so zero is never a valid   *    - Parents are numbered from 1 up, so zero is never a valid
43   *  parent number   *      parent number
44     *
45     *    - Parent lists are kept sorted by address.
46   *   *
47   *  - Parent lists are kept sorted by address.   *    - The ordering of the parents list is not predictable in
48     *      any usefull way.
49   *   *
50   *  - The ordering of the parents list is not predictable in   *    - The number of parents for a given instance can be modified
51   *  any usefull way.   *      by ARE_THE_SAME's.
52   *   *
53   *  - The number of parents for a given instance can be modified   *    - The number of parents is NOT constant for a given type.
  *  by ARE_THE_SAME's.  
54   *   *
55   *  - The number of parents is NOT constant for a given type.   *    - Parent lists will contain no duplications.
56     *      (when AddParent is used correctly, that is.)
57   *   *
58   *  - Parent lists will contain no duplications.   *    - DummyInstances don't track parents -- they play a reference
59   *  (when AddParent is used correctly, that is.)   *      count game.
60   *   *
61   *  - DummyInstances don't track parents -- they play a reference   *  General comments on children:
62   *    count game.   *
63     *    - Children are number from 1 up, so zero is never a valid child
64     *      number.
65     *
66     *    - Children numbers will remain constant for a given type except
67     *      for arrays which can have varying numbers of children.
68     *
69     *    - Children numbers may or may not change will an instance is
70     *      refined.
71     *
72     *    - Children are always sorted in increasing order either
73     *      alphabetically or numerically depending on the type of
74     *      naming.
75     *
76     *    - Children don't know what their name is.  Only a parent
77     *      knows the names of the children below it.
78     *
79     *    - DummyInstances have no children.
80   */   */
81    
82  extern unsigned long NumberParents(CONST struct Instance *);  #ifndef __PARENTCHILD_H_SEEN__
83  /**<  #define __PARENTCHILD_H_SEEN__
84   *  unsigned long NumberParents(i)  
85   *  const struct Instance *i;  /* Parent routines */
86    
87    extern unsigned long NumberParents(CONST struct Instance *i);
88    /**<
89     *  <!--  unsigned long NumberParents(i)                               -->
90     *  <!--  const struct Instance *i;                                    -->
91   *   *
92   *  Return the number of parents that instance i has.   *  Return the number of parents that instance i has.
93   *  DummyInstances have no parents, apparently.   *  DummyInstances have no parents, apparently.
94   */   */
95    
96  extern struct Instance *InstanceParent(CONST struct Instance *,unsigned long);  extern struct Instance *InstanceParent(CONST struct Instance *i, unsigned long n);
97  /**<  /**<
98   *  struct Instance *InstanceParent(i,n);   *  <!--  struct Instance *InstanceParent(i,n);                        -->
99   *  const struct Instance *i;   *  <!--  const struct Instance *i;                                    -->
100   *  unsigned long n;   *  <!--  unsigned long n;                                             -->
101   *   *
102   *  Return a pointer to parent number n.  Parents are numbered from   *  Return a pointer to parent number n.  Parents are numbered from
103   *  1 to NumberParents(i).  0(zero) is not a valid parent number.   *  1 to NumberParents(i).  0(zero) is not a valid parent number.
104   *  DummyInstances have no parents, apparently.   *  DummyInstances have no parents, apparently.
105   */   */
106    
107  extern unsigned long SearchForParent(CONST struct Instance *,  extern unsigned long SearchForParent(CONST struct Instance *i,
108           CONST struct Instance *);                                       CONST struct Instance *p);
109  /**<  /**<
110   *  unsigned long SearchForParent(i,p)   *  <!--  unsigned long SearchForParent(i,p)                           -->
111   *  const struct Instance *i,*p;   *  <!--  const struct Instance *i,*p;                                 -->
112   *   *
113   *  Look in instance "i"'s parent list for parent "p".  If "p" is not   *  Look in instance "i"'s parent list for parent "p".  If "p" is not
114   *  found, it will return 0; otherwise, it will return the parent number of   *  found, it will return 0; otherwise, it will return the parent number of
# Line 97  extern unsigned long SearchForParent(CON Line 116  extern unsigned long SearchForParent(CON
116   *  DummyInstance never has parents, it thinks.   *  DummyInstance never has parents, it thinks.
117   */   */
118    
119  extern void DeleteParent(struct Instance *,unsigned long);  extern void DeleteParent(struct Instance *i, unsigned long pos);
120  /**<  /**<
121   *  void DeleteParent(i,pos)   *  <!--  void DeleteParent(i,pos)                                     -->
122   *  Remove parent in pos from i's parent list.   *  Remove parent in pos from i's parent list.
123   *  DummyInstance just reduces its reference count.   *  DummyInstance just reduces its reference count.
124   */   */
125    
126  extern struct InstanceName ParentsName(CONST struct Instance *,  extern struct InstanceName ParentsName(CONST struct Instance *p,
127                                         CONST struct Instance *);                                         CONST struct Instance *c);
128  /**<  /**<
129   *  struct InstanceName ParentsName(p,c)   *  <!--  struct InstanceName ParentsName(p,c)                         -->
130   *  const struct Instance *p,*c;   *  <!--  const struct Instance *p,*c;                                 -->
131   *   *
132   *  This will returns parent "p"'s name for "c".  This assumes that   *  This will returns parent "p"'s name for "c".  This assumes that
133   *  "c" is actually a child of "p", and it will return a bad value if   *  "c" is actually a child of "p", and it will return a bad value if
# Line 120  extern struct InstanceName ParentsName(C Line 139  extern struct InstanceName ParentsName(C
139   *  because you aren't supposed to care about dummy instances.   *  because you aren't supposed to care about dummy instances.
140   */   */
141    
142  extern void AddParent(struct Instance *, struct Instance *);  extern void AddParent(struct Instance *i, struct Instance *p);
143  /**<  /**<
144   *  void AddParent(i,p)   *  <!--  void AddParent(i,p)                                          -->
145   *  struct Instance *i,*p;   *  <!--  struct Instance *i,*p;                                       -->
146   *   *
147   *  This will add parent "p" to instance "i"'s parent list.  This only   *  This will add parent "p" to instance "i"'s parent list.  This only
148   *  creates the link from "i" to "p"; it doesn't create the link from   *  creates the link from "i" to "p"; it doesn't create the link from
# Line 137  extern void AddParent(struct Instance *, Line 156  extern void AddParent(struct Instance *,
156   *  things work out ok.   *  things work out ok.
157   */   */
158    
159  /**<  /* Children routines */
  *  Children routines  
  *  
  *  General comments on children:  
  *  - Children are number from 1 up, so zero is never a valid child  
  *  number.  
  *  
  *  - Children numbers will remain constant for a given type except  
  *  for arrays which can have varying numbers of children.  
  *  
  *  - Children numbers may or may not change will an instance is  
  *  refined.  
  *  
  *  - Children are always sorted in increasing order either  
  *  alphabetically or numerically depending on the type of  
  *  naming.  
  *  
  *  - Children don't know what their name is.  Only a parent  
  *  knows the names of the children below it.  
  *  
  *  - DummyInstances have no children.  
  */  
160    
161  extern unsigned long NumberChildren(CONST struct Instance *);  extern unsigned long NumberChildren(CONST struct Instance *i);
162  /**<  /**<
163   *  unsigned long NumberChildren(i)   *  <!--  unsigned long NumberChildren(i)                              -->
164   *  const struct Instance *i;   *  <!--  const struct Instance *i;                                    -->
165   *   *
166   *  Return the number of children that instance i has.   *  Return the number of children that instance i has.
167   */   */
168    
169    
170  extern struct Instance *InstanceChild(CONST struct Instance *,  extern struct Instance *InstanceChild(CONST struct Instance *i,
171                                        unsigned long);                                        unsigned long n);
172  /**<  /**<
173   *  struct Instance *InstanceChild(i,n)   *  <!--  struct Instance *InstanceChild(i,n)                          -->
174   *  const struct Instance *i;   *  <!--  const struct Instance *i;                                    -->
175   *  unsigned long n;   *  <!--  unsigned long n;                                             -->
176   *   *
177   *  Return a pointer to children number n.  Do not confuse the child number   *  Return a pointer to children number n.  Do not confuse the child number
178   *  n with an integer index.  The two numbers may have no correlation.   *  n with an integer index.  The two numbers may have no correlation.
# Line 183  extern struct Instance *InstanceChild(CO Line 181  extern struct Instance *InstanceChild(CO
181   *  May exit on improper i.   *  May exit on improper i.
182   */   */
183    
184  extern struct InstanceName ChildName(CONST struct Instance *,unsigned long);  extern struct InstanceName ChildName(CONST struct Instance *i, unsigned long n);
185  /**<  /**<
186   *  struct InstanceName ChildName(i,n)   *  <!--  struct InstanceName ChildName(i,n)                           -->
187   *  struct Instance *i;   *  <!--  struct Instance *i;                                          -->
188   *  unsigned long n;   *  <!--  unsigned long n;                                             -->
189   *   *
190   *  Returns the name of the n'th child of i.  Assumes that i has an   *  Returns the name of the n'th child of i.  Assumes that i has an
191   *  n'th child.   *  n'th child.
192   */   */
193    
194  extern CONST struct Statement *ChildDeclaration(CONST struct Instance *,  extern CONST struct Statement *ChildDeclaration(CONST struct Instance *i,
195                                                  unsigned long);                                                  unsigned long n);
196  /**<  /**<
197   *  CONST struct Statement *ChildDeclaration(i,n)   *  <!--  CONST struct Statement *ChildDeclaration(i,n)                -->
198   *  struct Instance *i;   *  <!--  struct Instance *i;                                          -->
199   *  unsigned long n;   *  <!--  unsigned long n;                                             -->
  *  i must not be NULL! The nth child may be NULL, but we don't care.  
200   *  Returns the declaration statement (IS_A,ALIASE,ARRAY) of the n'th child   *  Returns the declaration statement (IS_A,ALIASE,ARRAY) of the n'th child
201   *  of i, if i has an n'th child. May return NULL under very odd circumstances.   *  of i, if i has an n'th child. May return NULL under very odd circumstances.
202   *  Does not return redeclarations (refinement) statements.   *  Does not return redeclarations (refinement) statements.
203     *  i must not be NULL! The nth child may be NULL, but we don't care.
204   *  (Note that as of 2/97 this function cannot return NULL because   *  (Note that as of 2/97 this function cannot return NULL because
205   *  the ascend language is basetype safe semantically.   *  the ascend language is basetype safe semantically.)
206   */   */
207    
208  extern CONST struct TypeDescription *ChildRefines(CONST struct Instance *,  extern CONST struct TypeDescription *ChildRefines(CONST struct Instance *i,
209                                                    unsigned long);                                                    unsigned long n);
210  /**<  /**<
211   *  CONST struct TypeDescription *ChildRefines(i,n)   *  <!--  CONST struct TypeDescription *ChildRefines(i,n)              -->
212   *  struct Instance *i;   *  <!--  struct Instance *i;                                          -->
213   *  unsigned long n;   *  <!--  unsigned long n;                                             -->
214   *   *
215   *  Returns the type of the n'th child of i as determined at parse time.   *  Returns the type of the n'th child of i as determined at parse time.
216   *  The nth child of the instance i doesn't need to exist yet. (may be null)   *  The nth child of the instance i doesn't need to exist yet. (may be null)
# Line 221  extern CONST struct TypeDescription *Chi Line 219  extern CONST struct TypeDescription *Chi
219   *  If the child is an array, the type returned here   *  If the child is an array, the type returned here
220   *  will be the type of the array elements as determined at parse time.   *  will be the type of the array elements as determined at parse time.
221   *  This function may return NULL -- this merely means that at parse   *  This function may return NULL -- this merely means that at parse
222   *  time we couldn't quite untwist the naming to determine a type.   *  time we couldn't quite untwist the naming to determine a type.<br><br>
223   *   *
224   *  Warning: Unselected parts will yield instances of type DUMMYINST   *  Warning: Unselected parts will yield instances of type DUMMYINST
225   *  instead of whatever type this returns.   *  instead of whatever type this returns.
226   */   */
227    
228  extern unsigned long ChildSearch(CONST struct Instance *,  extern unsigned long ChildSearch(CONST struct Instance *i,
229                                   CONST struct InstanceName *);                                   CONST struct InstanceName *name);
230  /**<  /**<
231   *  unsigned long ChildSearch(i,name)   *  <!--  unsigned long ChildSearch(i,name)                            -->
232   *  struct Instance *sreli;   *  <!--  struct Instance *sreli;                                      -->
233   *  struct InstanceName *name;   *  <!--  struct InstanceName *name;                                   -->
234   *   *
235   *  This procedure will search instance i for a child that matches "name".   *  This procedure will search instance i for a child that matches "name".
236   *  It it is unsuccessful, it will return 0; otherwise, it will return the   *  It it is unsuccessful, it will return 0; otherwise, it will return the
# Line 242  extern unsigned long ChildSearch(CONST s Line 240  extern unsigned long ChildSearch(CONST s
240   *  error. The strings in the InstanceName must come from the symbol table.   *  error. The strings in the InstanceName must come from the symbol table.
241   */   */
242    
243  extern struct Instance *ChildByChar(CONST struct Instance *,symchar *);  extern struct Instance *ChildByChar(CONST struct Instance *i,
244  /**<                                      symchar *str);
245   *  c = ChildByChar(p,str);  /**<
246   *  struct Instance *p;   *  <!--  c = ChildByChar(p,str);                                      -->
247   *  char *str;   *  <!--  struct Instance *p;                                          -->
248   *  struct Instance *c;   *  <!--  char *str;                                                   -->
249     *  <!--  struct Instance *c;                                          -->
250   *   *
251   *  This returns to the pointer to a child, c, of parent,p, named by str.   *  This returns to the pointer to a child, c, of parent,p, named by str.
252   *  str must be a simple name. If child not found, returns NULL.   *  str must be a simple name. If child not found, returns NULL.
# Line 256  extern struct Instance *ChildByChar(CONS Line 255  extern struct Instance *ChildByChar(CONS
255   *  can have a child with a name which is not in the symbol table.   *  can have a child with a name which is not in the symbol table.
256   */   */
257    
258  /**<  /*
259   *  extern unsigned long ChildSearchRegExp(); NOT IMPLEMENTED.   *  extern unsigned long ChildSearchRegExp(); NOT IMPLEMENTED.
260   *  unsigned long ChildSearchRegExp(i,name,start)   *  unsigned long ChildSearchRegExp(i,name,start)
261   *  struct Instance *i;   *  struct Instance *i;
# Line 273  extern struct Instance *ChildByChar(CONS Line 272  extern struct Instance *ChildByChar(CONS
272   *  f   *  f
273   */   */
274    
275    extern unsigned long ChildIndex(CONST struct Instance *i,
276  extern unsigned long ChildIndex(CONST struct Instance *,                                  CONST struct Instance *child);
277      CONST struct Instance *);  /**<
278  /**<   *  <!--  unsigned long ChildIndex(i,child)                            -->
279   *  unsigned long ChildIndex(i,child)   *  <!--  const struct Instance *i,*child;                             -->
  *  const struct Instance *i,*child;  
280   *  This procedure searches through the child list of instance i for child.   *  This procedure searches through the child list of instance i for child.
281   *  If it does not find a match, it returns 0; otherwise, it will return   *  If it does not find a match, it returns 0; otherwise, it will return
282   *  the child number of "child".   *  the child number of "child".
283   */   */
284    
285  extern void StoreChildPtr(struct Instance *,unsigned long,struct Instance *);  extern void StoreChildPtr(struct Instance *i,
286  /**<                            unsigned long n,
287   *  void StoreChildPtr(i,n,child)                            struct Instance *child);
288   *  struct Instance *i,*child;  /**<
289   *  unsigned long n;   *  <!--  void StoreChildPtr(i,n,child)                                -->
290     *  <!--  struct Instance *i,*child;                                   -->
291     *  <!--  unsigned long n;                                             -->
292   *   *
293   *  Store the child pointer "child" in position n of i.  This only creates   *  Store the child pointer "child" in position n of i.  This only creates
294   *  the link from i to child, and not the back link which is created by   *  the link from i to child, and not the back link which is created by
# Line 296  extern void StoreChildPtr(struct Instanc Line 296  extern void StoreChildPtr(struct Instanc
296   *  created in a special way.   *  created in a special way.
297   */   */
298    
299  #endif  #endif  /* __PARENTCHILD_H_SEEN__ */
300  /**< __PARENTCHILD_H_SEEN__ */  

Legend:
Removed from v.53  
changed lines
  Added in v.54

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22