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

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

--- ai12s/ai12-0329-1.txt	2019/04/06 04:42:02	1.1
+++ ai12s/ai12-0329-1.txt	2019/04/10 01:47:55	1.2
@@ -1,8 +1,7 @@
-!standard 13.13.1(12/5)                                  19-04-05  AI12-0329-1/01
-!standard 13.13.1(13/5)
-!standard 13.13.1(18/5)
-!standard 13.13.1(26/5)
+!standard 13.13.1(9/5)                                  19-04-09  AI12-0329-1/02
+!standard 13.13.1(9.1/5)
 !class Amendment 19-04-05
+!status ARG Approved 9-0-2  19-04-09
 !status work item 19-04-05
 !status received 19-04-03
 !priority Low
@@ -10,8 +9,8 @@
 !subject Naming of FIFO_Streams packages
 !summary
 
-The package family is named Storage, with children FIFO and Bounded_FIFO.
-The interface type is named Storage_Stream_Type.
+The package family is named Storage, with children Unbounded and Bounded.
+The abstract type is named Storage_Stream_Type.
 
 !problem
 
@@ -19,7 +18,8 @@
 
 (1) There's nothing about the interface that limits it to FIFO operations.
 It *is* limited to in-memory operations, so perhaps that property should
-be emphasized with the name.
+be emphasized with the name. Additionally, a Stream is inherently FIFO,
+so its weird to emphasize that property.
 
 (2) The use of Unbounded_<something> is inconsistent with the names used
 for the containers.
@@ -36,9 +36,24 @@
 
 !wording
 
