CVS difference for ai12s/ai12-0340-1.txt
--- ai12s/ai12-0340-1.txt 2019/10/30 06:13:35 1.2
+++ ai12s/ai12-0340-1.txt 2019/11/09 04:58:07 1.3
@@ -1,11 +1,16 @@
-!standard A.4.12(0) 19-10-29 AI12-0340-1/01
+!standard A.4.12(0) 19-10-29 AI12-0340-1/02
!standard 4.10(3.1/5)
-!standard A.10(3.2/5)
-!standard A.10(6/5)
-!standard A.10(25.2/5)
-!standard A.10(28/5)
-!standard A.10(31/5)
+!standard 4.10(3.2/5)
+!standard 4.10(6/5)
+!standard 4.10(25.2/5)
+!standard 4.10(28/5)
+!standard 4.10(31/5)
+!standard 4.10(41/5)
+!standard H.4(23.2/5)
+!standard H.4(23.11/5)
!class Amendment 19-09-03
+!status Amendment 1-2012 19-10-29
+!status ARG Approved 10-0-0 19-10-05
!status work item 19-03-03
!status received 19-06-20
!priority Medium
@@ -37,11 +42,12 @@
language-defined string type. The types used to save and retrieve the text
need not be the same.
-The text buffer packages have the following declarations:
+The text buffer library packages have the following declarations:
[Author's note: See the !discussion for discussion of design issues.]
- package Ada.Strings.Text_Buffers is
+ package Ada.Strings.Text_Buffers
+ with Pure, Nonblocking, Global => null is
type Text_Buffer_Count is range 0 .. *implementation-defined*;
@@ -127,6 +133,8 @@
Character_Count (Buffer) =
Character_Count (Buffer)'Old + New_Line_Count;
+ private
+ ... -- not specified by the language
end Ada.Strings.Text_Buffers;
package Ada.Strings.Text_Buffers.Unbounded
@@ -141,7 +149,8 @@
-- Nonabstract overridings of each inherited operation are declared here.
-
+ private
+ ... -- not specified by the language
end Ada.Strings.Text_Buffers.Unbounded;
package Ada.Strings.Text_Buffers.Bounded
@@ -182,9 +191,9 @@
A call to Get, Wide_Get, or Wide_Wide_Get returns the same sequence of
characters as was present in the calls that stored the characters into the buffer.
For a call to Get, if any character in the sequence is not defined in Character,
-the result is implementation-defined. Similarly, for a call to Wide_Get, if
+the result is implementation defined. Similarly, for a call to Wide_Get, if
any character in the sequence is not defined in Wide_Character, the result is
-implementation-defined.
+implementation defined.
AARM Ramification: Even when the result is implementation-defined, the
postconditions on the various Get routines require the length of the returned
@@ -225,30 +234,36 @@
Replace 4.10(25.2/5) with:
- Wide_Wide_Image calls S'Put_Image passing Arg (which will typically store
- a sequence of character values out in a text buffer) and then returns the
+ S'Wide_Wide_Image calls S'Put_Image passing Arg (which will typically store
+ a sequence of character values in a text buffer) and then returns the
result of retrieving the contents of that buffer with Wide_Wide_Get. The
- lower bound of the result is 1.
+ lower bound of the result is one.
Replace 4.10(28/5) with:
- Wide_Image calls S'Put_Image passing Arg (which will typically store
- a sequence of character values out in a text buffer) and then returns the
+ S'Wide_Image calls S'Put_Image passing Arg (which will typically store
+ a sequence of character values in a text buffer) and then returns the
result of retrieving the contents of that buffer with Wide_Get. The
- lower bound of the result is 1.
+ lower bound of the result is one.
Replace 4.10(31/5) with:
- Image calls S'Put_Image passing Arg (which will typically store
- a sequence of character values out in a text buffer) and then returns the
+ S'Image calls S'Put_Image passing Arg (which will typically store
+ a sequence of character values in a text buffer) and then returns the
result of retrieving the contents of that buffer with Get. The
- lower bound of the result is 1.
+ lower bound of the result is one.
[Author's note: The correspondence between Wide_Wide_Image, Wide_Image, and
Image is now implicit in the definitions of Put_Image and the text buffer
retrieval routines. That should make it easier to use similar definitions
elsewhere in the future.]
+Replace 4.10(41/5) with:
+
+ Additional spaces (Wide_Wide_Characters with position 32), and calls to the
+ New_Line operation of a text buffer, may be inserted to improve readability
+ of the generated image.
+
Replace H.4(23.2/5) with:
Max_Image_Length
@@ -325,8 +340,9 @@
Note that we don't define the internal storage format, rather just talking
about storage of characters. The Get routines are responsible for converting
the internal format to the appropriate output format. In particular, an
-implementation could use UTF8 storage to save space, or Wide_Wide_String
-storage to be simple.
+implementation could use an extended UTF8 storage to save space (extended as
+all Wide_Wide_Characters need to be storable, UTF8 proper only encodes a
+maximum of21 bits), or Wide_Wide_String storage to be simple.
----
@@ -357,6 +373,193 @@
is the same or longer otherwise. That doesn't seem necessary for existing
implementations, so we didn't add the complication.
+!corrigendum 4.10(0)
+
+@dinsc
+** See the conflict file **
+
+!corrigendum A.4.12(0)
+
+@dinsc
+A universal text buffer can be used to save and retrieve text of any
+language-defined string type. The types used to save and retrieve the text
+need not be the same.
+
+The text buffer library packages have the following declarations:
+
+@xcode<@b<package> Ada.Strings.Text_Buffers
+ @b<with> Pure, Nonblocking, Global =@> @b<null is>>
+
+@xcode< @b<type> Text_Buffer_Count @b<is range> 0 .. @ft<@i<implementation-defined>>;>
+
+@xcode< New_Line_Count : @b<constant> Text_Buffer_Count := @ft<@i<implementation-defined>>;>
+
+@xcode< @b<type> Root_Buffer_Type @b<is abstract tagged private>;>
+
+@xcode< @b<function> Character_Count (Buffer : Root_Buffer_Type)
+ @b<return> Text_Buffer_Count @b<is abstract>;>
+
+@xcode< @b<procedure> Clear (Buffer : Root_Buffer_Type) @b<is abstract>
+ @b<with> Post'Class =@> Character_Count (Buffer) = 0;>
+
+@xcode< @b<procedure> Get (
+ Buffer : @b<in out> Root_Buffer_Type;
+ Item : @b<out> String;
+ Last : @b<out> Natural) @b<is abstract>
+ @b<with> Post'Class =@>
+ (@b<declare>
+ Num_Read : @b<constant> Text_Buffer_Count :=
+ Text_Buffer_Count'Min
+ (Character_Count(Buffer)'Old, Item'Length);
+ @b<begin>
+ Last = Num_Read + Item'First - 1 @b<and then>
+ Character_Count (Buffer) =
+ Character_Count (Buffer)'Old - Num_Read);>
+
+@xcode< @b<procedure> Wide_Get (
+ Buffer : @b<in out> Root_Buffer_Type;
+ Item : @b<out> Wide_String;
+ Last : @b<out> Natural) @b<is abstract>
+ @b<with> Post'Class =@>
+ (@b<declare>
+ Num_Read : @b<constant> Text_Buffer_Count :=
+ Text_Buffer_Count'Min
+ (Character_Count(Buffer)'Old, Item'Length);
+ @b<begin>
+ Last = Num_Read + Item'First - 1 @b<and then>
+ Character_Count (Buffer) =
+ Character_Count (Buffer)'Old - Num_Read);>
+
+@xcode< @b<procedure> Wide_Wide_Get (
+ Buffer : @b<in out> Root_Buffer_Type;
+ Item : @b<out> Wide_Wide_String;
+ Last : @b<out> Natural) @b<is abstract>
+ @b<with> Post'Class =@>
+ (@b<declare>
+ Num_Read : @b<constant> Text_Buffer_Count :=
+ Text_Buffer_Count'Min
+ (Character_Count(Buffer)'Old, Item'Length);
+ @b<begin>
+ Last = Num_Read + Item'First - 1 @b<and then>
+ Character_Count (Buffer) =
+ Character_Count (Buffer)'Old - Num_Read);>
+
+@xcode< @b<function> End_of_Line (Buffer : @b<in> Root_Buffer_Type)
+ @b<return> Boolean @b<is abstract>;>
+
+@xcode< @b<procedure> Put (
+ Buffer : @b<in out> Root_Buffer_Type;
+ Item : @b<in> String) @b<is abstract>
+ @b<with> Post'Class =@>
+ Character_Count (Buffer) =
+ Character_Count (Buffer)'Old + Item'Length;>
+
+@xcode< @b<procedure> Wide_Put (
+ Buffer : @b<in out> Root_Buffer_Type;
+ Item : @b<in> Wide_String) @b<is abstract>
+ @b<with> Post'Class =@>
+ Character_Count (Buffer) =
+ Character_Count (Buffer)'Old + Item'Length;>
+
+@xcode< @b<procedure> Wide_Wide_Put (
+ Buffer : @b<in out> Root_Buffer_Type;
+ Item : @b<in> Wide_Wide_String) @b<is abstract>
+ @b<with> Post'Class =@>
+ Character_Count (Buffer) =
+ Character_Count (Buffer)'Old + Item'Length;>
+
+@xcode< @b<procedure> New_Line (Buffer : @b<in out> Root_Buffer_Type)
+ @b<is abstract>
+ @b<with> Post'Class =@>
+ Character_Count (Buffer) =
+ Character_Count (Buffer)'Old + New_Line_Count;>
+
+@xcode<@b<private>
+ ... --@ft<@i< not specified by the language>>
+@b<end> Ada.Strings.Text_Buffers;>
+
+@xcode<@b<package> Ada.Strings.Text_Buffers.Unbounded
+ @b<with> Preelaborate, Nonblocking, Global =@> @b<null is>>
+
+@xcode< @b<type> Buffer_Type @b<is new> Root_Buffer_Type @b<with private>
+ @b<with> Default_Initial_Condition =@>
+ Character_Count (Buffer_Type) = 0;>
+
+@xcode< --@ft<@i< Nonabstract overridings of each inherited operation are declared here.>>>
+
+@xcode<@b<private>
+ ... --@ft<@i< not specified by the language>>
+@b<end> Ada.Strings.Text_Buffers.Unbounded;>
+
+@xcode<@b<package> Ada.Strings.Text_Buffers.Bounded
+ @b<with> Pure, Nonblocking, Global =@> @b<null is>>
+
+@xcode< @b<type> Buffer_Type (Max_Characters : Text_Buffer_Count)
+ @b<is new> Root_Buffer_Type @b<with private>
+ @b<with> Default_Initial_Condition =@>
+ Character_Count (Buffer_Type) = 0;>
+
+@xcode< --@ft<@i< Nonabstract overridings of each inherited operation are declared here.>>
+ --@ft<@i< For each of Put, Wide_Put, and Wide_Wide_Put,>>
+ -- Pre =@> (@b<if> Character_Count (Buffer) + Item'Length @> Buffer.Max_Characters
+ -- @b<then raise> Constraint_Error),
+ --@ft<@i< is added to the declaration. For New_Line,>>
+ -- Pre =@> (@b<if> Character_Count (Buffer) + New_Line_Count @> Buffer.Max_Characters
+ -- @b<then raise> Constraint_Error),
+ --@ft<@i< is added to the declaration.>>>
+
+@xcode<@b<private>
+ ... --@ft<@i< not specified by the language>>
+@b<end> Ada.Strings.Text_Buffers.Bounded;>
+
+Character_Count returns the number of characters currently stored in a text
+buffer.
+
+New_Line stores New_Line_Count characters that represent a new line into a text
+buffer. End_of_Line returns True if the next characters to be retrieved from the
+text buffer represent a new line.
+
+A call to Put, Wide_Put, or Wide_Wide_Put stores a sequence of characters into the
+text buffer.
+
+A call to Get, Wide_Get, or Wide_Wide_Get returns the same sequence of
+characters as was present in the calls that stored the characters into the buffer.
+For a call to Get, if any character in the sequence is not defined in Character,
+the result is implementation defined. Similarly, for a call to Wide_Get, if
+any character in the sequence is not defined in Wide_Character, the result is
+implementation defined.
+
+@s8<@i<Implementation Advice>>
+
+Bounded buffer objects should be implemented without dynamic allocation.
+
+
+!corrigendum H.4(23)
+
+@dinsa
+@xhang<@xterm<No_Reentrancy>During the execution of a subprogram by a task,
+no other task invokes the same subprogram.>
+@dinss
+@s8<@i<Dynamic Semantics>>
+
+The following @i<restriction_parameter_>@fa<identifier> is language defined:
+
+@xhang<@xterm<Max_Image_Length>
+Specifies the maximum length for the result of an Image, Wide_Image, or
+Wide_Wide_Image attribute. Violation of this restriction results in the
+raising of Program_Error at the point of the invocation of an image
+attribute.>
+
+!corrigendum H.4(23.8/2)
+
+@dinsa
+@xbullet<Max_Tasks =@> 0.>
+@dinst
+If a Max_Image_Length restriction applies to any compilation unit in
+the partition, then for any subtype S, S'Image, S'Wide_Image, and
+S'Wide_Wide_Image shall be implemented within that partition without
+any dynamic allocation.
+
!ASIS
No ASIS changes needed.
@@ -868,6 +1071,73 @@
> So do folks feel we should move in this direction for Put_Image?
I also agree that this seems like a step in the right direction.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Friday, November 8, 2019 6:30 PM
+
+4.10(41/5) (an Implementation Permission) reads:
+
+* Additional spaces, carriage returns, and line feeds (Wide_Wide_Characters
+ with positions 32, 10, and 13), may be inserted to improve readability of
+ the generated image.
+
+AI12-0340-1 describes all writing to go through a Text_Buffer, and text
+buffers define a New_Line operation in order to abstract line breaks.
+Therefore, this permission should be worded in terms of additional calls
+to the New_Line operation in order to have the maximum abstraction and
+portability. (We don't want implementations writing carriage returns on
+Linux, for instance.)
+
+Perhaps this should be worded something like:
+
+* Additional spaces (Wide_Wide_Characters with position 32), and calls to the
+ New_Line operation of a text buffer, may be inserted to improve readability
+ of the generated image.
+
+Thoughts? Improvements?
+
+****************************************************************
+
+From: Tucker Taft
+Sent: Friday, November 8, 2019 8:32 PM
+
+Makes sense.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Friday, November 8, 2019 9:27 PM
+
+I've noticed a few glitches in the Text_Buffer specifications:
+
+(1) The word "library" is missing from the lead-in:
+
+ The text buffer {library} packages have the following declarations:
+
+This is needed to match the lead-ins in nearby sections. (These vary somewhat
+across the RM, I picked the lead-in used for Strings.Encoding and other nearby
+packages.)
+
+(2) The classification is missing for the parent package Strings.Text_Buffers,
+this should be:
+
+package Ada.Strings.Text_Buffers
+ with Pure, Nonblocking, Global => null is
+
+(3) The private parts are missing from all three packages. These should be:
+
+ private
+ ... -- not specified by the language
+ end Ada.Strings.Text_Buffers;
+
+[with the appropriate end name, of course].
+
+(4) The classification of the Unbounded package is written "Preelaborated",
+while it should be "Preelaborate".
+
+As always, consider these things my Editorial Review of the AI.
****************************************************************
Questions? Ask the ACAA Technical Agent