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

Unformatted version of ai05s/ai05-0268-1.txt version 1.3
Other versions for file ai05s/ai05-0268-1.txt

!standard 4.1.5(0/3)          11-12-16 AI05-0268-1/02
!standard 4.1.6(0/3)
!standard 5.5.2(0/3)
!class Amendment 11-11-08
!status Amendment 2012 11-11-11
!status ARG Approved 8-0-0 11-11-11
!status work item 11-11-08
!status received 11-07-20
!priority Low
!difficulty Easy
!subject Examples in new sections of the Standard
!summary
Improve the examples in new clauses in the Standard.
!question
The examples in 4.1.5, 4.1.6, and 5.5.2 seem incomplete or are missing altogether.
!proposal
Add the following in front of 4.1.5(9/3):
type Barrel is tagged ... -- holds objects of type Element
B: aliased Barrel;
Replace 4.1.5(10/3) with:
function Find(B : aliased in out Barrel; Key : String) return Ref_Element; -- Return a reference to an element of a barrel
Replace 4.1.5(12-13/3) with:
Find (B, "grape") := Element'(...); -- Assign through a reference.
-- This is equivalent to: Find (B, "grape").Data.all := Element'(...);
Add an example to 4.1.6 after 4.1.6(17/3):
Examples
type Indexed_Barrel is tagged ... with Variable_Indexing => Find; -- Indexed_Barrel is an indexable type, -- Find is the generalized indexing operation.
function Find(B : aliased in out Indexed_Barrel; Key : String) return Ref_Element; -- Return a reference to an element of a barrel (see 4.1.5).
IB: aliased Indexed_Barrel;
-- All of the following calls are then equivalent: Find (IB,"pear").Data.all := Element'(...); -- Traditional call IB.Find ("pear").Data.all := Element'(...); -- Call of prefixed view IB.Find ("pear") := Element'(...); -- Implicit dereference (see 4.1.5) IB ("pear") := Element'(...); -- Implicit indexing and dereference IB ("pear").Data.all := Element'(...); -- Implicit indexing only
Add an example to 5.5.2 after 5.5.2(13/3):
Examples
for examples of use of generalized iterators, see A.18.32 and the corresponding container packages in A.18.2 and A.18.3.
!wording
(See proposal.)
!discussion
Any example for the generalized iterators is going to be large. We point the reader at the containers example rather than trying to create another example.
!corrigendum 4.1.5(0)
Insert new clause:
Force a conflict; the real text is found in the conflict file.
!corrigendum 4.1.6(0)
Insert new clause:
Force a conflict; the real text is found in the conflict file.
!corrigendum 5.5.2(0)
Insert new clause:
Force a conflict; the real text is found in the conflict file.
!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.)

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


Questions? Ask the ACAA Technical Agent