CVS difference for ais/ai-00026.txt

Differences between 1.3 and version 1.4
Log of other versions for file ais/ai-00026.txt

--- ais/ai-00026.txt	1999/08/31 22:53:53	1.3
+++ ais/ai-00026.txt	2000/04/14 01:45:05	1.4
@@ -1,4 +1,4 @@
-!standard A.12.1   (28-35)                            99-08-31  AI95-00026/04
+!standard A.12.1   (28-35)                            00-04-11  AI95-00026/05
 !class binding interpretation 95-06-25
 !status Corrigendum 2000 99-08-13
 !status WG9 approved 95-06-14
@@ -57,89 +57,108 @@
 
 A.12.1 describes the current index, or position, of a stream file, but
 does not indicate that its value is set by any operation other than
-Set_Index and Set_Mode.  The intent was to model the current index of a
-stream file after the current index of a direct file (except that the
-index counts stream elements rather than file elements, and except that a
+Set_Index and Set_Mode. Stream files also fail to describe their conceptual
+model.
+
+The intent was that stream files that support positioning are similar to
+direct files, and that other stream files are similar to sequential
+files. Both of these file types are described in A.8. Note, however, that
+A.8 specifically says it does not apply to stream files.
+
+Since stream files with positioning are intended to be similar to direct files,
+the current index of a stream file should be handled similarly (except that
+the index counts stream elements rather than file elements, and except that a
 stream file can be opened in or reset to mode Append_File).  The
 recommendation is based on the behavior described in A.8(4), A.8.2, and
-A.8.5 for direct files.  (The part of the recommendation about the
-raising of Use_Error echoes A.12.1(33).)
+A.8.5 for direct files.
 
-!corrigendum A.12.1(28)
+!corrigendum A.12.1(2)
 
-@drepl
-The subprograms Create, Open, Close, Delete, Reset, Mode, Name, Form,
-Is_Open, and End_of_File have the same effect as the corresponding
-subprograms in Sequential_IO (see A.8.2).
-@dby
-The subprograms Create, Open, Close, Delete, Mode, Name, Form, Is_Open, and
-End_of_File have the same effect as the corresponding subprograms in
-Sequential_IO (see A.8.2). In addition, if positioning is supported for the
-specified external file, a current index is maintained for the file. The
-current index is set to Size(File) +1 by Open and Create if Mode(File) =
-Append_File, and to 1 otherwise.
+@dinsb
+The library package Streams.Stream_IO has the following declaration:
+@dinst
+The elements of a stream file are stream elements.  If positioning is supported
+for the specified external file, a current index and current size are maintained
+for the file as described in A.8. If positioning is not supported, a current
+index is not maintained, and the current size is implementation-defined.
 
-!corrigendum A.12.1(29)
+!corrigendum A.12.1(28)
 
-@drepl
-The Stream function returns a Stream_Access result from a File_Type
-object, thus allowing the stream-oriented attributes Read, Write, Input, and
-Output to be used on the same file for multiple types.
-@dby
-The Stream function returns a Stream_Access result from a File_Type object,
-thus allowing the stream-oriented attributes Read, Write, Input, and Output
-to be used on the same file for multiple types. If positioning is supported for
-the File_Type object, then the default implementations of these attributes add
-one to the current index.
+@dinsa
+The subprograms Create, Open, Close, Delete, Reset, Mode, Name, Form, Is_Open,
+and End_of_File have the same effect as the corresponding subprograms in
+Sequential_IO (see A.8.2).
+@dinss
+The Set_Mode procedure changes the mode of the file. If the new mode is
+Append_File, the file is positioned to its end; otherwise, the position in the
+file is unchanged.
+
+The Flush procedure synchronizes the external file with the internal file (by
+flushing any internal buffers) without closing the file or changing the
+position. Mode_Error is propagated if the mode of the file is In_File.
 
 !corrigendum A.12.1(30)
 
-@drepl
+@dinsa
 The procedures Read and Write are equivalent to the corresponding
 operations in the package Streams. Read propagates Mode_Error if the mode of
 File is not In_File. Write propagates Mode_Error if the mode of File is not
 Out_File or Append_File. The Read procedure with a Positive_Count parameter
 starts reading at the specified index. The Write procedure with a Positive_
 Count parameter starts writing at the specified index.
+@dinst
+The Size function returns the current size of the file.
+
+!corrigendum A.12.1(31)
+
+@drepl
+The Index function returns the current file index, as a count (in stream
+elements) from the beginning of the file. The position of the first element
+in the file is 1.
 @dby
-The procedures Read and Write are equivalent to the corresponding operations in
-the package Streams. Read propagates Mode_Error if the mode of File is not
-In_File. Write propagates Mode_Error if the mode of File is not Out_File or
-Append_File. The Read procedure with a Positive_Count parameter starts reading
-at the specified index if positioning is supported for the file. The Write
-procedure with a Positive_Count parameter starts writing at the specified index
-if positioning is supported for the file. Read and Write increment the current
-index by the number of stream elements read or written. Or, for Read and Write
-with a Positive_Count parameter, the value of the current index is set to
-Positive_Count plus the number of stream elements read or written.
+The Index function returns the current index.
 
 !corrigendum A.12.1(32)
 
-@drepl
+@dinsa
 The Set_Index procedure sets the current index to the specified value.
-@dby
-The Set_Index procedure sets the current index to the specified value if
-positioning is supported for the file, otherwise Use_Error is raised.
+@dinss
+If positioning is supported for the external file, the current index is
+maintained as follows:
+@xbullet<For Open and Create, if the Mode parameter is Append_File, the current
+index is set to the current size of the file; otherwise, the current index is set
+to one.>
+@xbullet<For Reset, if the Mode parameter is Append_File, or no Mode parameter
+is given and the current mode is Append_File, the current index is set to the
+current size of the file plus one; otherwise, the current index is set to one.>
+@xbullet<For Set_Mode, if the new mode is Append_File, the current index is set
+to current size plus one; otherwise, the current index is unchanged.>
+@xbullet<For Read and Write without a Positive_Count parameter, the current
+index is incremented by the number of stream elements read or written.>
+@xbullet<For Read and Write with a Positive_Count parameter, the value of the
+current index is set to the value of the Positive_Count parameter plus the
+number of stream elements read or written.>
+
+!corrigendum A.12.1(34)
+
+@ddel
+The Size function returns the current size of the file.
 
 !corrigendum A.12.1(35)
 
-@drepl
+@ddel
 The Set_Mode procedure changes the mode of the file. If the new mode is
 Append_File, the file is positioned to its end; otherwise, the position in
 the file is unchanged.
-@dby
-The Set_Mode procedure changes the mode of the file. If the new mode is
-Append_File, the file is positioned to its end, and the current index is set to
-Size(File)+1; otherwise, the position in the file is unchanged.
 
-The Reset procedure can also change the mode and position of the file. If
-positioning is supported for the file, Reset with no Mode parameter sets the
-current index to Size(File)+1 if the current mode is Append_File, and to one
-otherwise. If positioning is not supported, the position is set to after the
-current end of the file if the mode is Append_File, and to the beginning
-otherwise. The procedure Reset with a Mode parameter is equivalent to a call to
-Set_Mode(File, Mode) followed by a call to Reset(File).
+!corrigendum A.12.1(36)
 
+@ddel
+The Flush procedure synchronizes the external file with the internal file (by
+flushing any internal buffers) without closing the file or changing the
+position. Mode_Error is propagated if the mode of the file is In_File.
+
+
 !ACATS test
 
 Create a C-Test to check that the current index is maintained properly.
@@ -213,5 +232,21 @@
 
 A.12.1(36):
 Unchanged.
+
+****************************************************************
+
+!from Editor 99-04-11
+
+At the recent ARG meeting, we determined to rearrange the paragraphs of this
+section to make the most possible sense. This was done by putting related
+items together. Traditionally, entities in Ada 95 packages are described in
+the order that they are declared in the package. However, this package is
+quite disorganized; Flush and Set_Mode have more in common with Open and Reset
+than they do with Size and Set_Index. We decided to break this meta rule
+rather than to rearrange the package.
+
+The meeting also added a reference to the description of the model of
+direct access files given in A.8. This is needed because A.8 says specifically
+that it does not apply to stream files.
 
 ****************************************************************

Questions? Ask the ACAA Technical Agent