File : bc-containers.ads
-- Copyright (C) 1994-1999 Grady Booch, David Weller, Steve Doiel
-- and Simon Wright.
-- All Rights Reserved.
--
-- This program is free software; you can redistribute it
-- and/or modify it under the terms of the Ada Community
-- License which comes with this Library.
--
-- This program is distributed in the hope that it will be
-- useful, but WITHOUT ANY WARRANTY; without even the implied
-- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
-- PURPOSE. See the Ada Community License for more details.
-- You should have received a copy of the Ada Community
-- License with this library, in the file named "Ada Community
-- License" or "ACL". If not, contact the author of this library
-- for a copy.
--
-- $Id: bc-containers.ads,v 1.7.2.3 1999/12/31 15:16:22 simon Exp $
with Ada.Finalization;
with BC.Smart;
generic
type Item is private;
with function "=" (L, R : Item) return Boolean is <>;
package BC.Containers is
pragma Elaborate_Body;
-- This package specifies the common protocol of all Container classes.
-- This common protocol consists of Iterators.
type Container is abstract tagged private;
-- Active iteration
type Iterator is private;
function New_Iterator (For_The_Container : Container) return Iterator
is abstract;
-- Return a reset Iterator bound to the specific Container.
procedure Reset (It : in out Iterator);
-- Reset the Iterator to the beginning.
procedure Next (It : in out Iterator);
-- Advance the Iterator to the next Item in the Container.
function Is_Done (It : Iterator) return Boolean;
-- Return True if there are no more Items in the Container.
function Current_Item (It : Iterator) return Item;
-- Return a copy of the current Item.
generic
with procedure Apply (Elem : in out Item);
In_The_Iterator : Iterator;
procedure Access_Current_Item;
-- Call Apply for the Iterator's current Item.
procedure Delete_Item_At (It : Iterator);
-- Remove the current item.
-- Passive iteration
generic
with procedure Apply (Elem : in Item; OK : out Boolean);
procedure Visit (Using : in out Iterator);
-- Call Apply with a copy of each Item in the Container to which the
-- iterator Using is bound. The iteration will terminate early if Apply
-- sets OK to False.
generic
type Param_Type is private;
with procedure Apply (Elem : in Item;
Param : in Param_Type;
OK : out Boolean);
procedure Visit_With_In_Param (Using : in out Iterator;
Param : in Param_Type);
-- Call Apply with a Parameter for each Item in the Container to which the
-- iterator Using is bound. The iteration will terminate early if Apply
-- sets OK to False.
generic
type Param_Type is private;
with procedure Apply (Elem : in Item;
Param : in out Param_Type;
OK : out Boolean);
procedure Visit_With_In_Out_Param (Using : in out Iterator;
Param : in out Param_Type);
-- Call Apply with a Parameter for each Item in the Container to which the
-- iterator Using is bound. The iteration will terminate early if Apply
-- sets OK to False.
generic
with procedure Apply (Elem : in out Item; OK : out Boolean);
procedure Modify (Using : in out Iterator);
-- Call Apply with a copy of each Item in the Container to which the
-- iterator Using is bound. The iteration will terminate early if Apply
-- sets OK to False.
generic
type Param_Type is private;
with procedure Apply (Elem : in out Item;
Param : in Param_Type;
OK : out Boolean);
procedure Modify_With_In_Param (Using : in out Iterator;
Param : in Param_Type);
-- Call Apply with a Parameter each Item in the Container to which the
-- iterator Using is bound. The iteration will terminate early if Apply
-- sets OK to False.
generic
type Param_Type is private;
with procedure Apply (Elem : in out Item;
Param : in out Param_Type;
OK : out Boolean);
procedure Modify_With_In_Out_Param (Using : in out Iterator;
Param : in out Param_Type);
-- Call Apply with a copy of each Item in the Container to which the
-- iterator Using is bound. The iteration will terminate early if Apply
-- sets OK to False.
private
-- We need access to Items; but we must make sure that no actual
-- allocations occur using this type.
type Item_Ptr is access all Item;
for Item_Ptr'Storage_Size use 0;
type Container is abstract new Ada.Finalization.Controlled with null record;
-- Private primitive operations.
-- These should ideally be abstract; instead, we provide implementations,
-- but they raise Should_Have_Been_Overridden.
function Cardinality (C : Container) return Natural;
function Item_At (C : Container; Index : Positive) return Item_Ptr;
procedure Purge (C : in out Container);
-- Actual_Iterators are strongly dependent on the concrete Container
-- implementation. The externally-visible Iterator is implemented as
-- a (smart) pointer to the specific Container's Actual_Iterator.
--
-- All the primitive subprograms of Iterator are implemented in terms
-- of matching subprograms of Actual_Iterator.
type Actual_Iterator (For_The_Container : access Container'Class)
is abstract new Ada.Finalization.Limited_Controlled with null record;
type Iterator_P is access Actual_Iterator'Class;
procedure Reset (It : in out Actual_Iterator) is abstract;
procedure Next (It : in out Actual_Iterator) is abstract;
function Is_Done (It : Actual_Iterator) return Boolean is abstract;
function Current_Item (It : Actual_Iterator) return Item is abstract;
function Current_Item (It : Actual_Iterator) return Item_Ptr is abstract;
procedure Delete_Item_At (It : Actual_Iterator) is abstract;
package SP is new BC.Smart (T => Actual_Iterator'Class, P => Iterator_P);
type Iterator is new SP.Pointer;
end BC.Containers;