Ada Conformity Assessment Authority      Home Conformity Assessment   Test Suite ARGAda Standard
 
Annotated Ada Reference Manual (Ada 202x Draft 25)Legal Information
Contents   Index   References   Search   Previous   Next 

5.5.1 User-Defined Iterator Types

Static Semantics

1/3
{AI05-0139-2} The following language-defined generic library package exists: 
2/5
{AI12-0241-1} generic
   type Cursor;
   with function Has_Element (Position : Cursor) return Boolean;
package Ada.Iterator_Interfaces is
   with Pure, Nonblocking => False is pragma Pure (Iterator_Interfaces);
3/3
   type Forward_Iterator is limited interface;
   function First (Object : Forward_Iterator) return Cursor is abstract;
   function Next (Object : Forward_Iterator; Position : Cursor)
      return Cursor is abstract;
4/3
   type Reversible_Iterator is limited interface and Forward_Iterator;
   function Last (Object : Reversible_Iterator) return Cursor is abstract;
   function Previous (Object : Reversible_Iterator; Position : Cursor)
      return Cursor is abstract;
4.1/5
{AI12-0266-1}    type Parallel_Iterator is limited interface and Forward_Iterator;
4.2/5
{AI12-0266-1}    subtype Chunk_Index is Positive;
4.3/5
{AI12-0266-1}    function Is_Split (Object : Parallel_Iterator)
      return Boolean is abstract;
4.4/5
{AI12-0266-1}    procedure Split_Into_Chunks (Object     : in out Parallel_Iterator;
                                Max_Chunks : in     Chunk_Index) is abstract
      with Pre'Class   => not Object.Is_Split or else raise Program_Error,
           Post'Class  => Object.Is_Split and then
                          Object.Chunk_Count <= Max_Chunks;
4.5/5
{AI12-0266-1}    function Chunk_Count (Object : Parallel_Iterator)
      return Chunk_Index is abstract
      with Pre'Class   => Object.Is_Split or else raise Program_Error;
4.6/5
{AI12-0266-1}    function First (Object : Parallel_Iterator;
                   Chunk  : Chunk_Index) return Cursor is abstract
      with Pre'Class   => (Object.Is_Split and then
                              Chunk <= Object.Chunk_Count)
                           or else raise Program_Error;
4.7/5
{AI12-0266-1}    function Next (Object   : Parallel_Iterator;
                  Position : Cursor;
                  Chunk    : Chunk_Index) return Cursor is abstract
      with Pre'Class   => (Object.Is_Split and then
                              Chunk <= Object.Chunk_Count)
                           or else raise Program_Error;
4.8/5
{AI12-0266-1}    type Parallel_Reversible_Iterator is limited interface
      and Parallel_Iterator and Reversible_Iterator;
5/3
end Ada.Iterator_Interfaces;
5.a/5
Reason: {AI12-0241-1} This package must allow blocking (Nonblocking => False) for compatibility. The purpose of this package is to provide a template for overriding user-defined routines; and such routines can only allow blocking if the root type does so. Users can still declare their overridding routines nonblocking if they wish. 
6/5
{AI05-0139-2} {AI12-0266-1} An iterator type is a type descended from the Forward_Iterator interface from some instance of Ada.Iterator_Interfaces. A reversible iterator type is a type descended from the Reversible_Iterator interface from some instance of Ada.Iterator_Interfaces. A parallel iterator type is a type descended from the Parallel_Iterator interface from some instance of Ada.Iterator_Interfaces. A type descended from the Parallel_Reversible_Iterator interface from some instance of Ada.Iterator_Interfaces is both a parallel iterator type and a reversible iterator type. An iterator object is an object of an iterator type. A reversible iterator object is an object of a reversible iterator type. A parallel iterator object is an object of a parallel iterator type. The formal subtype Cursor from the associated instance of Ada.Iterator_Interfaces is the iteration cursor subtype for the iterator type.
7/3
{AI05-0139-2} {AI05-0292-1} The following type-related operational aspects may be specified for an indexable container type T (see 4.1.6):
8/5
{AI12-0111-1} Default_Iterator

