------------------------------------------------------------------------------ | |

-- -- | |

-- GNAT LIBRARY COMPONENTS -- | |

-- -- | |

-- ADA.CONTAINERS.RED_BLACK_TREES.GENERIC_KEYS -- | |

-- -- | |

-- B o d y -- | |

-- -- | |

-- Copyright (C) 2004-2022, Free Software Foundation, Inc. -- | |

-- -- | |

-- GNAT is free software; you can redistribute it and/or modify it under -- | |

-- terms of the GNU General Public License as published by the Free Soft- -- | |

-- ware Foundation; either version 3, or (at your option) any later ver- -- | |

-- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- | |

-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- | |

-- or FITNESS FOR A PARTICULAR PURPOSE. -- | |

-- -- | |

-- As a special exception under Section 7 of GPL version 3, you are granted -- | |

-- additional permissions described in the GCC Runtime Library Exception, -- | |

-- version 3.1, as published by the Free Software Foundation. -- | |

-- -- | |

-- You should have received a copy of the GNU General Public License and -- | |

-- a copy of the GCC Runtime Library Exception along with this program; -- | |

-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- | |

-- <http://www.gnu.org/licenses/>. -- | |

-- -- | |

-- This unit was originally developed by Matthew J Heaney. -- | |

------------------------------------------------------------------------------ | |

package body Ada.Containers.Red_Black_Trees.Generic_Keys is | |

pragma Warnings (Off, "variable ""Busy*"" is not referenced"); | |

pragma Warnings (Off, "variable ""Lock*"" is not referenced"); | |

-- See comment in Ada.Containers.Helpers | |

package Ops renames Tree_Operations; | |

------------- | |

-- Ceiling -- | |

------------- | |

-- AKA Lower_Bound | |

function Ceiling (Tree : Tree_Type; Key : Key_Type) return Node_Access is | |

-- Per AI05-0022, the container implementation is required to detect | |

-- element tampering by a generic actual subprogram. | |

