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-2013, 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   procedure String_Output
159     (Strm : access Ada.Streams.Root_Stream_Type'Class;
160      Item : String);
161
162   procedure String_Output_Blk_IO
163     (Strm : access Ada.Streams.Root_Stream_Type'Class;
164      Item : String);
165
166   procedure String_Read
167     (Strm : access Ada.Streams.Root_Stream_Type'Class;
168      Item : out String);
169
170   procedure String_Read_Blk_IO
171     (Strm : access Ada.Streams.Root_Stream_Type'Class;
172      Item : out String);
173
174   procedure String_Write
175     (Strm : access Ada.Streams.Root_Stream_Type'Class;
176      Item : String);
177
178   procedure String_Write_Blk_IO
179     (Strm : access Ada.Streams.Root_Stream_Type'Class;
180      Item : String);
181
182   -----------------------------------
183   -- Wide_String stream operations --
184   -----------------------------------
185
186   function Wide_String_Input
187     (Strm : access Ada.Streams.Root_Stream_Type'Class)
188      return Wide_String;
189
190   function Wide_String_Input_Blk_IO
191     (Strm : access Ada.Streams.Root_Stream_Type'Class)
192      return Wide_String;
193
194   procedure Wide_String_Output
195     (Strm : access Ada.Streams.Root_Stream_Type'Class;
196      Item : Wide_String);
197
198   procedure Wide_String_Output_Blk_IO
199     (Strm : access Ada.Streams.Root_Stream_Type'Class;
200      Item : Wide_String);
201
202   procedure Wide_String_Read
203     (Strm : access Ada.Streams.Root_Stream_Type'Class;
204      Item : out Wide_String);
205
206   procedure Wide_String_Read_Blk_IO
207     (Strm : access Ada.Streams.Root_Stream_Type'Class;
208      Item : out Wide_String);
209
210   procedure Wide_String_Write
211     (Strm : access Ada.Streams.Root_Stream_Type'Class;
212      Item : Wide_String);
213
214   procedure Wide_String_Write_Blk_IO
215     (Strm : access Ada.Streams.Root_Stream_Type'Class;
216      Item : Wide_String);
217
218   ----------------------------------------
219   -- Wide_Wide_String stream operations --
220   ----------------------------------------
221
222   function Wide_Wide_String_Input
223     (Strm : access Ada.Streams.Root_Stream_Type'Class)
224      return Wide_Wide_String;
225
226   function Wide_Wide_String_Input_Blk_IO
227     (Strm : access Ada.Streams.Root_Stream_Type'Class)
228      return Wide_Wide_String;
229
230   procedure Wide_Wide_String_Output
231     (Strm : access Ada.Streams.Root_Stream_Type'Class;
232      Item : Wide_Wide_String);
233
234   procedure Wide_Wide_String_Output_Blk_IO
235     (Strm : access Ada.Streams.Root_Stream_Type'Class;
236      Item : Wide_Wide_String);
237
238   procedure Wide_Wide_String_Read
239     (Strm : access Ada.Streams.Root_Stream_Type'Class;
240      Item : out Wide_Wide_String);
241
242   procedure Wide_Wide_String_Read_Blk_IO
243     (Strm : access Ada.Streams.Root_Stream_Type'Class;
244      Item : out Wide_Wide_String);
245
246   procedure Wide_Wide_String_Write
247     (Strm : access Ada.Streams.Root_Stream_Type'Class;
248      Item : Wide_Wide_String);
249
250   procedure Wide_Wide_String_Write_Blk_IO
251     (Strm : access Ada.Streams.Root_Stream_Type'Class;
252      Item : Wide_Wide_String);
253
254end System.Strings.Stream_Ops;
255