1 ------------------------------------------------------------------------------
3 -- GNAT LIBRARY COMPONENTS --
5 -- ADA.CONTAINERS.RED_BLACK_TREES.GENERIC_KEYS --
9 -- Copyright (C) 2004-2013, Free Software Foundation, Inc. --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. --
18 -- As a special exception under Section 7 of GPL version 3, you are granted --
19 -- additional permissions described in the GCC Runtime Library Exception, --
20 -- version 3.1, as published by the Free Software Foundation. --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
27 -- This unit was originally developed by Matthew J Heaney. --
28 ------------------------------------------------------------------------------
30 package body Ada.Containers.Red_Black_Trees.Generic_Keys is
32 package Ops renames Tree_Operations;
40 function Ceiling (Tree : Tree_Type; Key : Key_Type) return Node_Access is
41 B : Natural renames Tree'Unrestricted_Access.Busy;
42 L : Natural renames Tree'Unrestricted_Access.Lock;
48 -- If the container is empty, return a result immediately, so that we do
49 -- not manipulate the tamper bits unnecessarily.
51 if Tree.Root = null then
55 -- Per AI05-0022, the container implementation is required to detect
56 -- element tampering by a generic actual subprogram.
63 if Is_Greater_Key_Node (Key, X) then
88 function Find (Tree : Tree_Type; Key : Key_Type) return Node_Access is
89 B : Natural renames Tree'Unrestricted_Access.Busy;
90 L : Natural renames Tree'Unrestricted_Access.Lock;
98 -- If the container is empty, return a result immediately, so that we do
99 -- not manipulate the tamper bits unnecessarily.
101 if Tree.Root = null then
105 -- Per AI05-0022, the container implementation is required to detect
106 -- element tampering by a generic actual subprogram.
113 if Is_Greater_Key_Node (Key, X) then
124 elsif Is_Less_Key_Node (Key, Y) then
148 function Floor (Tree : Tree_Type; Key : Key_Type) return Node_Access is
149 B : Natural renames Tree'Unrestricted_Access.Busy;
150 L : Natural renames Tree'Unrestricted_Access.Lock;
156 -- If the container is empty, return a result immediately, so that we do
157 -- not manipulate the tamper bits unnecessarily.
159 if Tree.Root = null then
163 -- Per AI05-0022, the container implementation is required to detect
164 -- element tampering by a generic actual subprogram.
171 if Is_Less_Key_Node (Key, X) then
192 --------------------------------
193 -- Generic_Conditional_Insert --
194 --------------------------------
196 procedure Generic_Conditional_Insert
197 (Tree : in out Tree_Type;
199 Node : out Node_Access;
200 Inserted : out Boolean)
205 -- Per AI05-0022, the container implementation is required to detect
206 -- element tampering by a generic actual subprogram.
208 B : Natural renames Tree.Busy;
209 L : Natural renames Tree.Lock;
214 -- This is a "conditional" insertion, meaning that the insertion request
215 -- can "fail" in the sense that no new node is created. If the Key is
216 -- equivalent to an existing node, then we return the existing node and
217 -- Inserted is set to False. Otherwise, we allocate a new node (via
218 -- Insert_Post) and Inserted is set to True.
220 -- Note that we are testing for equivalence here, not equality. Key must
221 -- be strictly less than its next neighbor, and strictly greater than
222 -- its previous neighbor, in order for the conditional insertion to
225 -- Handle insertion into an empty container as a special case, so that
226 -- we do not manipulate the tamper bits unnecessarily.
228 if Tree.Root = null then
229 Insert_Post (Tree, null, True, Node);
234 -- We search the tree to find the nearest neighbor of Key, which is
235 -- either the smallest node greater than Key (Inserted is True), or the
236 -- largest node less or equivalent to Key (Inserted is False).
247 Inserted := Is_Less_Key_Node (Key, X);
248 X := (if Inserted then Ops.Left (X) else Ops.Right (X));
264 -- Key is less than Y. If Y is the first node in the tree, then there
265 -- are no other nodes that we need to search for, and we insert a new
266 -- node into the tree.
268 if Y = Tree.First then
269 Insert_Post (Tree, Y, True, Node);
273 -- Y is the next nearest-neighbor of Key. We know that Key is not
274 -- equivalent to Y (because Key is strictly less than Y), so we move
275 -- to the previous node, the nearest-neighbor just smaller or
276 -- equivalent to Key.
278 Node := Ops.Previous (Y);
281 -- Y is the previous nearest-neighbor of Key. We know that Key is not
282 -- less than Y, which means either that Key is equivalent to Y, or
288 -- Key is equivalent to or greater than Node. We must resolve which is
289 -- the case, to determine whether the conditional insertion succeeds.
295 Compare := Is_Greater_Key_Node (Key, Node);
310 -- Key is strictly greater than Node, which means that Key is not
311 -- equivalent to Node. In this case, the insertion succeeds, and we
312 -- insert a new node into the tree.
314 Insert_Post (Tree, Y, Inserted, Node);
319 -- Key is equivalent to Node. This is a conditional insertion, so we do
320 -- not insert a new node in this case. We return the existing node and
321 -- report that no insertion has occurred.
324 end Generic_Conditional_Insert;
326 ------------------------------------------
327 -- Generic_Conditional_Insert_With_Hint --
328 ------------------------------------------
330 procedure Generic_Conditional_Insert_With_Hint
331 (Tree : in out Tree_Type;
332 Position : Node_Access;
334 Node : out Node_Access;
335 Inserted : out Boolean)
337 -- Per AI05-0022, the container implementation is required to detect
338 -- element tampering by a generic actual subprogram.
340 B : Natural renames Tree.Busy;
341 L : Natural renames Tree.Lock;
347 -- The purpose of a hint is to avoid a search from the root of
348 -- tree. If we have it hint it means we only need to traverse the
349 -- subtree rooted at the hint to find the nearest neighbor. Note
350 -- that finding the neighbor means merely walking the tree; this
351 -- is not a search and the only comparisons that occur are with
352 -- the hint and its neighbor.
354 -- Handle insertion into an empty container as a special case, so that
355 -- we do not manipulate the tamper bits unnecessarily.
357 if Tree.Root = null then
358 Insert_Post (Tree, null, True, Node);
363 -- If Position is null, this is interpreted to mean that Key is large
364 -- relative to the nodes in the tree. If Key is greater than the last
365 -- node in the tree, then we're done; otherwise the hint was "wrong" and
368 if Position = null then -- largest
373 Compare := Is_Greater_Key_Node (Key, Tree.Last);
387 Insert_Post (Tree, Tree.Last, False, Node);
390 Conditional_Insert_Sans_Hint (Tree, Key, Node, Inserted);
396 pragma Assert (Tree.Length > 0);
398 -- A hint can either name the node that immediately follows Key,
399 -- or immediately precedes Key. We first test whether Key is
400 -- less than the hint, and if so we compare Key to the node that
401 -- precedes the hint. If Key is both less than the hint and
402 -- greater than the hint's preceding neighbor, then we're done;
403 -- otherwise we must search.
405 -- Note also that a hint can either be an anterior node or a leaf
406 -- node. A new node is always inserted at the bottom of the tree
407 -- (at least prior to rebalancing), becoming the new left or
408 -- right child of leaf node (which prior to the insertion must
409 -- necessarily be null, since this is a leaf). If the hint names
410 -- an anterior node then its neighbor must be a leaf, and so
411 -- (here) we insert after the neighbor. If the hint names a leaf
412 -- then its neighbor must be anterior and so we insert before the
419 Compare := Is_Less_Key_Node (Key, Position);
433 Test := Ops.Previous (Position); -- "before"
435 if Test = null then -- new first node
436 Insert_Post (Tree, Tree.First, True, Node);
446 Compare := Is_Greater_Key_Node (Key, Test);
460 if Ops.Right (Test) = null then
461 Insert_Post (Tree, Test, False, Node);
463 Insert_Post (Tree, Position, True, Node);
469 Conditional_Insert_Sans_Hint (Tree, Key, Node, Inserted);
475 -- We know that Key isn't less than the hint so we try again, this time
476 -- to see if it's greater than the hint. If so we compare Key to the
477 -- node that follows the hint. If Key is both greater than the hint and
478 -- less than the hint's next neighbor, then we're done; otherwise we
485 Compare := Is_Greater_Key_Node (Key, Position);
499 Test := Ops.Next (Position); -- "after"
501 if Test = null then -- new last node
502 Insert_Post (Tree, Tree.Last, False, Node);
512 Compare := Is_Less_Key_Node (Key, Test);
526 if Ops.Right (Position) = null then
527 Insert_Post (Tree, Position, False, Node);
529 Insert_Post (Tree, Test, True, Node);
535 Conditional_Insert_Sans_Hint (Tree, Key, Node, Inserted);
541 -- We know that Key is neither less than the hint nor greater than the
542 -- hint, and that's the definition of equivalence. There's nothing else
543 -- we need to do, since a search would just reach the same conclusion.
547 end Generic_Conditional_Insert_With_Hint;
549 -------------------------
550 -- Generic_Insert_Post --
551 -------------------------
553 procedure Generic_Insert_Post
554 (Tree : in out Tree_Type;
560 if Tree.Length = Count_Type'Last then
561 raise Constraint_Error with "too many elements";
564 if Tree.Busy > 0 then
565 raise Program_Error with
566 "attempt to tamper with cursors (container is busy)";
570 pragma Assert (Z /= null);
571 pragma Assert (Ops.Color (Z) = Red);
574 pragma Assert (Tree.Length = 0);
575 pragma Assert (Tree.Root = null);
576 pragma Assert (Tree.First = null);
577 pragma Assert (Tree.Last = null);
584 pragma Assert (Ops.Left (Y) = null);
588 if Y = Tree.First then
593 pragma Assert (Ops.Right (Y) = null);
595 Ops.Set_Right (Y, Z);
597 if Y = Tree.Last then
602 Ops.Set_Parent (Z, Y);
603 Ops.Rebalance_For_Insert (Tree, Z);
604 Tree.Length := Tree.Length + 1;
605 end Generic_Insert_Post;
607 -----------------------
608 -- Generic_Iteration --
609 -----------------------
611 procedure Generic_Iteration
615 procedure Iterate (Node : Node_Access);
621 procedure Iterate (Node : Node_Access) is
626 if Is_Less_Key_Node (Key, N) then
628 elsif Is_Greater_Key_Node (Key, N) then
631 Iterate (Ops.Left (N));
638 -- Start of processing for Generic_Iteration
642 end Generic_Iteration;
644 -------------------------------
645 -- Generic_Reverse_Iteration --
646 -------------------------------
648 procedure Generic_Reverse_Iteration
652 procedure Iterate (Node : Node_Access);
658 procedure Iterate (Node : Node_Access) is
663 if Is_Less_Key_Node (Key, N) then
665 elsif Is_Greater_Key_Node (Key, N) then
668 Iterate (Ops.Right (N));
675 -- Start of processing for Generic_Reverse_Iteration
679 end Generic_Reverse_Iteration;
681 ----------------------------------
682 -- Generic_Unconditional_Insert --
683 ----------------------------------
685 procedure Generic_Unconditional_Insert
686 (Tree : in out Tree_Type;
688 Node : out Node_Access)
702 Before := Is_Less_Key_Node (Key, X);
703 X := (if Before then Ops.Left (X) else Ops.Right (X));
706 Insert_Post (Tree, Y, Before, Node);
707 end Generic_Unconditional_Insert;
709 --------------------------------------------
710 -- Generic_Unconditional_Insert_With_Hint --
711 --------------------------------------------
713 procedure Generic_Unconditional_Insert_With_Hint
714 (Tree : in out Tree_Type;
717 Node : out Node_Access)
720 -- There are fewer constraints for an unconditional insertion
721 -- than for a conditional insertion, since we allow duplicate
722 -- keys. So instead of having to check (say) whether Key is
723 -- (strictly) greater than the hint's previous neighbor, here we
724 -- allow Key to be equal to or greater than the previous node.
726 -- There is the issue of what to do if Key is equivalent to the
727 -- hint. Does the new node get inserted before or after the hint?
728 -- We decide that it gets inserted after the hint, reasoning that
729 -- this is consistent with behavior for non-hint insertion, which
730 -- inserts a new node after existing nodes with equivalent keys.
732 -- First we check whether the hint is null, which is interpreted
733 -- to mean that Key is large relative to existing nodes.
734 -- Following our rule above, if Key is equal to or greater than
735 -- the last node, then we insert the new node immediately after
736 -- last. (We don't have an operation for testing whether a key is
737 -- "equal to or greater than" a node, so we must say instead "not
738 -- less than", which is equivalent.)
740 if Hint = null then -- largest
741 if Tree.Last = null then
742 Insert_Post (Tree, null, False, Node);
743 elsif Is_Less_Key_Node (Key, Tree.Last) then
744 Unconditional_Insert_Sans_Hint (Tree, Key, Node);
746 Insert_Post (Tree, Tree.Last, False, Node);
752 pragma Assert (Tree.Length > 0);
754 -- We decide here whether to insert the new node prior to the
755 -- hint. Key could be equivalent to the hint, so in theory we
756 -- could write the following test as "not greater than" (same as
757 -- "less than or equal to"). If Key were equivalent to the hint,
758 -- that would mean that the new node gets inserted before an
759 -- equivalent node. That wouldn't break any container invariants,
760 -- but our rule above says that new nodes always get inserted
761 -- after equivalent nodes. So here we test whether Key is both
762 -- less than the hint and equal to or greater than the hint's
763 -- previous neighbor, and if so insert it before the hint.
765 if Is_Less_Key_Node (Key, Hint) then
767 Before : constant Node_Access := Ops.Previous (Hint);
769 if Before = null then
770 Insert_Post (Tree, Hint, True, Node);
771 elsif Is_Less_Key_Node (Key, Before) then
772 Unconditional_Insert_Sans_Hint (Tree, Key, Node);
773 elsif Ops.Right (Before) = null then
774 Insert_Post (Tree, Before, False, Node);
776 Insert_Post (Tree, Hint, True, Node);
783 -- We know that Key isn't less than the hint, so it must be equal
784 -- or greater. So we just test whether Key is less than or equal
785 -- to (same as "not greater than") the hint's next neighbor, and
786 -- if so insert it after the hint.
789 After : constant Node_Access := Ops.Next (Hint);
792 Insert_Post (Tree, Hint, False, Node);
793 elsif Is_Greater_Key_Node (Key, After) then
794 Unconditional_Insert_Sans_Hint (Tree, Key, Node);
795 elsif Ops.Right (Hint) = null then
796 Insert_Post (Tree, Hint, False, Node);
798 Insert_Post (Tree, After, True, Node);
801 end Generic_Unconditional_Insert_With_Hint;
809 Key : Key_Type) return Node_Access
817 if Is_Less_Key_Node (Key, X) then
828 end Ada.Containers.Red_Black_Trees.Generic_Keys;