1--  Copyright 1994 Grady Booch
2--  Copyright 1994-1997 David Weller
3--  Copyright 1998-2014 Simon Wright <simon@pushface.org>
4
5--  This package is free software; you can redistribute it and/or
6--  modify it under terms of the GNU General Public License as
7--  published by the Free Software Foundation; either version 2, or
8--  (at your option) any later version. This package is distributed in
9--  the hope that it will be useful, but WITHOUT ANY WARRANTY; without
10--  even the implied warranty of MERCHANTABILITY or FITNESS FOR A
11--  PARTICULAR PURPOSE. See the GNU General Public License for more
12--  details. You should have received a copy of the GNU General Public
13--  License distributed with this package; see file COPYING.  If not,
14--  write to the Free Software Foundation, 59 Temple Place - Suite
15--  330, Boston, MA 02111-1307, USA.
16
17--  As a special exception, if other files instantiate generics from
18--  this unit, or you link this unit with other files to produce an
19--  executable, this unit does not by itself cause the resulting
20--  executable to be covered by the GNU General Public License.  This
21--  exception does not however invalidate any other reasons why the
22--  executable file might be covered by the GNU Public License.
23
24with BC.Support.AVL_Trees;
25with System.Storage_Pools;
26
27generic
28   with function "<" (L, R : Item) return Boolean is <>;
29   Storage : in out System.Storage_Pools.Root_Storage_Pool'Class;
30package BC.Containers.Trees.AVL is
31
32   pragma Preelaborate;
33
34   type AVL_Tree is new BC.Containers.Container with private;
35
36   function "=" (L, R : AVL_Tree) return Boolean;
37   --  return True if both trees contain the same Elements.
38
39   function Null_Container return AVL_Tree;
40
41   procedure Clear (T : in out AVL_Tree);
42   --  Make the tree null and reclaim the storage associated with its items.
43
44   procedure Insert (T : in out AVL_Tree;
45                     Element : Item;
46                     Not_Found : out Boolean);
47   --  Add the item to the tree, preserving the tree's
48   --  balance. Not_Found is set to True if the item had not
49   --  previously existed in the tree, and to False otherwise.
50
51   procedure Delete
52     (T : in out AVL_Tree; Element : Item; Found : out Boolean);
53   --  Remove the item from the tree, preserving the tree's
54   --  balance. Found is set to True if the item was in fact found in
55   --  the tree and removed, and to False otherwise.
56
57   function Extent (T : AVL_Tree) return Natural;
58   --  Return the number of items in the tree.
59
60   function Is_Null (T : AVL_Tree) return Boolean;
61   --  Return True if and only if the tree has no items.
62
63   function Is_Member (T : AVL_Tree; Element : Item) return Boolean;
64   --  Return True if and only if the item exists in the tree.
65
66   function New_Iterator (For_The_Tree : AVL_Tree) return Iterator'Class;
67   --  Return a reset Iterator bound to the specific tree.
68
69   generic
70      with procedure Apply (Elem : in out Item);
71   procedure Access_Actual_Item (In_The_Tree : AVL_Tree;
72                                 Elem : Item;
73                                 Found : out Boolean);
74   --  If an Item "=" to Elem is present in the Tree, call Apply for
75   --  it and set Found to True; otherwise, set Found to False.
76   --  Apply MUST NOT alter the result of the ordering operation "<".
77
78   -------------------------------------------------------------------
79   --  The  functionality of  Visit and  Modify is  also available  --
80   --  using the  standard Container generic. Note  that, as here,  --
81   --  the  Apply used  there MUST  NOT  alter the  result of  the  --
82   --  ordering operation "<".                                      --
83   -------------------------------------------------------------------
84
85   generic
86      with procedure Apply (Elem : in Item; OK : out Boolean);
87   procedure Visit (Over_The_Tree : AVL_Tree);
88   --  Call Apply with a copy of each Item in the Tree, in order. The
89   --  iteration will terminate early if Apply sets OK to False.
90
91   generic
92      with procedure Apply (Elem : in out Item; OK : out Boolean);
93   procedure Modify (Over_The_Tree : AVL_Tree);
94   --  Call Apply for each Item in the Tree, in order. The iteration will
95   --  terminate early if Apply sets OK to False.
96   --  Apply MUST NOT alter the result of the ordering operation "<".
97
98private
99
100   package Support is new BC.Support.AVL_Trees
101     (Item => Item,
102      "=" => "=",
103      "<" => "<",
104      Storage => Storage);
105
106   type AVL_Tree is new BC.Containers.Container with record
107      Rep : Support.AVL_Tree;
108   end record;
109
110   --  Iterator implementations.
111
112   type AVL_Tree_Iterator is new Iterator with record
113      Previous, Current : Support.AVL_Node_Ref;
114   end record;
115
116   procedure Reset (It : in out AVL_Tree_Iterator);
117
118   procedure Next (It : in out AVL_Tree_Iterator);
119
120   function Is_Done (It : AVL_Tree_Iterator) return Boolean;
121
122   function Current_Item (It : AVL_Tree_Iterator) return Item;
123
124   procedure Delete_Item_At (It : in out AVL_Tree_Iterator);
125
126   function Current_Item_Ptr (It : AVL_Tree_Iterator) return Item_Ptr;
127
128end BC.Containers.Trees.AVL;
129