CVS difference for ai12s/ai12-0304-1.txt

Differences between 1.2 and version 1.3
Log of other versions for file ai12s/ai12-0304-1.txt

--- ai12s/ai12-0304-1.txt	2019/01/13 06:32:23	1.2
+++ ai12s/ai12-0304-1.txt	2019/04/12 04:49:12	1.3
@@ -1,6 +1,4 @@
-!standard 5.5.2(2/3)                                  19-01-11  AI12-0304-1/01
-!standard 5.5.2(5/4)
-!standard 5.5.2(7/3)
+!standard 4.10(0)                                  19-04-09  AI12-0304-1/02
 !class Amendment 19-01-11
 !status work item 19-01-11
 !status received 19-01-10
@@ -25,26 +23,38 @@
 
 Append to the end of the new (as of AI12-0020) 4.10 Images section.
 
-    For any language-defined scalar type T, T'Put_Image shall not
-    be specified.
-
     Implementation Permissions
 
-    For each language-defined non-scalar type T, T'Put_Image
+    For each language-defined nonscalar type T, T'Put_Image
     may be specified.
 
     AARM note: This permission applies, in particular, to
-    non-scalar types declared in language-defined generic packages,
-    and to any language-defined private type which an implementation
-    chooses to complete as a scalar type.
+    nonscalar types declared in language-defined generic packages,
+    and to any language-defined private type, even if an implementation
+    chooses to complete it as a scalar type.
+
+    AARM Note: For any language-defined scalar type T, T'Put_Image should
+    not be specified; the Image attribute needs to return the language-defined 
+    image for such types. This is important for compatibility: the Image 
+    attribute have been available for scalar types for many Ada revisions, 
+    and programs can (and do!) depend on its behavior.
 
     Implementation Advice
 
-    For each language-defined container type T (i.e., each of the Vector,
+    For each language-defined container type T (that is, each of the Vector,
     List, Map, Set, Tree, and Holder types defined in the various
     children of Ada.Containers), T'Put_Image should be specified so
     that T'Image produces a result consistent with array aggregate
     syntax (using "[" and "]" as delimiters) as follows:
+        - Vector images should be consistent with the default image of 
+          an array type with the same index and component types.
+
+          AARM Note: In particular, this means that the format is that
+          of a named array aggregate. We have no recommendation on how to 
+          handle empty elements; if the implementation can identify them, it
+          may wish to display them specially, but otherwise, they're just 
+          uninitialized elements.
+
         - Map images should be consistent with named array aggregate
           syntax, using key value images in place of discrete choice
           names. For example, "[Key1 => Value1, Key2 => Value2]".
@@ -54,12 +64,13 @@
             key/element pairs occur within a map image. In the case of
             multiple key values whose corresponding element values have
             the same image, there is no recommendation about factoring
-            (e.g., generating "Key1 | Key2 => Some_Value" instead of
+            (that is, generating "Key1 | Key2 => Some_Value" instead of
             "Key1 => Some_Value, Key2 => Some_Value").
 
         - Set, List, and Holder images should be consistent with
           positional array aggregate syntax. List elements should
-          occur in order within an image of a list.
+          occur in order within an image of a list. The image of an
+          empty holder should be "[]".
 
           AARM Note:
             There is no recommendation about the order in which
@@ -69,10 +80,10 @@
           consistent with positional array aggregate syntax.
           For example, "[[1, 2], [111, 222, 333]]".
 
-    For each language-defined type T that has a primitive
+    For each language-defined nonscalar type T that has a primitive
     language-defined Image function whose profile is type conformant with
-    that of T'Image (e.g., Ada.Numerics.Float_Random.State has such an
-    Image function), T'Put_Image should be specified so that T'Image
+    that of T'Image (for example, Ada.Numerics.Float_Random.State has such 
+    an Image function), T'Put_Image should be specified so that T'Image
     yields the same result as that Image function.
 
     AARM Note:
@@ -84,21 +95,22 @@
 !discussion
 
 One could imagine going into great detail specifying the behavior of the 
-image attributes of all of the various non-scalar predefined types.
+image attributes of all of the various nonscalar predefined types.
 
 That does not seem like a good idea (do we really want to spend any time 
 considering what images should look like for the private type 
 Ada.Text_IO.Editing.Picture?).
 
-But the container types do seem to be of particular interest, so perhaps 
-we ought to say something about them. (Incidentally, is there anything 
-that we want to say about the Image attributes of the various cursor types?).
+But the container types are of particular interest, so we ought to say 
+something about them. 
 
 ---
 
-The first new rule (the prohibition on specifying T'Put_Image for a 
-language-defined scalar type T) is intended to ensure that the behavior of 
-T'Image (and T'Wide_Image, etc.) remains unchanged from what it was before 
+We don't need to normatively prohibit specifying T'Put_Image for a 
+language-defined scalar type T, as arbitrary changes to language-defined
+packages are not permitted (with a handful of exceptions). In any case,
+we do not want the behavior of T'Image (and T'Wide_Image, and so on),
+for all language-defined scalar types T, to change from what it was before
 the Put_Image aspect was introduced.
 
 In two places, the wording says "T'Put_Image should be specified so that" 
@@ -110,9 +122,13 @@
 
 [Editor's note: I think the recently added "as-if" AARM Note {A(5.d/5)} would
 cover this. The only way this would matter is if there exists some program
-that could tell the difference. I don't know of such a way, but perhaps the
-author does.]
+that could tell the difference. I don't know of such a way.]
 
