!standard A.18.3(6/5)                                   20-08-31  AI12-0391-1/01
!standard A.18.3(23/5)
!standard A.18.3(96/5)
!class Amendment 20-08-31
!status work item 20-08-31
!status received 20-06-16
!priority Low
!difficulty Easy
!subject List containers need Append_One
!summary

Add an Append_One operation to Ada.Containers.Doubly_Linked_Lists, and
use it for Add_Unnamed in the Aggregate aspect.

!problem

Ada.Containers.Doubly_Linked_Lists has in the Aggregate aspect,
Add_Unnamed using the existing Append operation. However, the existing 
Append operation includes a Count parameter which does not meet the 
profile of the required operation. Fix this? (Yes.)

!proposal

(See Summary.)

!wording

In A.18.3(6/5), replace "Append" with "Append_One".

Add after A.18.3(23/5):

   procedure Append_One (Container : in out List;
                         New_Item  : in     Element_Type)
      with Pre  => (not Tampering_With_Cursors_Prohibited (Container)
                       or else raise Program_Error) and then
                   (Length (Container) <= Count_Type'Last - 1
                       or else raise Constraint_Error),
           Post => Length (Container)'Old + 1 = Length (Container);


Add after A.18.3(96/5):

procedure Append_One (Container : in out List;
                      New_Item  : in     Element_Type)
   with Pre  => (not Tampering_With_Cursors_Prohibited (Container)
                   or else raise Program_Error) and then
                (Length (Container) <= Count_Type'Last - 1
                   or else raise Constraint_Error),
        Post => Length (Container)'Old + 1 = Length (Container);

    Equivalent to Insert (Container, No_Element, New_Item, 1).

!discussion

As in Vectors, this operation cannot be named Append, as any call to Append 
without the Count parameter would be ambiguous if that was the case.

!ASIS

No ACATS effect.

!ACATS test

An ACATS C-Test is needed to check that the new procedure exists and works as
expected. (This is a low priority test, as container aggregates will use the
procedure, and thus the aggregate tests will check this functionality 
indirectly.)

!appendix

From: Ed Schonberg
Sent: Tuesday, June 16, 2020  3:29 PM

The modification to Ada/Containers.Doubly_Linked_Lists (A.18.3) indicates that 
the aspect Aggregate uses the existing Append operation fort Add_Unnamed. 
However the existing Append operation includes a Count parameter which does 
not meet the profile of the required operation.  An operation Append_One should 
be mentioned, as is already done for the Vector container.

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

From: Tucker Taft
Sent: Tuesday, June 16, 2020  3:38 PM

Good point!

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