API Reference

type Handle (Max_Size : Positive)

  
   type Handle (Max_Size : Positive) is limited private;  

Initial value: empty

A position is initially invalid until assigned a value by First, Last, or Off_List.

Other positions accessible via Next and Prev.

& Invalid_Position : exception; -- Raised if a position is invalid.

procedure Assign

   procedure Assign (To : out Handle; From : in Handle);   

Makes To a copy of From.

Raises Too_Short if To.Max_Size < Length (From). Nothing is changed if Too_Short is raised.

Time: O(N).

procedure Clear

   procedure Clear (List : in out Handle);   

Makes List empty; all lists are initially empty.

Time: O(N).

Postcondition: Is_Empty (List).

Operations to obtain valid positions for lists:

function First

   function First (List : Handle) return Position;   

function Last

   function Last (List : Handle) return Position;   

function Off_List

   function Off_List (List : Handle) return Position;   

Time: O(1)

Off_List (List) is the valid Position for List that is returned by Prev (First (List), List) and by Next (Last (List), List). First and Last return Off_List (List) if Is_Empty (List). Operations to obtain valid positions from valid positions:

function Next

   function Next (Pos : Position; List : Handle) return Position;   

function Prev

   function Prev (Pos : Position; List : Handle) return Position;   

raise Invalid_Position.

Next and Prev raise Invalid_Position if Pos is invalid. Next (Last (L), L) = Prev (First (L), L) = Off_List (L). Next (Off_List (L), L) = First (L).

Prev (Off_List (L), L) = Last (L).

Time: O(1).

Operations to manipulate lists:

procedure Insert

   procedure Insert (Into    : in out Handle;   
                     Item    : in     Element;  
                     Before  : in     Position;  
                     New_Pos :    out Position);  

Inserts Item before Before.

Returns the position of Item in Into in New_Pos.

Before => Off_List (Into) is the same as Append with After => Last (Into). Raises Full if Into is full.

Raises Invalid_Position if Pos is invalid.

Nothing is changed if Full or Invalid_Position are raised.

Time: O(1).

Precondition: not Is_Full (Into) raise Full if violated. Postcondition: not Is_Empty (Into).

procedure Append

   procedure Append (Into    : in out Handle;   
                     Item    : in     Element;  
                     After   : in     Position;  
                     New_Pos :    out Position);  

Appends Item after After.

Returns the position of Item in Into in New_Pos. After => Off_List (Into) is the same as Insert with Before => First (Into).

Raises Full if Into is full.

Raises Invalid_Position if Pos is invalid.

Nothing is changed if Full or Invalid_Position are raised.

Time: O(1).

Precondition: not Is_Full (Into) raise Full if violated. Postcondition: not Is_Empty (Into).

procedure Delete

   procedure Delete (From : in out Handle; Pos : in out Position);   

raise Invalid_Position.

Deletes the item at Pos.

Pos is made invalid.

Raises Empty if From is empty.

Raises Invalid_Position if Pos is invalid or Off_List (From). Nothing is changed if Invalid_Position is raised.

Time: O(1).

Precondition: not Is_Empty (From) raise Empty if violated. Postcondition: not Is_Full (From).

function Get

   function Get (From : Handle; Pos : Position) return Element;   

raise Invalid_Position.

Returns the item at Pos.

Raises Invalid_Position if Pos is invalid or Off_List (From). Raises Empty if From is empty.

procedure Put

   procedure Put (Into : in out Handle; Pos : in Position; Item : in Element);   

raise Invalid_Position.

Makes the Element stored at Pos be Item.

Raises Invalid_Position if Pos is invalid or Off_List (Into). Nothing is changed if Invalid_Position is raised.

Time: O(1).

function Is_Empty

   function Is_Empty (List : Handle) return Boolean;   

Returns True if List is empty [Length (List) = 0]; returns False otherwise.

function Is_Full

   function Is_Full (List : Handle) return Boolean;   

Returns True if List is full [Length (List) = List.Max_Size]; returns False otherwise.

function Length

   function Length (List : Handle) return Natural;   

Returns a count of the number of items in List.

type Context_Data (<>) , with procedure Action , procedure Iterate

   generic -- Iterate   
      type Context_Data (<>) is limited private;  
  
      with procedure Action (Item     : in out Element;  
                             Context  : in out Context_Data;  
                             Pos      : in     Position;  
                             Continue :    out Boolean);  
   procedure Iterate (Over : in out Handle; Context : in out Context_Data);  

Calls Action with each Element in Over, & its Position, in turn. Returns immediately if Continue is set to False (remainder of Over is not processed).