1--  Copyright 2002-2014 Simon Wright <simon@pushface.org>
2
3--  This package is free software; you can redistribute it and/or
4--  modify it under terms of the GNU General Public License as
5--  published by the Free Software Foundation; either version 2, or
6--  (at your option) any later version. This package is distributed in
7--  the hope that it will be useful, but WITHOUT ANY WARRANTY; without
8--  even the implied warranty of MERCHANTABILITY or FITNESS FOR A
9--  PARTICULAR PURPOSE. See the GNU General Public License for more
10--  details. You should have received a copy of the GNU General Public
11--  License distributed with this package; see file COPYING.  If not,
12--  write to the Free Software Foundation, 59 Temple Place - Suite
13--  330, Boston, MA 02111-1307, USA.
14
15--  As a special exception, if other files instantiate generics from
16--  this unit, or you link this unit with other files to produce an
17--  executable, this unit does not by itself cause the resulting
18--  executable to be covered by the GNU General Public License.  This
19--  exception does not however invalidate any other reasons why the
20--  executable file might be covered by the GNU Public License.
21
22with Ada.Streams;
23
24package BC.Support.Memory_Streams is
25
26   pragma Preelaborate;
27
28   type Stream_Type
29     (Capacity : Ada.Streams.Stream_Element_Count)
30      is new Ada.Streams.Root_Stream_Type with private;
31   --  Provides an in-memory Stream.
32
33   function Length (Stream : Stream_Type) return Natural;
34   --  Returns the number of stream elements in Stream.
35
36   function Contents (Stream : Stream_Type)
37                     return Ada.Streams.Stream_Element_Array;
38   --  Returns a copy of the contents of Stream.
39
40   procedure Write_Contents (To : access Ada.Streams.Root_Stream_Type'Class;
41                             Stream : Stream_Type);
42   --  Writes the contents of Stream directly to the stream To.
43   --
44   --  If To is itself a memory Stream_Type, this will effectively
45   --  concatenate Stream to To.
46
47   procedure Read_Contents (From : access Ada.Streams.Root_Stream_Type'Class;
48                            Stream : in out Stream_Type);
49   --  Fills Stream directly from the stream From.
50   --
51   --  Reads the lesser of the Capacity of Stream and the "length" of
52   --  From.
53   --
54   --  The previous contents of Stream are lost.
55
56   procedure Set_Contents (From : Ada.Streams.Stream_Element_Array;
57                           Stream : in out Stream_Type);
58   --  Sets the contents of Stream to be the contents of array From.
59   --
60   --  Raises Ada.IO_Exceptions.End_Error if Stream is not
61   --  large enough to contain From.
62   --
63   --  The previous contents of Stream are lost.
64   --
65   --  Aimed at use with datagram sockets, where you have to take the
66   --  contents in one bite and can't know in advance how long the
67   --  datagram is.
68
69   procedure Reset (Stream : out Stream_Type);
70   --  Clears Stream.
71
72private
73
74   type Stream_Type
75     (Capacity : Ada.Streams.Stream_Element_Count)
76   is new Ada.Streams.Root_Stream_Type with record
77      Next_Write : Ada.Streams.Stream_Element_Count := 1;
78      Next_Read : Ada.Streams.Stream_Element_Count := 1;
79      Buffer : Ada.Streams.Stream_Element_Array (1 .. Capacity);
80   end record;
81
82   procedure Read
83     (Stream : in out Stream_Type;
84      Item   : out Ada.Streams.Stream_Element_Array;
85      Last   : out Ada.Streams.Stream_Element_Offset);
86   --  Removes Item'Length storage elements (or, as many as remain)
87   --  from Stream. Last is updated to the final index in Item that
88   --  was updated (normally, Item'Last). When Stream was already
89   --  empty, Item will be unchanged and Last will be set to
90   --  Item'First - 1.
91
92   procedure Write
93     (Stream : in out Stream_Type;
94      Item   : in Ada.Streams.Stream_Element_Array);
95   --  Adds Item to Stream. Raises Ada.IO_Exceptions.End_Error on
96   --  overrun.
97
98end BC.Support.Memory_Streams;
99