# CVS difference for ai05s/ai05-0001-1.txt

Differences between 1.6 and version 1.7
Log of other versions for file ai05s/ai05-0001-1.txt

```--- ai05s/ai05-0001-1.txt	2009/02/13 07:13:55	1.6
+++ ai05s/ai05-0001-1.txt	2009/02/18 05:47:31	1.7
@@ -1,4 +1,4 @@
-!standard  A.18(0/2)                                 09-02-12    AI05-0001-1/03
+!standard  A.18(0/2)                                 09-02-16    AI05-0001-1/04
!class Amendment 05-10-24
!status work item 06-03-15
@@ -60,21 +60,14 @@

type Vector (Capacity : Count_Type) is tagged private;

-[ARG]
+Add the following declarations after A.18.2(34/2):

-I think Assign is going to be declared for the unbounded forms.
+   procedure Assign (Target : in out Vector; Source : Vector);

-In the case of Assign, we could prefer to preserve the existing
-internal array.  If the source length is equal or less than target
-capacity, there's nothing special to do; however, if source length is
-greater than target capacity, then we must reserve capacity.
-
-Are we over-specifying if we say what the final capacity should be?
-Do we allow the capacity to shrink (as in does when the assignment
-operator is used) in the unbounded form?  Or do we require that the
-unbounded and bounded forms behave identically wrt storage semantics?
+   function Copy (Source : Vector; Capacity : Count_Type := 0)
+      return Vector;

-[END ARG]

procedure Assign (Target : in out Vector; Source : Vector);

@@ -84,12 +77,6 @@
Each element of Source is then assigned to the matching element of
Target.

-[ARG]
-
-We need to make Copy work for the unbounded form too.
-
-[END ARG]
-
function Copy (Source : Vector; Capacity : Count_Type := 0)
return Vector;

@@ -107,17 +94,6 @@

[ARG]

-DO WE ADD ASSIGN AND COPY OPS TO UNBOUNDED FORM?
-(see above - I think yes)
-
-If Assign and Copy really are new operations for the unbounded (and
-bounded) forms, then where do these descriptions go: A.18 or somewhere
-else?
-
-[END ARG]
-
-[ARG]
-
FOR BOUNDED FORM: DECLARE A CAPACITY_SUBTYPE FOR BOUNDED VECTOR
FOR UNBOUNDED CASE TOO

@@ -161,6 +137,32 @@

V : P.Vector (IT'Value_Count);  -- IT'Value_Count = 6

+In a review of a draft of this document, Randy B. said:
+
+The trick here, of course, is to ensure that you're evaluating as
+Universal_Integer. But I suppose that isn't perfect, since the expressions
+don't have to be static, and you could always use a type with more values
+than the largest integer type supported by the compiler.
+
+OTOH, you don't want to support more than Count_Type'Last elements, so
+giving an index with more is dubious.
+
+OT3H, not allowing Natural seems annoying.
+
+Anyway, if you write the expressions as boolean conditionals, they're be
+evaluated as univeral integers. One idea is something like:
+  subtype Capacity_Subtype is Count_Type
+    range 0 .. Count_Type'Max (0,
+       Boolean'Pos(Index_Type'Pos (Index_Type'Last) - Index_Type'Pos
+(Index_Type'First) + 1 > Count_Type'Pos(Count_Type'Last))*Count_Type'Last +
+       Boolean'Pos(Index_Type'Pos (Index_Type'Last) - Index_Type'Pos
+(Index_Type'First) + 1 <= Count_Type'Pos(Count_Type'Last)*(Index_Type'Pos
+(Index_Type'Last) - Index_Type'Pos (Index_Type'First) + 1));
+
+Gosh that's awful. (And it still will raise an exception if Index_Type is a
+64-bit type on GNAT.)
+
+I guess we better leave this one for the full group.
[END ARG]

@@ -212,31 +214,21 @@

[END ARG]

-[ARG]

-My notes from Portland say:
-
-NEED IMPL ADVICE TO SAY THAT MOVE MUST COPY.
-
-That's necessary because the description of the unbounded form (see
-RM05 A.18.2 (261/2)) says:
+[ARG]

-  "Move should not copy elements, and should minimize copying of
-  internal data structures."
+RLB: In the bounded form only? Or in unbounded and bounded
+forms?

-This needs to be modified.  Do we write distinct implementation advice
-for both unbounded and bounded forms?  Or can we leave it as is:
-that's implementation advice for the unbounded form (only), and we
-need not say anything for the bounded case.
+Alternatively, we would have to put as Implementation

-Alternatively, if this implementation advice is supposed to be general
-enough to apply to both forms, then we could qualify the advice by
-saying:
+"The Implementation Advice for procedure Move is deleted."

-  "For the unbounded form, Move should not copy elements, and should
-  minimize copying of internal data structures."
+That's pretty weird.

-[END ARG]
+[END ARG]

procedure Reserve_Capacity
(Container : in out Vector;
@@ -248,9 +240,10 @@

[ARG]

-Does the bounded form get a distinct description for Reserve_Capacity?
-The Reserve_Capacity operation for the unbounded form does not raise
-Capacity_Error.
+The bounded form has a distinct description for Reserve_Capacity,
+because it can raise Capacity_Error.  Where does this description go?
+[RLB: Under the description of Reserve_Capacity in the bounded forms,
+of course. Where else would it go?]

More generally, no operations for the unbounded forms raise
Capacity_Error.  Do we need to specify this distinct behavior of the
@@ -279,26 +272,24 @@
capacity, as follows:

type List (Capacity : Count_Type) is tagged private;
-
-[ARG]

-Here's what I have for Assign:
+Add the following declarations after A.18.3(17/2):

procedure Assign (Target : in out List; Source : List);
+
+   function Copy (Source : List; Capacity : Count_Type := 0)
+      return List;

-  "If Target denotes the same object as Source, the operation has no
-  effect.  If Source length is greater than Target capacity, then the
-  operation raises Capacity_Error, and Target is not modified.
-  Otherwise, it clears Target, and then each element of Source is
-  assigned to the matching element of Target."
-
-The issue is that there's no Reserve_Capacity operation for lists, so
-we can't use the trick as we did for vectors to write a description
-that works for both the unbounded and bounded forms.  Do we write
-distinct descriptions of Assign for the unbounded vs. bounded cases?

-[END ARG]
+   procedure Assign (Target : in out List; Source : List);

+If Target denotes the same object as Source, the operation has no
+effect.  If Source length is greater than Target capacity, then the
+operation raises Capacity_Error, and Target is not modified.
+Otherwise, it clears Target, and then each element of Source is
+assigned to the matching element of Target.
+
function Copy (Source : List; Capacity : Count_Type := 0)
return List;

@@ -307,6 +298,19 @@
to or greater than Source.Length, the list capacity is at least the
specified value.  Otherwise, the operation raises Capacity_Error.

+[ARG]
+
+An issue with Assign here is that there's no Reserve_Capacity
+operation for lists, so we can't use the trick as we did for vectors
+to write a description that works for both the unbounded and bounded
+forms.  Do we write distinct descriptions of Assign for the unbounded
+vs. bounded cases?
+
+In general, operations that can raise Capacity_Error include:
+Append, Insert, Assign, Copy, Move, Prepend, List'Read, Splice
+
+[END ARG]
+
procedure Move (Target : in out List; Source : in out List);

Equivalent to Target.Assign (Source) followed by Source.Clear.
@@ -317,18 +321,12 @@
forms?

[END ARG]
-
-[ARG]
-
-RM05 A.18.3 (162/2) says:

-  "Move should not copy elements, and should minimize copying of
-  internal data structures."

-As with the vector (and other containers), we need to decide what to
+[ARG]

-[END ARG]
+RLB: See notes under bounded vector.

[END ARG]

@@ -360,6 +358,11 @@
Position is moved to Target, immediately preceeding position Before.

+Maps
+
+
+
Bounded Hashed Map

The language-defined generic package Containers.Bounded_Hashed_Maps
@@ -389,6 +392,16 @@
If the specified Capacity is larger than the Container.Capacity, then
it raises Capacity_Error.  Otherwise, the operation has no effect.

+Add the following declarations after A.18.5(17/2):
+
+   procedure Assign (Target : in out Map; Source : Map);
+
+   function Copy (Source   : Map;
+                  Capacity : Count_Type := 0;
+                  Modulus  : Hash_Type := 0) return Map;
+
+
procedure Assign (Target : in out Map; Source : Map);

If Target denotes the same object as Source, the operation has no
@@ -432,6 +445,14 @@

[END ARG]

+[ARG]
+
+I have put the description of Assign and Copy here instead of in
+A.18.4 only because here I have two slightly different descriptions
+for hashed vs. ordered forms.
+
+[END ARG]
+
procedure Move (Target : in out Map; Source : in out Map);

Equivalent to Target.Assign (Source) followed by Source.Clear.
@@ -488,6 +509,15 @@

type Map (Capacity : Count_Type) is tagged private;

+Add the following declarations after A.18.6(16/2):
+
+   procedure Assign (Target : in out Map; Source : Map);
+
+   function Copy (Source   : Map;
+                  Capacity : Count_Type := 0) return Map;
+
+
procedure Assign (Target : in out Map; Source : Map);

If Target denotes the same object as Source, the operation has no
@@ -501,7 +531,6 @@

[END ARG]

-
function Copy (Source   : Map;
Capacity : Count_Type := 0) return Map;

@@ -512,21 +541,24 @@
otherwise, the operation raises Capacity_Error.

[ARG]
-
-My notes say:

-WE DON'T HAVE RES_CAP, SO WE NEED LIST OF OPS THAT MUST ADD CAP CHECK
+Here's a list of operations that raise Capacity_Error:
+Assign, Copy, Include, Insert, Move, Map'Read, Reserve_Capacity

-Does this still apply?
+We just need to decide how to handle these, since there are
+differences between the unbounded and bounded forms.

[END ARG]

-
procedure Move (Target : in out Map; Source : in out Map);

Equivalent to Target.Assign (Source) followed by Source.Clear.

+Sets
+
+
Bounded Hashed Set

The language-defined generic package Containers.Bounded_Hashed_Sets
@@ -556,6 +588,16 @@
If the specified Capacity is larger than the Container.Capacity, then
it raises Capacity_Error.  Otherwise, the operation has no effect.

+Add the following declarations after A.18.8(17/2):
+
+   procedure Assign (Target : in out Set; Source : Set);
+
+   function Copy (Source   : Set;
+                  Capacity : Count_Type := 0;
+                  Modulus  : Hash_Type := 0) return Set;
+
+
procedure Assign (Target : in out Set; Source : Set);

If Target denotes the same object as Source, the operation has no
@@ -564,7 +606,6 @@
Otherwise, it clears Target and inserts each element of Source into
Target.

-
function Copy (Source   : Set;
Capacity : Count_Type := 0;
Modulus  : Hash_Type := 0) return Set;
@@ -615,6 +656,15 @@

type Set (Capacity : Count_Type) is tagged private;

+Add the following declarations after A.18.9(16/2):
+
+   procedure Assign (Target : in out Set; Source : Set);
+
+   function Copy (Source   : Set;
+                  Capacity : Count_Type := 0) return Set;
+
+
procedure Assign (Target : in out Set; Source : Set);

If Target denotes the same object as Source, the operation has no
@@ -766,16 +816,16 @@
Reorders the elements of an indexable container, over the range First
.. Last, such that the elements are sorted smallest first as
determined by the generic formal Less function provided. Generic
-formal Less compares the container elements having the given indices,
-and generic formal Swap exchanges the values of the indicated
-container elements. Any exception raised during evaluation of Less or
-Swap is propagated.
+formal Less compares the elements having the given indices, and
+generic formal Swap exchanges the values of the indicated
+elements. Any exception raised during evaluation of Less or Swap is
+propagated.

The actual function for the generic formal function Less of
Generic_Sort is expected to return the same value each time it is
called with a particular pair of element values. It should define a
-strict weak ordering relationship (see A.18); it should not modify
-Container. If the actual for Less behaves in some other manner, the
+strict weak ordering relationship (see A.18); it should not modify the
+elements. If the actual for Less behaves in some other manner, the
behavior of Generic_Sort is unspecified. How many times the
Generic_Sorts calls Less or Swap is unspecified.

@@ -3603,8 +3653,8 @@
> Is there some place where I can help? (If I find some spare time, of
> course.)

-Yes, of course.  The best place is to post to the adalib list.
-Otherwise, I can give you developer status in jean repository, which
+Yes, of course.  The best place is to post to the adalib list.
+Otherwise, I can give you developer status in jean repository, which
would allow you to edit (and check-in) sources directly.

@@ -3617,26 +3667,26 @@
> range -- but we could never even add those elements, since the maximum
> vector length is determined by the range of the index subtype.  Should
> we allow this? [END ARG]
->
+>
> I think if someone asks for this, he gets what he asked for. A note in
> the AARM (or, if this is only a secondary standard to the RM, in
> something similar) could be added.

-OK, that makes sense.  I don't think we made any explicit statement in
-the RM to handle this case for the unbounded forms, so maybe we don't
+OK, that makes sense.  I don't think we made any explicit statement in
+the RM to handle this case for the unbounded forms, so maybe we don't

> 2.----------------------------------------------------------------------
-> Why is there a Reserve_Capacity? It's completely useless.
+> Why is there a Reserve_Capacity? It's completely useless.

-Actually, I think that it has semantics identical to the unbounded form.
-  (But I have to think about it.  Maybe I over-specified, in which case
+Actually, I think that it has semantics identical to the unbounded form.
+  (But I have to think about it.  Maybe I over-specified, in which case
no discussion would even be necessary.)

> Is it just for

Yes.

@@ -3645,8 +3695,8 @@
> which are not in Ada.Containers.Vectors, so this breaks compatibility,
> so why shouldn't there be some missing?

-I suspect that the operations we add to the bounded form will eventually
-migrate into the unbounded forms as well.  (I think the only two
+I suspect that the operations we add to the bounded form will eventually
+migrate into the unbounded forms as well.  (I think the only two
operations are Assign and Copy.  I forget -- were there others?)

@@ -3657,7 +3707,7 @@
> For vectors: Arrays raise CE; vectors are kind of arrays, so they also
> should raise CE. Bounded strings raise CE.

-OK, that's a data point from a HI user.  Reviewing my code I see that I
+OK, that's a data point from a HI user.  Reviewing my code I see that I
raise both SE and CE, inconsistently.  Thanks for the tip.

****************************************************************
@@ -3693,7 +3743,7 @@
From: Matthew Heaney
Sent: Friday, October 24, 2008  5:51 AM

-> A quick glance at this did not turn up any wording for
+> A quick glance at this did not turn up any wording for
> Reserve_Capacity for bounded vectors and lists.

For Vector it's on line #105:
@@ -3717,14 +3767,14 @@
Otherwise, the operation does nothing.

-> I think you need to say somewhere that the capacity of the container
-> cannot be changed, and an attempt to set it larger than specified will
-> always fail with Storage_Error (if that what we decided??). Surely
+> I think you need to say somewhere that the capacity of the container
+> cannot be changed, and an attempt to set it larger than specified will
+> always fail with Storage_Error (if that what we decided??). Surely
> that needs to be mentioned (it's the whole point of bounded).

Is this requirement satisfied by descriptions above?

-> I see you do mention it for Maps, but then say it is the same as
+> I see you do mention it for Maps, but then say it is the same as
> Unbounded.

But that part was non-normative.  It was in the form of a question to be
@@ -3745,15 +3795,15 @@
> difference in intent. Surely we want to explain that somewhere, else these
> containers will not be obviously different.

-OK, that's fine by me.  I was trying to minimize the amount of normative
-text, but if you think it's more clear to be explicit about behavior for
+OK, that's fine by me.  I was trying to minimize the amount of normative
+text, but if you think it's more clear to be explicit about behavior for
bounded forms then we can leave it in.

> Also note that if Reserve_Capacity is properly documented, changing Insert,
> etc. isn't needed, because they all call Reserve_Capacity when they need to
> expand (and that will raise an exception).

-Good point.  I'll have to review all the spots where Reserve_Capacity is
+Good point.  I'll have to review all the spots where Reserve_Capacity is
called indirectly, as a side-effect of insertion, etc.

> And I do think you need to mention (but perhaps only in an AARM
@@ -3801,4 +3851,3 @@
"need finalization."

****************************************************************
-
```

Questions? Ask the ACAA Technical Agent