+
+!corrigendum 4.10(0)
+@dinsc
+A fake to force a conflict; the actual text is in the conflict file.
+
 !ASIS
 
 No ASIS effect.
@@ -343,12 +359,19 @@
 Ada.String.Maps.Character_Set
 Ada.String.Wide_Maps.Wide_Character_Set
 Ada.String.Wide_Wide_Maps.Wide_Wide_Character_Set
-Bounded_String (from an instance Ada.String.Bounded) Ada.Strings.Unbounded.Unbounded_String
+Bounded_String (from an instance Ada.String.Bounded) 
+Ada.Strings.Unbounded.Unbounded_String
 Ada.Task_Identification.Task_Id
-Cursor (from an instance of an Ada.Containers) Wide_Bounded_String (from an instance Ada.Strings.Wide_Bounded) Ada.Strings.Wide_Unbounded.Wide_Unbounded_String
+Cursor (from an instance of an Ada.Containers) 
+Wide_Bounded_String (from an instance Ada.Strings.Wide_Bounded) 
+Ada.Strings.Wide_Unbounded.Wide_Unbounded_String
 Wide_Wide_Bounded_String
 Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Unbounded_String
-State (from an instance Ada.Numerics.Discrete_Random) Ada.Numerics.Float_Random.State Ada.Real_Time.Time_Span Ada.Real_Time.Time Imaginary (from an instance Ada.Numerics.Generic_Complex_Types)
+State (from an instance Ada.Numerics.Discrete_Random) 
+Ada.Numerics.Float_Random.State 
+Ada.Real_Time.Time_Span 
+Ada.Real_Time.Time 
+Imaginary (from an instance Ada.Numerics.Generic_Complex_Types)
 Ada.Calendar.Time
 Ada.Exceptions.Exception_Id
 Interfaces.C.Strings.chars_ptr
@@ -471,5 +494,81 @@
 We almost never use Notes directed at implementations.  Notes are almost 
 always for the user.  I would stick with Implementation Advice or an AARM 
 note.  At this point, I suggest we leave the final decision to an ARG meeting.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Thursday, April 11, 2019  11:04 PM
+
+(1) I put the AARM note that Put_Image should not be specified for 
+    language-defined scalar types after the new Implementation Permission, 
+    since it makes the most sense there. I note that it doesn't make sense to 
+    have both the Implementation Permission that one *can* specify Put_Image 
+    for nonscalar types, and a rule that one *cannot* specify Put_Image for 
+    scalar types. One of those has to be true because of existing rules! (And
+    we think it is the *cannot* rule.)
+
+(2) There's a number of images written in double quotes thus "[1, 2, 3]"; I'm 
+    dropping the quotes and setting these in the example font.
+
+(3) The introduction of the ImplAdvice says that it applies to all containers, 
+    but the list of bullets never gives any rule for Vectors! After discussing 
+    this with Steve, I added:
+
+        - Vector images should be consistent with the default image of 
+          an array type with the same index and component types.
+
+    I wrote it this way to avoid repeating discussion about named notation and 
+    what those names are. This is followed by an AARM note (like the others):
+
+          AARM Note: In particular, this means that the format is that
+          of a named array aggregate. We have no recommendation on how to 
+          handle empty elements; if the implementation can identify them, it
+          may wish to display them specially, but otherwise, they're just 
+          uninitialized elements.
+
+(4) In the e-mail thread from January, Steve says that we need to add a line 
+    saying that "The image of an empty holder should be "[]". We need to 
+    mention this because an empty holder isn't so much a null array but rather 
+    an array whose single element is "bottom", so the mapping is not obvious.
+
+(5) Also in that thread, there were two questions that I had that we deferred 
+    to the ARG meeting. I don't think I have the energy to ask them again, but
+     I mention them here so that if anyone cares they can ask to discuss them.
+
+   [A] I thought that the Implementation Advice on the containers should be a 
+   requirement, so that users can depend on getting a reasonably consistent 
+   Image from the containers. We make requirements about storage management, 
+   streaming, and various other things for the containers, so it seems strange 
+   that this is just advice. Additionally, I thought that the AARM note about 
+   making images relevant to clients rather than exposing implementation 
+   details probably should be Implementation Advice, since it is not 
+   necessarily an obvious "best practice". Hopefully, neither of these matter 
+   much in practice (implementers probably will do the right thing here).
+
+   [B] I thought we should consider specifying a result for some additional 
+   types, including "Imaginary" (from Ada.Numerics.Generic_Complex_Types) --
+   which is private but required to be completed with a real type; 
+   Ada.Calendar.Time, Ada.Real_Time.Time, Ada.Real_Time.Time_Span, and 
+   Ada.Execution_Time.CPU_Time. Steve had suggested saying something about 
+   System.Address and Ada.Tags.Tag. Again, implementations will hopefully do
+   something useful and obvious.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Thursday, April 11, 2019  11:34 PM
+
+(6) We had
+
+    For each language-defined type T that has a primitive
+    language-defined Image function ...
+
+And we also have a note that Put_Image not be changed for scalar types. This 
+wording conflicts, if only in theory (I didn't check for Image functions for 
+scalar types). So I added "nonscalar" to it:
+
+    For each language-defined nonscalar type T that has a primitive
+    language-defined Image function ...
 
 ****************************************************************

Questions? Ask the ACAA Technical Agent