Lock : With_Lock (Tree.TC'Unrestricted_Access); | |

Y : Node_Access; | |

X : Node_Access; | |

begin | |

-- If the container is empty, return a result immediately, so that we do | |

-- not manipulate the tamper bits unnecessarily. | |

if Tree.Root = null then | |

return null; | |

end if; | |

X := Tree.Root; | |

while X /= null loop | |

if Is_Greater_Key_Node (Key, X) then | |

X := Ops.Right (X); | |

else | |

Y := X; | |

X := Ops.Left (X); | |

end if; | |

end loop; | |

return Y; | |

end Ceiling; | |

---------- | |

-- Find -- | |

---------- | |

function Find (Tree : Tree_Type; Key : Key_Type) return Node_Access is | |

-- Per AI05-0022, the container implementation is required to detect | |

-- element tampering by a generic actual subprogram. | |

Lock : With_Lock (Tree.TC'Unrestricted_Access); | |

Y : Node_Access; | |

X : Node_Access; | |

begin | |

-- If the container is empty, return a result immediately, so that we do | |

-- not manipulate the tamper bits unnecessarily. | |

if Tree.Root = null then | |

return null; | |

end if; | |

X := Tree.Root; | |

while X /= null loop | |

if Is_Greater_Key_Node (Key, X) then | |

X := Ops.Right (X); | |

else | |

Y := X; | |

X := Ops.Left (X); | |

end if; | |

end loop; | |

if Y = null or else Is_Less_Key_Node (Key, Y) then | |

return null; | |

else | |

return Y; | |

end if; | |

end Find; | |

----------- | |

-- Floor -- | |

----------- | |

function Floor (Tree : Tree_Type; Key : Key_Type) return Node_Access is | |

-- Per AI05-0022, the container implementation is required to detect | |

-- element tampering by a generic actual subprogram. | |

Lock : With_Lock (Tree.TC'Unrestricted_Access); | |

Y : Node_Access; | |

X : Node_Access; | |

begin | |

-- If the container is empty, return a result immediately, so that we do | |

-- not manipulate the tamper bits unnecessarily. | |

if Tree.Root = null then | |

return null; | |

end if; | |

X := Tree.Root; | |

while X /= null loop | |

if Is_Less_Key_Node (Key, X) then | |

X := Ops.Left (X); | |

else | |

Y := X; | |

X := Ops.Right (X); | |

end if; | |

end loop; | |

return Y; | |

end Floor; | |

-------------------------------- | |

-- Generic_Conditional_Insert -- | |

-------------------------------- | |

procedure Generic_Conditional_Insert | |

(Tree : in out Tree_Type; | |

Key : Key_Type; | |

Node : out Node_Access; | |

Inserted : out Boolean) | |

is | |

X : Node_Access; | |

Y : Node_Access; | |

Compare : Boolean; | |

begin | |

-- This is a "conditional" insertion, meaning that the insertion request | |

-- can "fail" in the sense that no new node is created. If the Key is | |

-- equivalent to an existing node, then we return the existing node and | |

-- Inserted is set to False. Otherwise, we allocate a new node (via | |

-- Insert_Post) and Inserted is set to True. | |

-- Note that we are testing for equivalence here, not equality. Key must | |

-- be strictly less than its next neighbor, and strictly greater than | |

-- its previous neighbor, in order for the conditional insertion to | |

-- succeed. | |

-- Handle insertion into an empty container as a special case, so that | |

-- we do not manipulate the tamper bits unnecessarily. | |

if Tree.Root = null then | |

Insert_Post (Tree, null, True, Node); | |

Inserted := True; | |

return; | |

end if; | |

-- We search the tree to find the nearest neighbor of Key, which is | |

-- either the smallest node greater than Key (Inserted is True), or the | |

-- largest node less or equivalent to Key (Inserted is False). | |

declare | |

Lock : With_Lock (Tree.TC'Unrestricted_Access); | |

begin | |

X := Tree.Root; | |

Y := null; | |

Inserted := True; | |

while X /= null loop | |

Y := X; | |

Inserted := Is_Less_Key_Node (Key, X); | |

X := (if Inserted then Ops.Left (X) else Ops.Right (X)); | |

end loop; | |

end; | |

if Inserted then | |

-- Key is less than Y. If Y is the first node in the tree, then there | |

-- are no other nodes that we need to search for, and we insert a new | |

-- node into the tree. | |

if Y = Tree.First then | |

Insert_Post (Tree, Y, True, Node); | |

return; | |

end if; | |

-- Y is the next nearest-neighbor of Key. We know that Key is not | |

-- equivalent to Y (because Key is strictly less than Y), so we move | |

-- to the previous node, the nearest-neighbor just smaller or | |

-- equivalent to Key. | |

Node := Ops.Previous (Y); | |

else | |

-- Y is the previous nearest-neighbor of Key. We know that Key is not | |

-- less than Y, which means either that Key is equivalent to Y, or | |

-- greater than Y. | |

Node := Y; | |

end if; | |

-- Key is equivalent to or greater than Node. We must resolve which is | |

-- the case, to determine whether the conditional insertion succeeds. | |

declare | |

Lock : With_Lock (Tree.TC'Unrestricted_Access); | |

begin | |

Compare := Is_Greater_Key_Node (Key, Node); | |

end; | |

if Compare then | |

-- Key is strictly greater than Node, which means that Key is not | |

-- equivalent to Node. In this case, the insertion succeeds, and we | |

-- insert a new node into the tree. | |

Insert_Post (Tree, Y, Inserted, Node); | |

Inserted := True; | |

return; | |

end if; | |

-- Key is equivalent to Node. This is a conditional insertion, so we do | |

-- not insert a new node in this case. We return the existing node and | |

-- report that no insertion has occurred. | |

Inserted := False; | |

end Generic_Conditional_Insert; | |

------------------------------------------ | |

-- Generic_Conditional_Insert_With_Hint -- | |

------------------------------------------ | |

procedure Generic_Conditional_Insert_With_Hint | |

(Tree : in out Tree_Type; | |

Position : Node_Access; | |

Key : Key_Type; | |

Node : out Node_Access; | |

Inserted : out Boolean) | |

is | |

Test : Node_Access; | |

Compare : Boolean; | |

begin | |

-- The purpose of a hint is to avoid a search from the root of | |

-- tree. If we have it hint it means we only need to traverse the | |

-- subtree rooted at the hint to find the nearest neighbor. Note | |

-- that finding the neighbor means merely walking the tree; this | |

-- is not a search and the only comparisons that occur are with | |

-- the hint and its neighbor. | |

-- Handle insertion into an empty container as a special case, so that | |

-- we do not manipulate the tamper bits unnecessarily. | |

if Tree.Root = null then | |

Insert_Post (Tree, null, True, Node); | |

Inserted := True; | |

return; | |

end if; | |

-- If Position is null, this is interpreted to mean that Key is large | |

-- relative to the nodes in the tree. If Key is greater than the last | |

-- node in the tree, then we're done; otherwise the hint was "wrong" and | |

-- we must search. | |

if Position = null then -- largest | |

declare | |

Lock : With_Lock (Tree.TC'Unrestricted_Access); | |

begin | |

Compare := Is_Greater_Key_Node (Key, Tree.Last); | |

end; | |

if Compare then | |

Insert_Post (Tree, Tree.Last, False, Node); | |

Inserted := True; | |

else | |

Conditional_Insert_Sans_Hint (Tree, Key, Node, Inserted); | |

end if; | |

return; | |

end if; | |

pragma Assert (Tree.Length > 0); | |

-- A hint can either name the node that immediately follows Key, | |

-- or immediately precedes Key. We first test whether Key is | |

-- less than the hint, and if so we compare Key to the node that | |

-- precedes the hint. If Key is both less than the hint and | |

-- greater than the hint's preceding neighbor, then we're done; | |

-- otherwise we must search. | |

-- Note also that a hint can either be an anterior node or a leaf | |

-- node. A new node is always inserted at the bottom of the tree | |

-- (at least prior to rebalancing), becoming the new left or | |

-- right child of leaf node (which prior to the insertion must | |

-- necessarily be null, since this is a leaf). If the hint names | |

-- an anterior node then its neighbor must be a leaf, and so | |

-- (here) we insert after the neighbor. If the hint names a leaf | |

-- then its neighbor must be anterior and so we insert before the | |

-- hint. | |

declare | |

Lock : With_Lock (Tree.TC'Unrestricted_Access); | |

begin | |

Compare := Is_Less_Key_Node (Key, Position); | |

end; | |

if Compare then | |

Test := Ops.Previous (Position); -- "before" | |

if Test = null then -- new first node | |

Insert_Post (Tree, Tree.First, True, Node); | |

Inserted := True; | |

return; | |

end if; | |

declare | |

Lock : With_Lock (Tree.TC'Unrestricted_Access); | |

begin | |

Compare := Is_Greater_Key_Node (Key, Test); | |

end; | |

if Compare then | |

if Ops.Right (Test) = null then | |

Insert_Post (Tree, Test, False, Node); | |

else | |

Insert_Post (Tree, Position, True, Node); | |

end if; | |

Inserted := True; | |

else | |

Conditional_Insert_Sans_Hint (Tree, Key, Node, Inserted); | |

end if; | |

return; | |

end if; | |

-- We know that Key isn't less than the hint so we try again, this time | |

-- to see if it's greater than the hint. If so we compare Key to the | |

-- node that follows the hint. If Key is both greater than the hint and | |

-- less than the hint's next neighbor, then we're done; otherwise we | |

-- must search. | |

declare | |

Lock : With_Lock (Tree.TC'Unrestricted_Access); | |

begin | |

Compare := Is_Greater_Key_Node (Key, Position); | |

end; | |

if Compare then | |

Test := Ops.Next (Position); -- "after" | |

if Test = null then -- new last node | |

Insert_Post (Tree, Tree.Last, False, Node); | |

Inserted := True; | |

return; | |

end if; | |

declare | |

Lock : With_Lock (Tree.TC'Unrestricted_Access); | |

begin | |

Compare := Is_Less_Key_Node (Key, Test); | |

end; | |

if Compare then | |

if Ops.Right (Position) = null then | |

Insert_Post (Tree, Position, False, Node); | |

else | |

Insert_Post (Tree, Test, True, Node); | |

end if; | |

Inserted := True; | |

else | |

Conditional_Insert_Sans_Hint (Tree, Key, Node, Inserted); | |

end if; | |

return; | |

end if; | |

-- We know that Key is neither less than the hint nor greater than the | |

-- hint, and that's the definition of equivalence. There's nothing else | |

-- we need to do, since a search would just reach the same conclusion. | |

Node := Position; | |

Inserted := False; | |

end Generic_Conditional_Insert_With_Hint; | |

------------------------- | |

-- Generic_Insert_Post -- | |

------------------------- | |

procedure Generic_Insert_Post | |

(Tree : in out Tree_Type; | |

Y : Node_Access; | |

Before : Boolean; | |

Z : out Node_Access) | |

is | |

begin | |

TC_Check (Tree.TC); | |

if Checks and then Tree.Length = Count_Type'Last then | |

raise Constraint_Error with "too many elements"; | |

end if; | |

Z := New_Node; | |

pragma Assert (Z /= null); | |

pragma Assert (Ops.Color (Z) = Red); | |

if Y = null then | |

pragma Assert (Tree.Length = 0); | |

pragma Assert (Tree.Root = null); | |

pragma Assert (Tree.First = null); | |

pragma Assert (Tree.Last = null); | |

Tree.Root := Z; | |

Tree.First := Z; | |

Tree.Last := Z; | |

elsif Before then | |

pragma Assert (Ops.Left (Y) = null); | |

Ops.Set_Left (Y, Z); | |

if Y = Tree.First then | |

Tree.First := Z; | |

end if; | |

else | |

pragma Assert (Ops.Right (Y) = null); | |

Ops.Set_Right (Y, Z); | |

if Y = Tree.Last then | |

Tree.Last := Z; | |

end if; | |

end if; | |

Ops.Set_Parent (Z, Y); | |

Ops.Rebalance_For_Insert (Tree, Z); | |

Tree.Length := Tree.Length + 1; | |

end Generic_Insert_Post; | |

----------------------- | |

-- Generic_Iteration -- | |

----------------------- | |

procedure Generic_Iteration | |

(Tree : Tree_Type; | |

Key : Key_Type) | |

is | |

procedure Iterate (Node : Node_Access); | |

------------- | |

-- Iterate -- | |

------------- | |

procedure Iterate (Node : Node_Access) is | |

N : Node_Access; | |

begin | |

N := Node; | |

while N /= null loop | |

if Is_Less_Key_Node (Key, N) then | |

N := Ops.Left (N); | |

elsif Is_Greater_Key_Node (Key, N) then | |

N := Ops.Right (N); | |

else | |

Iterate (Ops.Left (N)); | |

Process (N); | |

N := Ops.Right (N); | |

end if; | |

end loop; | |

end Iterate; | |

-- Start of processing for Generic_Iteration | |

begin | |

Iterate (Tree.Root); | |

end Generic_Iteration; | |

------------------------------- | |

-- Generic_Reverse_Iteration -- | |

------------------------------- | |

procedure Generic_Reverse_Iteration | |

(Tree : Tree_Type; | |

Key : Key_Type) | |

is | |

procedure Iterate (Node : Node_Access); | |

------------- | |

-- Iterate -- | |

------------- | |

procedure Iterate (Node : Node_Access) is | |

N : Node_Access; | |

begin | |

N := Node; | |

while N /= null loop | |

if Is_Less_Key_Node (Key, N) then | |

N := Ops.Left (N); | |

elsif Is_Greater_Key_Node (Key, N) then | |

N := Ops.Right (N); | |

else | |

Iterate (Ops.Right (N)); | |

Process (N); | |

N := Ops.Left (N); | |

end if; | |

end loop; | |

end Iterate; | |

-- Start of processing for Generic_Reverse_Iteration | |

begin | |

Iterate (Tree.Root); | |

end Generic_Reverse_Iteration; | |

---------------------------------- | |

-- Generic_Unconditional_Insert -- | |

---------------------------------- | |

procedure Generic_Unconditional_Insert | |

(Tree : in out Tree_Type; | |

Key : Key_Type; | |

Node : out Node_Access) | |

is | |

Y : Node_Access; | |

X : Node_Access; | |

Before : Boolean; | |

begin | |

Y := null; | |

Before := False; | |

X := Tree.Root; | |

while X /= null loop | |

Y := X; | |

Before := Is_Less_Key_Node (Key, X); | |

X := (if Before then Ops.Left (X) else Ops.Right (X)); | |

end loop; | |

Insert_Post (Tree, Y, Before, Node); | |

end Generic_Unconditional_Insert; | |

-------------------------------------------- | |

-- Generic_Unconditional_Insert_With_Hint -- | |

-------------------------------------------- | |

procedure Generic_Unconditional_Insert_With_Hint | |

(Tree : in out Tree_Type; | |

Hint : Node_Access; | |

Key : Key_Type; | |

Node : out Node_Access) | |

is | |

begin | |

-- There are fewer constraints for an unconditional insertion | |

-- than for a conditional insertion, since we allow duplicate | |

-- keys. So instead of having to check (say) whether Key is | |

-- (strictly) greater than the hint's previous neighbor, here we | |

-- allow Key to be equal to or greater than the previous node. | |

-- There is the issue of what to do if Key is equivalent to the | |

-- hint. Does the new node get inserted before or after the hint? | |

-- We decide that it gets inserted after the hint, reasoning that | |

-- this is consistent with behavior for non-hint insertion, which | |

-- inserts a new node after existing nodes with equivalent keys. | |

-- First we check whether the hint is null, which is interpreted | |

-- to mean that Key is large relative to existing nodes. | |

-- Following our rule above, if Key is equal to or greater than | |

-- the last node, then we insert the new node immediately after | |

-- last. (We don't have an operation for testing whether a key is | |

-- "equal to or greater than" a node, so we must say instead "not | |

-- less than", which is equivalent.) | |

if Hint = null then -- largest | |

if Tree.Last = null then | |

Insert_Post (Tree, null, False, Node); | |

elsif Is_Less_Key_Node (Key, Tree.Last) then | |

Unconditional_Insert_Sans_Hint (Tree, Key, Node); | |

else | |

Insert_Post (Tree, Tree.Last, False, Node); | |

end if; | |

return; | |

end if; | |

pragma Assert (Tree.Length > 0); | |

-- We decide here whether to insert the new node prior to the | |

-- hint. Key could be equivalent to the hint, so in theory we | |

-- could write the following test as "not greater than" (same as | |

-- "less than or equal to"). If Key were equivalent to the hint, | |

-- that would mean that the new node gets inserted before an | |

-- equivalent node. That wouldn't break any container invariants, | |

-- but our rule above says that new nodes always get inserted | |

-- after equivalent nodes. So here we test whether Key is both | |

-- less than the hint and equal to or greater than the hint's | |

-- previous neighbor, and if so insert it before the hint. | |

if Is_Less_Key_Node (Key, Hint) then | |

declare | |

Before : constant Node_Access := Ops.Previous (Hint); | |

begin | |

if Before = null then | |

Insert_Post (Tree, Hint, True, Node); | |

elsif Is_Less_Key_Node (Key, Before) then | |

Unconditional_Insert_Sans_Hint (Tree, Key, Node); | |

elsif Ops.Right (Before) = null then | |

Insert_Post (Tree, Before, False, Node); | |

else | |

Insert_Post (Tree, Hint, True, Node); | |

end if; | |

end; | |

return; | |

end if; | |

-- We know that Key isn't less than the hint, so it must be equal | |

-- or greater. So we just test whether Key is less than or equal | |

-- to (same as "not greater than") the hint's next neighbor, and | |

-- if so insert it after the hint. | |

declare | |

After : constant Node_Access := Ops.Next (Hint); | |

begin | |

if After = null then | |

Insert_Post (Tree, Hint, False, Node); | |

elsif Is_Greater_Key_Node (Key, After) then | |

Unconditional_Insert_Sans_Hint (Tree, Key, Node); | |

elsif Ops.Right (Hint) = null then | |

Insert_Post (Tree, Hint, False, Node); | |

else | |

Insert_Post (Tree, After, True, Node); | |

end if; | |

end; | |

end Generic_Unconditional_Insert_With_Hint; | |

----------------- | |

-- Upper_Bound -- | |

----------------- | |

function Upper_Bound | |

(Tree : Tree_Type; | |

Key : Key_Type) return Node_Access | |

is | |

Y : Node_Access; | |

X : Node_Access; | |

begin | |

X := Tree.Root; | |

while X /= null loop | |

if Is_Less_Key_Node (Key, X) then | |

Y := X; | |

X := Ops.Left (X); | |

else | |

X := Ops.Right (X); | |

end if; | |

end loop; | |

return Y; | |

end Upper_Bound; | |

end Ada.Containers.Red_Black_Trees.Generic_Keys; |