-** TBD. (There is quite a bit of wording to change, as Brad noted in his 
-review, but it's not worth anyone's time to reproduce that here, especially
-before the names are chosen.
+The root package of this subsystem is called
+   Ada.Streams.Storage
+with a type
+   Storage_Stream_Type
+
+There are two child packages, Ada.Streams.Storage.Unbounded and 
+Ada.Streams.Storage.Bounded. The type names in the children are not changed;
+they remain Stream_Type.
+
+See !corrigendum below for the detailed wording changes.
+
+!discussion
+
+"Unbounded_String" is an exception to the meta-rule that we don't use 
+"Unbounded" in names, but that clearly couldn't have been called "String",
+so some other name was required.
+
+We orginally proposed:
 
    Ada.Streams.Storage
       Storage_Stream_Type
@@ -47,15 +62,15 @@
       Ada.Streams.Storage.Bounded_FIFO
           Stream_Type
 
-!discussion
+But that was ultimately rejected as a stream is inherently FIFO, so that also
+is redundant information. Once we drop that, we have no name for the concrete
+child implementation level at all. It doesn't add anything, since the parent 
+defines the necessary details. Thus, we dropped back to the Unbounded and
+Bounded names without any qualification.
 
-"Unbounded_String" is an exception to the meta-rule that we don't use 
-"Unbounded" in names, but that clearly couldn't have been called "String",
-so some other name was required. That isn't an issue in this case.
-
 Ideally, the names chosen for language-defined packages would work well for
 both the use-adverse and the use-lovers of the Ada community. Note that 
-everyone has to name the full expanded package name in the context clause,
+everyone has to write the full expanded package name in the context clause,
 so shorter, less redundant names help everyone. It does pay to repeat some
 information in the type names, as use-lovers will not have any context to 
 make the name clear.
@@ -63,14 +78,13 @@
 E-Mail discussions seemed to settle on naming this family of packages
 "Storage" in some way, based on the existing Storage_IO package.
 
-We also need to consider the type names, particularly of the interface.
+We also need to consider the type names, particularly of the abstract type.
 
 Some people preferred to repeat Stream in each of the package names. Your
 author thinks this is rather redundant (he's sick and tired of having to
 write Ada.Strings.Unbounded_Strings.Unbounded_String, and this would be
 worse), but for the record:
 
-
    Ada.Streams.Storage_Streams
       Storage_Stream_Type
       Ada.Streams.Storage_Streams.FIFO_Streams
@@ -81,15 +95,160 @@
 We also considered "Buffers" rather than "Storage" (but Ada already uses
 "Storage" for this use), 
 
+!corrigendum 13.13.1(9)
+
+@dinsa
+The Write operation appends Item to the specified stream.
+@dinss
+Three additional packages provide stream implementations that do not make 
+use of any file operations. These packages provide the same operations,
+with Streams.Storage providing an abstract interface, and two child 
+packages providing implementations of that interface. The difference is that 
+for Streams.Storage.Bounded, the maximum storage is bounded.
+
+The library package Ada.Streams.Storage has the following declaration:
+
+@xcode<@b<package> Ada.Streams.Storage
+   @b<with> Pure, Nonblocking @b<is>>
+
+@xcode<   @b<type> Storage_Stream_Type @b<is abstract new> Root_Stream_Type @b<with private>;>
+
+@xcode<   @b<function> Element_Count (Stream : Storage_Stream_Type)
+      @b<return> Stream_Element_Count @b<is abstract>;>
+
+@xcode<   @b<procedure> Clear (Stream : @b<in out> Storage_Stream_Type) @b<is abstract>;>
+
+@xcode<@b<private>
+   ... -- @ft<@i<not specified by the language>>
+@b<end> Ada.Streams.Storage;>
+
+The library package Ada.Streams.Storage.Unbounded has the following 
+declaration:
+
+@xcode<@b<package> Ada.Streams.Storage.Unbounded
+   @b<with> Prelaborated, Nonblocking @b<is>>
+
+@xcode<   @b<type> Stream_Type @b<is new> Storage_Stream_Type @b<with private>
+      @b<with> Default_Initial_Condition =@>
+         Element_Count (Stream_Type) = 0;>
+
+@xcode<   @b<overriding>
+   @b<procedure> Read (
+      Stream : @b<in out> Stream_Type;
+      Item   : @b<out> Stream_Element_Array;
+      Last   : @b<out> Stream_Element_Offset)
+      @b<with> Post =@>
+         (@b<declare>
+            Num_Read : @b<constant> Stream_Element_Count :=
+               Stream_Element_Count'Min 
+                  (Element_Count(Stream)'Old, Item'Length);
+          @b<begin>
+                Last = Num_Read + Item'First - 1
+             @b<and>
+                Element_Count (Stream) = 
+                   Element_Count (Stream)'Old - Num_Read);>
+
+@xcode<   @b<overriding>
+   @b<procedure> Write (
+      Stream : @b<in out> Stream_Type;
+      Item   : @b<in> Stream_Element_Array)
+      @b<with> Post =@>
+         Element_Count (Stream) =
+         Element_Count (Stream)'Old + Item'Length;>
+
+@xcode<   @b<overriding>
+   @b<function> Element_Count (Stream : Stream_Type)
+      @b<return> Stream_Element_Count;>
+
+@xcode<   @b<overriding>
+   @b<procedure> Clear (Stream : @b<in out> Stream_Type)
+      @b<with> Post =@> Element_Count (Stream) = 0;>
+
+@xcode<@b<private>
+   ... -- @ft<@i<not specified by the language>>
+@b<end> Ada.Streams.Storage.Unbounded;>
+
+The library package Ada.Streams.Storage.Bounded has the following
+declaration:
+
+@xcode<@b<package> Ada.Streams.Storage.Bounded
+   @b<with> Pure, Nonblocking @b<is>>
+
+@xcode<   @b<type> Stream_Type (Max_Elements : Stream_Element_Count) 
+      @b<is new> Storage_Stream_Type @b<with private>
+         @b<with> Default_Initial_Condition =@>
+            Element_Count (Stream_Type) = 0;>
+
+@xcode<   @b<overriding>
+   @b<procedure> Read (
+      Stream : @b<in out> Stream_Type;
+      Item   : @b<out> Stream_Element_Array;
+      Last   : @b<out> Stream_Element_Offset)
+      @b<with> Post =@>
+         (@b<declare>
+            Num_Read : @b<constant> Stream_Element_Count :=
+               Stream_Element_Count'Min 
+                  (Element_Count(Stream)'Old, Item'Length);
+          @b<begin>
+                Last = Num_Read + Item'First - 1
+             @b<and>
+                Element_Count (Stream) = 
+                   Element_Count (Stream)'Old - Num_Read);>
+
+@xcode<   @b<overriding>
+   @b<procedure> Write (
+      Stream : @b<in out> Stream_Type;
+      Item   : @b<in> Stream_Element_Array)
+      @b<with> Pre =@>
+              Element_Count (Stream) + Item'Length <= Stream.Max_Elements
+              @b<or else> (@b<raise> Constraint_Error),
+           Post =@>
+              Element_Count (Stream) =
+              Element_Count (Stream)'Old + Item'Length;>
+ 
+@xcode<   @b<overriding>
+   @b<function> Element_Count (Stream : Stream_Type)
+      @b<return> Stream_Element_Count
+      @b<with> Post =@> Element_Count'Result <= Stream.Max_Elements;>
+
+@xcode<   @b<overriding>
+   @b<procedure> Clear (Stream : @b<in out> Stream_Type)
+      @b<with> Post =@> Element_Count (Stream) = 0;>
+
+@xcode<@b<private>
+   ... -- @ft<@i<not specified by the language>>
+@b<end> Ada.Streams.Storage.Bounded;>
+
+The Element_Count functions return the number of stream elements
+that are available for reading from the given stream.
+
+The Read and Write procedures behave as described for package 
+Ada.Streams above.
+Stream elements are read in FIFO (first-in, first-out) order; stream
+elements are available for reading immediately after they are written.
+
+The Clear procedures remove any available stream elements from the given
+stream.
+
+!corrigendum 13.13.1(9.1/1)
+
+@dinsa
+If Stream_Element'Size is not a multiple of System.Storage_Unit, then the 
+components of Stream_Element_Array need not be aliased. 
+@dinst
+@s8<@i<Implementation Advice>>
+
+Streams.Storage.Bounded.Stream_Type objects should be implemented without
+implicit pointers or dynamic allocation.
+
+
 !ASIS
 
-[Not sure. It seems like some new capabilities might be needed,
-but I didn't check - Editor.]
+No change is needed.
 
 !ACATS test
 
-ACATS B- and C-Tests are needed to check that the new capabilities are
-supported.
+Any tests for the original AI (AI12-0293-1) would apply here as well.
 
 !appendix
 

Questions? Ask the ACAA Technical Agent