Version 1.2 of ai05s/ai05-0268-1.txt

!topic Incomplete and missing Examples in the RM
!reference Ada 2012 RM-4.1.5, 4.1.6, 5.5.2
!from Christoph Grein 2011-07-20
!keywords Examples, aspects, User-Defined References,
Implicit_Dereference, User-Defined Indexing, Variable_Indexing,
Constant_Indexing
!discussion
For the new syntaxes, especially the ones in the sections above,
examples are incomplete or completely missing.

4.1.5(9/3..13/3) gives this coding example:

  type Ref_Element(Data: access Element) is
    new Ada.Finalization.Limited_Controlled with private
      with Implicit_Dereference => Data;
  -- This Ref_Element type is a "reference" type.
  -- "Data" is its reference discriminant.

  function Find(C : access Container; Key : String) return Ref_Element;
  -- Return a reference to an element of a container.
  ...
  Find(C, "abc") := Element'(...); -- Assign through a reference.
  -- This is equivalent to:
  -- Find(C, "abc").Data.all := Element'(...);

Here the parameter C and also the Container type are undefined. It
doesn't really matter for this example, but I think for completeness
(and to avoid any guessing on the side of the reader) the following two
declarations have to be added at appropriate places:

type Container is tagged limited private;  -- holds objects of type
Element

C: aliased Container;

Then the calls of Find have to be updated like so:

Find (C'Access, "abc") := Element'(...); -- Assign through a reference.
-- This is equivalent to:
Find (C'Access, "abc").Data.all := Element'(...);

(I would prefer to see "Apple" or something more speaking as the key.)

Note: GNAT GPL 2011 already implements this aspect, but rejects this
call
      on the left-hand side of an assignment. Is this an implementation
bug?

On subsection 4.1.6, an example is completely missing. I think the
example above can very easily extended like this:

type Container is tagged limited private
  with Variable_Indexing => Find;
  -- Container is an indexable type,
  -- Find (see 4.1.5) is the generalized indexing operation.

-- All these calls are then equivalent:
Find (C'Access, "Apple").Data.all := Element'(...);-- (see 4.1.5) trad.
call
C.Find ("Apple").Data.all := Element'(...);  -- Object.Operation
notation
C.Find ("Apple")          := Element'(...);  -- (see 4.1.5) impl. Deref.
C      ("Apple")          := Element'(...);  -- implicit Indexing

Note: I'm not sure that this is correct; I haven't yet tried this with
GNAT
      (I do not know whether this aspect is already implemented).

5.5.2 Generalized Loop Iteration should provide examples as well,
preferably based on the above. I do not try for assorted reasons. I'm
aware that examples might get quite long here.
(I'm aware of the fact that containers has a complete example (A.18.33).
So I'm not sure what to do here. Perhaps a forward reference? Currently
there is no such thing in the RM, all examples are (or have to be)
complete or based on previous (sub)chapters.)

****************************************************************