2011-11-23 Matthew Heaney <heaney@adacore.com>
+ * a-cdlili.adb, a-cidlli.adb, a-cbdlli.adb (Iterator): Declared
+ Iterator type as limited (First, Last): Cursor return value
+ depends on iterator node value (Iterate): Use start position as
+ iterator node value (Next, Previous): Forward to corresponding
+ cursor-based operation.
+
+2011-11-23 Matthew Heaney <heaney@adacore.com>
+
* a-coorse.ads, a-ciorse.ads, a-cborse.ads (Set_Iterator_Interfaces):
Renamed from Ordered_Set_Iterator_Interfaces.
* a-coorse.adb, a-ciorse.adb, a-cborse.adb (Iterator): Declared
with System; use type System.Address;
package body Ada.Containers.Bounded_Doubly_Linked_Lists is
- type Iterator is new
+
+ type Iterator is limited new
List_Iterator_Interfaces.Reversible_Iterator with record
Container : List_Access;
Node : Count_Type;
function First (Object : Iterator) return Cursor is
begin
- if Object.Container = null then
- return No_Element;
+ -- The value of the iterator object's Node component influences the
+ -- behavior of the First (and Last) selector function.
+
+ -- When the Node component is 0, this means the iterator object was
+ -- constructed without a start expression, in which case the (forward)
+ -- iteration starts from the (logical) beginning of the entire sequence
+ -- of items (corresponding to Container.First, for a forward iterator).
+
+ -- Otherwise, this is iteration over a partial sequence of items. When
+ -- the Node component is positive, the iterator object was constructed
+ -- with a start expression, that specifies the position from which the
+ -- (forward) partial iteration begins.
+
+ if Object.Node = 0 then
+ return Bounded_Doubly_Linked_Lists.First (Object.Container.all);
else
- return (Object.Container, Object.Container.First);
+ return Cursor'(Object.Container, Object.Node);
end if;
end First;
function Iterate
(Container : List)
- return List_Iterator_Interfaces.Reversible_Iterator'class
+ return List_Iterator_Interfaces.Reversible_Iterator'Class
is
begin
- if Container.Length = 0 then
- return Iterator'(null, Count_Type'First);
- else
- return Iterator'(Container'Unrestricted_Access, Container.First);
- end if;
+ -- The value of the Node component influences the behavior of the First
+ -- and Last selector functions of the iterator object. When the Node
+ -- component is 0 (as is the case here), this means the iterator
+ -- object was constructed without a start expression. This is a
+ -- complete iterator, meaning that the iteration starts from the
+ -- (logical) beginning of the sequence of items.
+
+ -- Note: For a forward iterator, Container.First is the beginning, and
+ -- for a reverse iterator, Container.Last is the beginning.
+
+ return Iterator'(Container'Unrestricted_Access, Node => 0);
end Iterate;
function Iterate
Start : Cursor)
return List_Iterator_Interfaces.Reversible_Iterator'class
is
- It : constant Iterator := (Container'Unrestricted_Access, Start.Node);
begin
- return It;
+ -- It was formerly the case that when Start = No_Element, the partial
+ -- iterator was defined to behave the same as for a complete iterator,
+ -- and iterate over the entire sequence of items. However, those
+ -- semantics were unintuitive and arguably error-prone (it is too easy
+ -- to accidentally create an endless loop), and so they were changed,
+ -- per the ARG meeting in Denver on 2011/11. However, there was no
+ -- consensus about what positive meaning this corner case should have,
+ -- and so it was decided to simply raise an exception. This does imply,
+ -- however, that it is not possible to use a partial iterator to specify
+ -- an empty sequence of items.
+
+ if Start = No_Element then
+ raise Constraint_Error with
+ "Start position for iterator equals No_Element";
+ end if;
+
+ if Start.Container /= Container'Unrestricted_Access then
+ raise Program_Error with
+ "Start cursor of Iterate designates wrong list";
+ end if;
+
+ pragma Assert (Vet (Start), "Start cursor of Iterate is bad");
+
+ -- The value of the Node component influences the behavior of the First
+ -- and Last selector functions of the iterator object. When the Node
+ -- component is positive (as is the case here), it means that this
+ -- is a partial iteration, over a subset of the complete sequence of
+ -- items. The iterator object was constructed with a start expression,
+ -- indicating the position from which the iteration begins. Note that
+ -- the start position has the same value irrespective of whether this
+ -- is a forward or reverse iteration.
+
+ return Iterator'(Container'Unrestricted_Access, Node => Start.Node);
end Iterate;
----------
function Last (Object : Iterator) return Cursor is
begin
- if Object.Container = null then
- return No_Element;
+ -- The value of the iterator object's Node component influences the
+ -- behavior of the Last (and First) selector function.
+
+ -- When the Node component is 0, this means the iterator object was
+ -- constructed without a start expression, in which case the (reverse)
+ -- iteration starts from the (logical) beginning of the entire sequence
+ -- (corresponding to Container.Last, for a reverse iterator).
+
+ -- Otherwise, this is iteration over a partial sequence of items. When
+ -- the Node component is positive, the iterator object was constructed
+ -- with a start expression, that specifies the position from which the
+ -- (reverse) partial iteration begins.
+
+ if Object.Node = 0 then
+ return Bounded_Doubly_Linked_Lists.Last (Object.Container.all);
else
- return (Object.Container, Object.Container.Last);
+ return Cursor'(Object.Container, Object.Node);
end if;
end Last;
(Object : Iterator;
Position : Cursor) return Cursor
is
- Nodes : Node_Array renames Position.Container.Nodes;
- Node : constant Count_Type := Nodes (Position.Node).Next;
begin
- if Position.Node = Object.Container.Last then
+ if Position.Container = null then
return No_Element;
- else
- return (Object.Container, Node);
end if;
+
+ if Position.Container /= Object.Container then
+ raise Program_Error with
+ "Position cursor of Next designates wrong list";
+ end if;
+
+ return Next (Position);
end Next;
-------------
(Object : Iterator;
Position : Cursor) return Cursor
is
- Nodes : Node_Array renames Position.Container.Nodes;
- Node : constant Count_Type := Nodes (Position.Node).Prev;
begin
- if Position.Node = 0 then
+ if Position.Container = null then
return No_Element;
- else
- return (Object.Container, Node);
end if;
+
+ if Position.Container /= Object.Container then
+ raise Program_Error with
+ "Position cursor of Previous designates wrong list";
+ end if;
+
+ return Previous (Position);
end Previous;
-------------------
with Ada.Unchecked_Deallocation;
package body Ada.Containers.Doubly_Linked_Lists is
- type Iterator is new
+
+ type Iterator is limited new
List_Iterator_Interfaces.Reversible_Iterator with record
Container : List_Access;
Node : Node_Access;
function First (Object : Iterator) return Cursor is
begin
- if Object.Container = null then
- return No_Element;
+ -- The value of the iterator object's Node component influences the
+ -- behavior of the First (and Last) selector function.
+
+ -- When the Node component is null, this means the iterator object was
+ -- constructed without a start expression, in which case the (forward)
+ -- iteration starts from the (logical) beginning of the entire sequence
+ -- of items (corresponding to Container.First, for a forward iterator).
+
+ -- Otherwise, this is iteration over a partial sequence of items. When
+ -- the Node component is non-null, the iterator object was constructed
+ -- with a start expression, that specifies the position from which the
+ -- (forward) partial iteration begins.
+
+ if Object.Node = null then
+ return Doubly_Linked_Lists.First (Object.Container.all);
else
- return (Object.Container, Object.Container.First);
+ return Cursor'(Object.Container, Object.Node);
end if;
end First;
end Iterate;
function Iterate (Container : List)
- return List_Iterator_Interfaces.Reversible_Iterator'class
+ return List_Iterator_Interfaces.Reversible_Iterator'Class
is
begin
- if Container.Length = 0 then
- return Iterator'(null, null);
- else
- return Iterator'(Container'Unchecked_Access, Container.First);
- end if;
+ -- The value of the Node component influences the behavior of the First
+ -- and Last selector functions of the iterator object. When the Node
+ -- component is null (as is the case here), this means the iterator
+ -- object was constructed without a start expression. This is a
+ -- complete iterator, meaning that the iteration starts from the
+ -- (logical) beginning of the sequence of items.
+
+ -- Note: For a forward iterator, Container.First is the beginning, and
+ -- for a reverse iterator, Container.Last is the beginning.
+
+ return Iterator'(Container'Unrestricted_Access, Node => null);
end Iterate;
function Iterate (Container : List; Start : Cursor)
- return List_Iterator_Interfaces.Reversible_Iterator'class
+ return List_Iterator_Interfaces.Reversible_Iterator'Class
is
- It : constant Iterator := (Container'Unchecked_Access, Start.Node);
begin
- return It;
+ -- It was formerly the case that when Start = No_Element, the partial
+ -- iterator was defined to behave the same as for a complete iterator,
+ -- and iterate over the entire sequence of items. However, those
+ -- semantics were unintuitive and arguably error-prone (it is too easy
+ -- to accidentally create an endless loop), and so they were changed,
+ -- per the ARG meeting in Denver on 2011/11. However, there was no
+ -- consensus about what positive meaning this corner case should have,
+ -- and so it was decided to simply raise an exception. This does imply,
+ -- however, that it is not possible to use a partial iterator to specify
+ -- an empty sequence of items.
+
+ if Start = No_Element then
+ raise Constraint_Error with
+ "Start position for iterator equals No_Element";
+ end if;
+
+ if Start.Container /= Container'Unrestricted_Access then
+ raise Program_Error with
+ "Start cursor of Iterate designates wrong list";
+ end if;
+
+ pragma Assert (Vet (Start), "Start cursor of Iterate is bad");
+
+ -- The value of the Node component influences the behavior of the First
+ -- and Last selector functions of the iterator object. When the Node
+ -- component is non-null (as is the case here), it means that this
+ -- is a partial iteration, over a subset of the complete sequence of
+ -- items. The iterator object was constructed with a start expression,
+ -- indicating the position from which the iteration begins. Note that
+ -- the start position has the same value irrespective of whether this
+ -- is a forward or reverse iteration.
+
+ return Iterator'(Container'Unrestricted_Access, Node => Start.Node);
end Iterate;
----------
function Last (Object : Iterator) return Cursor is
begin
- if Object.Container = null then
- return No_Element;
+ -- The value of the iterator object's Node component influences the
+ -- behavior of the Last (and First) selector function.
+
+ -- When the Node component is null, this means the iterator object was
+ -- constructed without a start expression, in which case the (reverse)
+ -- iteration starts from the (logical) beginning of the entire sequence
+ -- (corresponding to Container.Last, for a reverse iterator).
+
+ -- Otherwise, this is iteration over a partial sequence of items. When
+ -- the Node component is non-null, the iterator object was constructed
+ -- with a start expression, that specifies the position from which the
+ -- (reverse) partial iteration begins.
+
+ if Object.Node = null then
+ return Doubly_Linked_Lists.Last (Object.Container.all);
else
- return (Object.Container, Object.Container.Last);
+ return Cursor'(Object.Container, Object.Node);
end if;
end Last;
Position : Cursor) return Cursor
is
begin
- if Position.Node = Object.Container.Last then
+ if Position.Container = null then
return No_Element;
- else
- return (Object.Container, Position.Node.Next);
end if;
+
+ if Position.Container /= Object.Container then
+ raise Program_Error with
+ "Position cursor of Next designates wrong list";
+ end if;
+
+ return Next (Position);
end Next;
-------------
Position : Cursor) return Cursor
is
begin
- if Position.Node = Position.Container.First then
+ if Position.Container = null then
return No_Element;
- else
- return (Object.Container, Position.Node.Prev);
end if;
+
+ if Position.Container /= Object.Container then
+ raise Program_Error with
+ "Position cursor of Previous designates wrong list";
+ end if;
+
+ return Previous (Position);
end Previous;
-------------------
procedure Free is
new Ada.Unchecked_Deallocation (Element_Type, Element_Access);
- type Iterator is new
+ type Iterator is limited new
List_Iterator_Interfaces.Reversible_Iterator with record
Container : List_Access;
Node : Node_Access;
function First (Object : Iterator) return Cursor is
begin
- if Object.Container = null then
- return No_Element;
+ -- The value of the iterator object's Node component influences the
+ -- behavior of the First (and Last) selector function.
+
+ -- When the Node component is null, this means the iterator object was
+ -- constructed without a start expression, in which case the (forward)
+ -- iteration starts from the (logical) beginning of the entire sequence
+ -- of items (corresponding to Container.First, for a forward iterator).
+
+ -- Otherwise, this is iteration over a partial sequence of items. When
+ -- the Node component is non-null, the iterator object was constructed
+ -- with a start expression, that specifies the position from which the
+ -- (forward) partial iteration begins.
+
+ if Object.Node = null then
+ return Indefinite_Doubly_Linked_Lists.First (Object.Container.all);
else
- return Cursor'(Object.Container, Object.Container.First);
+ return Cursor'(Object.Container, Object.Node);
end if;
end First;
function Iterate
(Container : List)
- return List_Iterator_Interfaces.Reversible_Iterator'class
+ return List_Iterator_Interfaces.Reversible_Iterator'Class
is
begin
- if Container.Length = 0 then
- return Iterator'(null, null);
- else
- return Iterator'(Container'Unchecked_Access, Container.First);
- end if;
+ -- The value of the Node component influences the behavior of the First
+ -- and Last selector functions of the iterator object. When the Node
+ -- component is null (as is the case here), this means the iterator
+ -- object was constructed without a start expression. This is a
+ -- complete iterator, meaning that the iteration starts from the
+ -- (logical) beginning of the sequence of items.
+
+ -- Note: For a forward iterator, Container.First is the beginning, and
+ -- for a reverse iterator, Container.Last is the beginning.
+
+ return Iterator'(Container'Unrestricted_Access, Node => null);
end Iterate;
function Iterate
(Container : List;
Start : Cursor)
- return List_Iterator_Interfaces.Reversible_Iterator'class
+ return List_Iterator_Interfaces.Reversible_Iterator'Class
is
- It : constant Iterator := (Container'Unchecked_Access, Start.Node);
begin
- return It;
+ -- It was formerly the case that when Start = No_Element, the partial
+ -- iterator was defined to behave the same as for a complete iterator,
+ -- and iterate over the entire sequence of items. However, those
+ -- semantics were unintuitive and arguably error-prone (it is too easy
+ -- to accidentally create an endless loop), and so they were changed,
+ -- per the ARG meeting in Denver on 2011/11. However, there was no
+ -- consensus about what positive meaning this corner case should have,
+ -- and so it was decided to simply raise an exception. This does imply,
+ -- however, that it is not possible to use a partial iterator to specify
+ -- an empty sequence of items.
+
+ if Start = No_Element then
+ raise Constraint_Error with
+ "Start position for iterator equals No_Element";
+ end if;
+
+ if Start.Container /= Container'Unrestricted_Access then
+ raise Program_Error with
+ "Start cursor of Iterate designates wrong list";
+ end if;
+
+ pragma Assert (Vet (Start), "Start cursor of Iterate is bad");
+
+ -- The value of the Node component influences the behavior of the First
+ -- and Last selector functions of the iterator object. When the Node
+ -- component is non-null (as is the case here), it means that this
+ -- is a partial iteration, over a subset of the complete sequence of
+ -- items. The iterator object was constructed with a start expression,
+ -- indicating the position from which the iteration begins. Note that
+ -- the start position has the same value irrespective of whether this
+ -- is a forward or reverse iteration.
+
+ return Iterator'(Container'Unrestricted_Access, Node => Start.Node);
end Iterate;
----------
function Last (Object : Iterator) return Cursor is
begin
- if Object.Container = null then
- return No_Element;
+ -- The value of the iterator object's Node component influences the
+ -- behavior of the Last (and First) selector function.
+
+ -- When the Node component is null, this means the iterator object was
+ -- constructed without a start expression, in which case the (reverse)
+ -- iteration starts from the (logical) beginning of the entire sequence
+ -- (corresponding to Container.Last, for a reverse iterator).
+
+ -- Otherwise, this is iteration over a partial sequence of items. When
+ -- the Node component is non-null, the iterator object was constructed
+ -- with a start expression, that specifies the position from which the
+ -- (reverse) partial iteration begins.
+
+ if Object.Node = null then
+ return Indefinite_Doubly_Linked_Lists.Last (Object.Container.all);
else
- return Cursor'(Object.Container, Object.Container.Last);
+ return Cursor'(Object.Container, Object.Node);
end if;
end Last;
function Next (Object : Iterator; Position : Cursor) return Cursor is
begin
- if Position.Node = Object.Container.Last then
+ if Position.Container = null then
return No_Element;
+ end if;
- else
- return (Object.Container, Position.Node.Next);
+ if Position.Container /= Object.Container then
+ raise Program_Error with
+ "Position cursor of Next designates wrong list";
end if;
+
+ return Next (Position);
end Next;
-------------
function Previous (Object : Iterator; Position : Cursor) return Cursor is
begin
- if Position.Node = Position.Container.First then
+ if Position.Container = null then
return No_Element;
- else
- return (Object.Container, Position.Node.Prev);
end if;
+
+ if Position.Container /= Object.Container then
+ raise Program_Error with
+ "Position cursor of Previous designates wrong list";
+ end if;
+
+ return Previous (Position);
end Previous;
-------------------
OSDN Git Service
