!standard  4.5.5(8)                               11-11-08    AI05-0268-1/01
!class binding interpretation 11-06-19
!status Amendment 2012 11-07-28
!status ARG Approved 11-1-0  11-06-26
!status work item 11-06-16
!status received 11-05-17
!priority Low
!difficulty Easy
!qualifier Error
!subject Examples in new sections of the Standard
!summary

** TBD.

!question

The examples in 4.1.5, 4.1.6, and 5.5.2 seem incomplete or are missing altogether.

!proposal

Add the following to the example in 4.1.5:

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, "grape") := Element'(...); -- Assign through a reference.
-- This is equivalent to:
Find (C'Access, "grape").Data.all := Element'(...);

Add an example to 4.1.6:

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, "grape").Data.all := Element'(...);-- (see 4.1.5) traditional call
C.Find ("grape").Data.all := Element'(...);  -- call of prefixed view
C.Find ("grape")          := Element'(...);  -- (see 4.1.5) implicit dereference
C      ("grape")          := Element'(...);  -- implicit Indexing


Add an example to 5.5.2:

** TBD.

!wording

** TBD.

!discussion

The example in the containers section covers most of this material. Should we
use a forward reference instead??

!ACATS Test

None needed.

!ASIS

No change needed.

!appendix

!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.)

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