ADDED   natools-accumulators.ads
Index: natools-accumulators.ads
==================================================================
--- natools-accumulators.ads
+++ natools-accumulators.ads
@@ -0,0 +1,90 @@
+------------------------------------------------------------------------------
+-- Copyright (c) 2011, Natacha Porté                                        --
+--                                                                          --
+-- Permission to use, copy, modify, and distribute this software for any    --
+-- purpose with or without fee is hereby granted, provided that the above   --
+-- copyright notice and this permission notice appear in all copies.        --
+--                                                                          --
+-- THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES --
+-- WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF         --
+-- MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR  --
+-- ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES   --
+-- WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN    --
+-- ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF  --
+-- OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           --
+------------------------------------------------------------------------------
+
+------------------------------------------------------------------------------
+-- Natools.Accumulators is a collection of interfaces for data structures   --
+-- that allow efficient accumulation of data.                               --
+--                                                                          --
+-- String_Accumulator is meant for creation of long strings through         --
+-- repeated calls of Append, and later retrieval of the full buffer through --
+-- one of the To_String subprograms. Length, Tail and Unappend are          --
+-- helper utilities that might not be very efficient but can occasionnally  --
+-- be useful. Hard_Reset and Soft_Reset both clear the internal state, with --
+-- Soft_Reset aimed for speed while Hard_Reset aims for best memory release --
+--                                                                          --
+-- String_Accumulator_Stack adds a stack structure on top of                --
+-- String_Accumulator, to allow temporary substrings to be created using    --
+-- similar facilities. All operations on String_Accumulator except          --
+-- Hard_Reset and Soft_Reset, when applied to String_Accumulator_Stack, are --
+-- meant to be forwarded to the top accumulator of the stack. Push and Pop  --
+-- change the stack state, while Hard_Reset and Soft_Reset apply to the     --
+-- whole stack, with the same semantics as for String_Accumulator.          --
+------------------------------------------------------------------------------
+
+package Natools.Accumulators is
+   pragma Pure (Accumulators);
+
+   type String_Accumulator is interface;
+
+   procedure Append (To : in out String_Accumulator; Text : String)
+      is abstract;
+      --  Append the given String to the internal buffer
+
+   procedure Hard_Reset (Acc : in out String_Accumulator)
+      is abstract;
+      --  Empty the internal buffer and free all possible memory
+
+   function Length (Acc : String_Accumulator) return Natural
+      is abstract;
+      --  Return the length of the internal buffer
+
+   procedure Soft_Reset (Acc : in out String_Accumulator)
+      is abstract;
+      --  Empty the internal buffer for reuse
+
+   function Tail (Acc : String_Accumulator; Size : Natural) return String
+      is abstract;
+      --  Return the last characters from the internal buffer
+
+   function To_String (Acc : String_Accumulator) return String
+      is abstract;
+      --  Output the whole internal buffer as a String
+
+   procedure To_String (Acc : String_Accumulator; Output : out String)
+      is abstract;
+      --  Write the whole internal buffer into the String, which must be
+      --    large enough.
+
+   procedure Unappend (From : in out String_Accumulator; Text : String)
+      is abstract;
+      --  Remove the given suffix from the internal buffer
+      --  Do nothing if the given text is not a prefix the internal buffer
+
+
+
+   type String_Accumulator_Stack is interface and String_Accumulator;
+
+   procedure Push (Acc : in out String_Accumulator_Stack)
+      is abstract;
+      --  Push the current internal buffer and start with an empty one
+
+   procedure Pop (Acc : in out String_Accumulator_Stack)
+      is abstract;
+      --  Drop the current internal buffer and use the previsouly pushed one
+      --     instead
+      --  Raise Program_Error when trying to pop the last internal buffer
+
+end Natools.Accumulators;