This aspect is specified by a name that denotes exactly one function declared immediately within the same declaration list in which T is declared, whose first parameter is of type T or T'Class or an access parameter whose designated type is type T or T'Class, whose other parameters, if any, have default expressions, and whose result type is an iterator type. This function is the default iterator function for T. Its result subtype is the default iterator subtype for T. The iteration cursor subtype for the default iterator subtype is the default cursor subtype for T. This aspect is inherited by descendants of type T (including T'Class).
8.a/3
Aspect Description for Default_Iterator: Default iterator to be used in for loops.
9/5
{AI12-0111-1} Iterator_Element

This aspect is specified by a name that denotes a subtype. This is the default element subtype for T. This aspect is inherited by descendants of type T (including T'Class).
9.a/3
Aspect Description for Iterator_Element: Element type to be used for user-defined iterators.
9.1/5
 {AI12-0111-1} Iterator_View

This aspect is specified by a name that denotes a type T2 with the following properties:
9.2/5
T2 is declared in the same compilation unit as T;
9.3/5
T2 is an iterable container type;
9.4/5
T2 has a single discriminant which is an access discriminant designating T; and
9.5/5
The default iterator subtypes for T and T2 statically match. 
9.6/5
This aspect is never inherited[, even by T'Class].
9.b/5
Reason: Iterator_View allows specifying an alternative type to be automatically used by container element iterators; see 5.5.2. This allows setting state for an iteration only once rather than for each individual reference. 
9.c/5
Ramification: Since Iterator_View is not inherited, it does not apply to T'Class. Otherwise, the type of the iterator object would not be known at compile-time (since it necessarily has to be different for each descendant).
9.d/5
Aspect Description for Iterator_View: An alternative type to used for container element iterators.
10/5
This paragraph was deleted.{AI12-0111-1} These aspects are inherited by descendants of type T (including T'Class).
11/5
{AI05-0139-2} {AI05-0292-1} {AI12-0266-1} An iterable container type is an indexable container type with specified Default_Iterator and Iterator_Element aspects. A reversible iterable container type is an iterable container type with the default iterator type being a reversible iterator type. A parallel iterable container type is an iterable container type with the default iterator type being a parallel iterator type. An iterable container object is an object of an iterable container type. A reversible iterable container object is an object of a reversible iterable container type. A parallel iterable container object is an object of a parallel iterable container type.
11.a.1/3
Glossary entry: An iterable container type is one that has user-defined behavior for iteration, via the Default_Iterator and Iterator_Element aspects.
11.1/4
  {AI12-0138-1} The Default_Iterator and Iterator_Element aspects are nonoverridable (see 13.1.1).
11.a/4
Reason: This ensures that all descendants of an iterable container type have aspects with the same properties. This prevents generic contract problems with formal derived types. 

Legality Rules

12/3
{AI05-0139-2} {AI05-0292-1} The Constant_Indexing aspect (if any) of an iterable container type T shall denote exactly one function with the following properties:
13/3
the result type of the function is covered by the default element type of T or is a reference type (see 4.1.5) with an access discriminant designating a type covered by the default element type of T;
14/3
the type of the second parameter of the function covers the default cursor type for T;
15/3
if there are more than two parameters, the additional parameters all have default expressions.
16/3
This function (if any) is the default constant indexing function for T.
16.a/3
Ramification: This does not mean that Constant_Indexing has to designate only one subprogram, only that there is only one routine that meets all of these properties. There can be other routines designated by Constant_Indexing, but they cannot have the profile described above. For instance, map containers have a version of Constant_Indexing that takes a key instead of a cursor; this is allowed.
17/3
{AI05-0139-2} {AI05-0292-1} The Variable_Indexing aspect (if any) of an iterable container type T shall denote exactly one function with the following properties:
18/3
the result type of the function is a reference type (see 4.1.5) with an access discriminant designating a type covered by the default element type of T;
19/3
the type of the second parameter of the function covers the default cursor type for T;
20/3
if there are more than two parameters, the additional parameters all have default expressions.
21/3
This function (if any) is the default variable indexing function for T.

Extensions to Ada 2005

21.a/3
{AI05-0139-2} User-defined iterator types are new in Ada 2012.

Incompatibilities With Ada 2012

21.b/4
{AI12-0138-1} Corrigendum: Defined Default_Iterator and Iterator_Element to be nonoveridable, which makes redefinitions and hiding of these aspects illegal. It's possible that some program could violate one of these new restrictions, but in most cases this can easily be worked around by using overriding rather than redefinition.
21.c/5
{AI12-0266-1} Various new types and subprograms are newly added to Ada.Iterator_Interfaces. If an instance of Ada.Iterator_Interfaces is referenced in a use_clause, and an entity with one of the new names is defined in some other package that is also referenced in a use_clause, the user-defined entity may no longer be use-visible, resulting in errors. This should be rare and is easily fixed if it does occur. 

Extensions to Ada 2012

21.d/5
{AI12-0111-1} Aspect Iterator_View is new; it allows container element iterators to set the tampering state once rather than for each use of the element.
21.e/5
{AI12-0266-1} Parallel iterator interfaces are new; they allow user-defined parallel loops to be defined. 

Contents   Index   References   Search   Previous   Next 
Ada-Europe Ada 2005 and 2012 Editions sponsored in part by Ada-Europe