1------------------------------------------------------------------------------
2--                                                                          --
3--                 GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS                 --
4--                                                                          --
5--              S Y S T E M . S T R I N G S . S T R E A M _ O P S           --
6--                                                                          --
7--                                 S p e c                                  --
8--                                                                          --
9--          Copyright (C) 2009-2018, Free Software Foundation, Inc.         --
10--                                                                          --
11-- GNAT is free software;  you can  redistribute it  and/or modify it under --
12-- terms of the  GNU General Public License as published  by the Free Soft- --
13-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
14-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
15-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
16-- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
17--                                                                          --
18-- As a special exception under Section 7 of GPL version 3, you are granted --
19-- additional permissions described in the GCC Runtime Library Exception,   --
20-- version 3.1, as published by the Free Software Foundation.               --
21--                                                                          --
22-- You should have received a copy of the GNU General Public License and    --
23-- a copy of the GCC Runtime Library Exception along with this program;     --
24-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
25-- <http://www.gnu.org/licenses/>.                                          --
26--                                                                          --
27-- GNAT was originally developed  by the GNAT team at  New York University. --
28-- Extensive contributions were provided by Ada Core Technologies Inc.      --
29--                                                                          --
30------------------------------------------------------------------------------
31
32--  This package provides subprogram implementations of stream attributes for
33--  the following types using a "block IO" approach in which the entire data
34--  item is written in one operation, instead of writing individual characters.
35
36--     Ada.Stream_Element_Array
37--     Ada.String
38--     Ada.Wide_String
39--     Ada.Wide_Wide_String
40--     System.Storage_Array
41
42--  Note: this routine is in Ada.Strings because historically it handled only
43--  the string types. It is not worth moving it at this stage.
44
45--  The compiler will generate references to the subprograms in this package
46--  when expanding stream attributes for the above mentioned types. Example:
47
48--     String'Output (Some_Stream, Some_String);
49
50--  will be expanded into:
51
52--     String_Output (Some_Stream, Some_String);
53--       or
54--     String_Output_Blk_IO (Some_Stream, Some_String);
55
56--  String_Output form is used if pragma Restrictions (No_String_Optimziations)
57--  is active, which requires element by element operations. The BLK_IO form
58--  is used if this restriction is not set, allowing block optimization.
59
60--  Note that if System.Stream_Attributes.Block_IO_OK is False, then the BLK_IO
61--  form is treated as equivalent to the normal case, so that the optimization
62--  is inhibited anyway, regardless of the setting of the restriction. This
63--  handles versions of System.Stream_Attributes (in particular the XDR version
64--  found in s-stratt-xdr) which do not permit block io optimization.
65
66pragma Compiler_Unit_Warning;
67
68with Ada.Streams;
69
70with System.Storage_Elements;
71
72package System.Strings.Stream_Ops is
73
74   -------------------------------------
75   -- Storage_Array stream operations --
76   -------------------------------------
77
78   function Storage_Array_Input
79     (Strm : access Ada.Streams.Root_Stream_Type'Class)
80      return System.Storage_Elements.Storage_Array;
81
82   function Storage_Array_Input_Blk_IO
83     (Strm : access Ada.Streams.Root_Stream_Type'Class)
84      return System.Storage_Elements.Storage_Array;
85
86   procedure Storage_Array_Output
87     (Strm : access Ada.Streams.Root_Stream_Type'Class;
88      Item : System.Storage_Elements.Storage_Array);
89
90   procedure Storage_Array_Output_Blk_IO
91     (Strm : access Ada.Streams.Root_Stream_Type'Class;
92      Item : System.Storage_Elements.Storage_Array);
93
94   procedure Storage_Array_Read
95     (Strm : access Ada.Streams.Root_Stream_Type'Class;
96      Item : out System.Storage_Elements.Storage_Array);
97
98   procedure Storage_Array_Read_Blk_IO
99     (Strm : access Ada.Streams.Root_Stream_Type'Class;
100      Item : out System.Storage_Elements.Storage_Array);
101
102   procedure Storage_Array_Write
103     (Strm : access Ada.Streams.Root_Stream_Type'Class;
104      Item : System.Storage_Elements.Storage_Array);
105
106   procedure Storage_Array_Write_Blk_IO
107     (Strm : access Ada.Streams.Root_Stream_Type'Class;
108      Item : System.Storage_Elements.Storage_Array);
109
110   --------------------------------------------
111   -- Stream_Element_Array stream operations --
112   --------------------------------------------
113
114   function Stream_Element_Array_Input
115     (Strm : access Ada.Streams.Root_Stream_Type'Class)
116      return Ada.Streams.Stream_Element_Array;
117
118   function Stream_Element_Array_Input_Blk_IO
119     (Strm : access Ada.Streams.Root_Stream_Type'Class)
120      return Ada.Streams.Stream_Element_Array;
121
122   procedure Stream_Element_Array_Output
123     (Strm : access Ada.Streams.Root_Stream_Type'Class;
124      Item : Ada.Streams.Stream_Element_Array);
125
126   procedure Stream_Element_Array_Output_Blk_IO
127     (Strm : access Ada.Streams.Root_Stream_Type'Class;
128      Item : Ada.Streams.Stream_Element_Array);
129
130   procedure Stream_Element_Array_Read
131     (Strm : access Ada.Streams.Root_Stream_Type'Class;
132      Item : out Ada.Streams.Stream_Element_Array);
133
134   procedure Stream_Element_Array_Read_Blk_IO
135     (Strm : access Ada.Streams.Root_Stream_Type'Class;
136      Item : out Ada.Streams.Stream_Element_Array);
137
138   procedure Stream_Element_Array_Write
139     (Strm : access Ada.Streams.Root_Stream_Type'Class;
140      Item : Ada.Streams.Stream_Element_Array);
141
142   procedure Stream_Element_Array_Write_Blk_IO
143     (Strm : access Ada.Streams.Root_Stream_Type'Class;
144      Item : Ada.Streams.Stream_Element_Array);
145
146   ------------------------------
147   -- String stream operations --
148   ------------------------------
149
150   function String_Input
151     (Strm : access Ada.Streams.Root_Stream_Type'Class)
152      return String;
153
154   function String_Input_Blk_IO
155     (Strm : access Ada.Streams.Root_Stream_Type'Class)
156      return String;
157
158   function String_Input_Tag
159     (Strm : access Ada.Streams.Root_Stream_Type'Class)
160      return String;
161   --  Same as String_Input_Blk_IO, except raises an exception for overly long
162   --  Strings. See expansion of Attribute_Input in Exp_Attr for details.
163
164   procedure String_Output
165     (Strm : access Ada.Streams.Root_Stream_Type'Class;
166      Item : String);
167
168   procedure String_Output_Blk_IO
169     (Strm : access Ada.Streams.Root_Stream_Type'Class;
170      Item : String);
171
172   procedure String_Read
173     (Strm : access Ada.Streams.Root_Stream_Type'Class;
174      Item : out String);
175
176   procedure String_Read_Blk_IO
177     (Strm : access Ada.Streams.Root_Stream_Type'Class;
178      Item : out String);
179
180   procedure String_Write
181     (Strm : access Ada.Streams.Root_Stream_Type'Class;
182      Item : String);
183
184   procedure String_Write_Blk_IO
185     (Strm : access Ada.Streams.Root_Stream_Type'Class;
186      Item : String);
187
188   -----------------------------------
189   -- Wide_String stream operations --
190   -----------------------------------
191
192   function Wide_String_Input
193     (Strm : access Ada.Streams.Root_Stream_Type'Class)
194      return Wide_String;
195
196   function Wide_String_Input_Blk_IO
197     (Strm : access Ada.Streams.Root_Stream_Type'Class)
198      return Wide_String;
199
200   procedure Wide_String_Output
201     (Strm : access Ada.Streams.Root_Stream_Type'Class;
202      Item : Wide_String);
203
204   procedure Wide_String_Output_Blk_IO
205     (Strm : access Ada.Streams.Root_Stream_Type'Class;
206      Item : Wide_String);
207
208   procedure Wide_String_Read
209     (Strm : access Ada.Streams.Root_Stream_Type'Class;
210      Item : out Wide_String);
211
212   procedure Wide_String_Read_Blk_IO
213     (Strm : access Ada.Streams.Root_Stream_Type'Class;
214      Item : out Wide_String);
215
216   procedure Wide_String_Write
217     (Strm : access Ada.Streams.Root_Stream_Type'Class;
218      Item : Wide_String);
219
220   procedure Wide_String_Write_Blk_IO
221     (Strm : access Ada.Streams.Root_Stream_Type'Class;
222      Item : Wide_String);
223
224   ----------------------------------------
225   -- Wide_Wide_String stream operations --
226   ----------------------------------------
227
228   function Wide_Wide_String_Input
229     (Strm : access Ada.Streams.Root_Stream_Type'Class)
230      return Wide_Wide_String;
231
232   function Wide_Wide_String_Input_Blk_IO
233     (Strm : access Ada.Streams.Root_Stream_Type'Class)
234      return Wide_Wide_String;
235
236   procedure Wide_Wide_String_Output
237     (Strm : access Ada.Streams.Root_Stream_Type'Class;
238      Item : Wide_Wide_String);
239
240   procedure Wide_Wide_String_Output_Blk_IO
241     (Strm : access Ada.Streams.Root_Stream_Type'Class;
242      Item : Wide_Wide_String);
243
244   procedure Wide_Wide_String_Read
245     (Strm : access Ada.Streams.Root_Stream_Type'Class;
246      Item : out Wide_Wide_String);
247
248   procedure Wide_Wide_String_Read_Blk_IO
249     (Strm : access Ada.Streams.Root_Stream_Type'Class;
250      Item : out Wide_Wide_String);
251
252   procedure Wide_Wide_String_Write
253     (Strm : access Ada.Streams.Root_Stream_Type'Class;
254      Item : Wide_Wide_String);
255
256   procedure Wide_Wide_String_Write_Blk_IO
257     (Strm : access Ada.Streams.Root_Stream_Type'Class;
258      Item : Wide_Wide_String);
259
260end System.Strings.Stream_Ops;
261