Re: Two approaches of iterators for the key-value pairs

[Brad Moore <bmoore.ada@gmail.com>]

On Friday, November 27, 2015 at 8:26:02 AM UTC-7, ytomino wrote:
> Hello, I'm reading AI12-0009-1 "Iterators for Directories and Environment_Variables".
> http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ai12s/ai12-0009-1.txt?rev=1.4
> 
> And there is interesting difference between the new iterator of Ada.Environment_Variables and the existing iterators.
> (The boolean trick of these new iterators is also interesting, but set aside.)

I'm not sure what is being referred to here as a "boolean trick". Perhaps you are referring to the mention of "Rosen Trick", which as Randy points out, should probably be called "Rosen Technique". However that has nothing to do with "Boolean". The Rosen technique is a coding technique that allows one to treat a read only "in" parameter as a modifiable "in out" parameter.

> 
> A loop for Ada.Environment_Variables would be like below, according to this AI:
> 
> for E *of* Ada.Environment_Variables.All_Variables loop
>    -- E is Iterator_Element (Name_Value_Pair_Type)
>    Name (E) -- key
>    Value (E) -- value
> end loop;
> 
> On the other hand, as we already know, a loop for Ada.Containers.Hashed_Maps/Ordered_Maps:
> 
> for I *in* The_Map_Object.Iterate loop
>    -- I is Cursor
>    Key (E) -- key
>    Element (E), Reference (E).Element.all -- value
> end loop;

All the existing containers are iterable containers, so they support
both using "of" and "in" syntax for loops. Using "of" is generally preferable
because cursors are implicit, and the code written by the user is therefore simpler. Using "in" syntax can also be used by obtaining an Iterator object, but this gives you a cursor instead of a container element, so you typically would need to write some extra calls to get to the container element from the cursor object.


This code excerpt you had above would not compile, so it is probably confusing people.
It think it would be better to perhaps show a full simple working example, such as incrementing each element of the container;
Here I show both forms of loop using a Hashed_Map container. As you can see,
the "of" format is simpler, and hopefully easier to read and understand.

with Ada.Containers.Hashed_Maps; use Ada;
procedure Test_Iterator is
   
   type Student_Id is new Positive;
   type Grade is new Natural range 0 .. 100;
   function Hash (Student : Student_Id) return Containers.Hash_Type is
     (Containers.Hash_Type (Student));
   
   package Maps is new Ada.Containers.Hashed_Maps 
     (Key_Type        => Student_Id,
      Element_Type    => Grade,
      Hash            => Hash,
      Equivalent_Keys => "=");

   School : Maps.Map;
   
begin

   School.Insert (Key      => 123456,    -- Student A
                  New_Item => 90);
   School.Insert (Key      => 789123,    -- Student B
                  New_Item => 65);

   -- Iterate using "in" syntax (for an iterator)
   for Cursor in School.Iterate loop
      School.Replace (Key => Maps.Key (Cursor), 
                      New_Item => Maps.Element (Cursor) + 1);
   end loop;

   -- Iterate using "of" syntax (for an iterable containter)
   for Grade of School loop
      Grade := Grade + 1;
   end loop;

   
end Test_Iterator;

For the AI for Ada 202x on Ada.Directories and Ada.Environment_Variables,
this is a work in progress, so it may end up looking very different in the end, or may even not make the cut for Ada 202x.

Essentially, the design choice discussed in the AI is whether to expose an Iterable Container type, or just an Iterator type.

Both choices could be made to have the same interface for the user, with the only difference being whether "in" or "of" appears in the loop.

If we expose an Iterable container though, that also gives the ability to use "in" syntax since an Iterable container is associated with an Iterator type, and that Iterator type could be used in the loop. However, in that case, as with other existing standard container types and as seen in my example above, using the "in" form would be a bit more awkward to use, compared to the "of" form, so I suspect most people would just use "of".

So the question really is, if we add Ada 2012 Iterator support to Ada.Directories and/or Ada.Environment_Variables, should the design be to 
expose just an Iterator type, or both an Iterator Type, and an Iterable container type?

My thought is that the latter might be better mostly because it would be more consistent with the other standard container types, but I could go either way.

A secondary question might be for anyone creating such abstractions of their own, are there cases where creating an Iterator type makes better sense than creating an Iterable container type?  The ACATS test involving the Prime number iterator could be an example of such an iterator type, but note I could have written that also as an Iterable Container type instead.

In other words, can general guidance be given about how to choose an approach, or does it not really matter, and the writer of such abstractions should choose which ever approach they fancy? 

Brad

> 
> If you create new iterator for some key-value pairs, which approach do you like?
> 
> -- 
> Yuta Tomino